Getting started with ANS

Normalized ANS writes the composited objects into the JSON properties using a reference syntax shorthand. It is called reference syntax because the JSON that represents the composited object contains a key of type: reference and a key of referent with the arc id and arc type of the target object. While typically not available to view, this reference syntax is used when the systems sends the ANS through the APIs for create or update operations.

The left side shows an Arc XP author written into the credits.by field as a reference in a parent object. On the right, the same credits.by field is denormalized when the Content API returns the parent object.

The second presentation is denormalized, or inflated, ANS. The content retrieved from Arc XP undergoes a process where references are substituted with the complete representation of the composited objects, which results in denormalized ANS. This means that instead of just having references to other objects, the ANS of the parent object includes the full details of all associated child objects. Arc XP follows the directives within the references to locate the objects linked to the referents’ type and id values, and replaces the shorthand reference syntax with the complete ANS of the child objects, unless a particular object cannot be found. 

The primary distinction between normalized and denormalized documents is in how they represent content. A normalized document is used to process standard create and update operations and mirrors the most recently saved state of a single document by a creator. It contains only the essential properties needed to describe the content. Conversely, a denormalized document contains the complete content body as intended for consumer viewing. In the denormalized version, all child Arc XP objects are combined—also in their fully denormalized form—with the parent object to form a single document ready for use in the view layer, such as a web browser, mobile app, or RSS feed.

Arc XP limits objects to 300 denormalized references. If you exceed this, the system replaces only the first 300 references with their denormalized objects during rendering, leaving the rest in their reference syntax state.

A referent update occurs in Arc XP when a referenced document undergoes modification. For example, a story contains a reference to an image in its content_elements ANS key. If the image’s caption is updated in Photo Center and saved, the next time the parent story’s inflated version is requested, the denormalized image in the story contains the updated caption of the child image. If that same image is used in 1000 stories or galleries, then all 1000 objects update with the same caption change. 

Arc XP employs a caching strategy that could cause these updates to take longer to show in the view layer to the consumer. To learn more, see Catching at Arc XP.

ANS reference syntax allows for a property in the referent field called referent_properties. This property allows you to customize and overwrite the original properties of a child object when it is used in a parent, but only for that one particular use. You write this kind of customized overwrite using a referent custom property, referent.referent_properties.{property of child object to overwrite}.

In the previous example of a fully inflated parent story from Content API, the image’s caption is contained in the object.

{
  "content_elements": [
    {
      "type": "reference",
      "referent": {
        "id": "MUMQSJXQFRE3HAKLMTK3T3R4QU",
        "type": "image",
        "referent_properties": {
          "caption": "In this story, use this caption for the image instead of the default: Road closure...' etc.",
          "subtitle": "This is an overwritten subtitle field"
        }
      }
    }
  ]
}

Inside of referent_properties, you can add some native properties of the child object that you want customized for its use in the parent content. referent_properties customizations are limited to fields that represent captions, titles, descriptions, headlines, and custom user-added fields in the additional_properties key. The values written in referent_properties do not feed back and change the original information on the source material. They are exclusive to only a single use in the parent content.

The following table provides a list of ANS fields that you are likely to nest child Arc XP objects in, resulting in reference syntax when writing create or update ANS.