Understanding Arc Native Specification (ANS)

Purpose

Learn the fundamentals of Arc XP’s standardized content model

Audience

Developers working with Arc XP content programmatically

What is ANS?

The Arc Native Specification (ANS) is Arc XP’s foundational content model that standardizes how content is structured, stored, and distributed across the platform. ANS is a JSON-based blueprint that represents all content within the Arc XP ecosystem.

See the latest version of the ANS:

ANS Schema GitHub repository

Key Benefits

ANS provides the following key benefits in the Arc XP ecosystem:

• Standardized representation of multiple content types (articles, images, videos)
• Consistent metadata structure across the platform
• Flexible content transformation and delivery
• Seamless integration between Arc XP components
• Robust content syndication and distribution support

Document Types

ANS documents comprise two main categories: Primary Documents and Secondary Documents. The following section provides an overview of each category.

Primary Documents

Primary documents are top-level documents containing other ANS documents within their properties. Primary documents include:

• Stories (articles)
• Galleries
• Videos

Secondary Documents

Secondary documents are embedded as properties within primary documents. Secondary documents include:

• Images
• Authors
• Sections
• Collections
• Document Redirect ⁽¹⁾
• Tags ⁽²⁾
• Distributors ⁽²⁾
• Geographic Restrictions ⁽²⁾

Note

⁽¹⁾ Supports a primary document but child objects are not written in the parent’s ANS. Document redirects are not the same as what is in a story’s related_content.redirect ANS field; this field stores a story’s forward redirect URL.

⁽²⁾ When supporting a primary document, information about this kind of Arc XP object uses a unique syntax, different from the reference syntax of the others.

Architecture

Arc XP Systems and ANS interact through APIs and Services and Content Pipelines.

APIs and Services

Arc XP APIs are designed to accept JSON data that adheres to the ANS schema. These APIs create objects that Arc XP applications can access and manipulate. Essentially, ANS serves as the language through which content is defined and managed within the Arc XP ecosystem, and integrates with various components through different APIs:

COMPONENT	ROLE
Content API	Provides normalized access to ANS documents
Draft API	Manages content creation and updates
Photo API	Handles image-specific operations
Video API	Manages video content
Author API	Controls author profiles

Content Pipeline

The content pipeline in the Arc XP ecosystem consists of the following phases:

1. Creation:
   a. Creators author and upload content in Composer, Photo Center, or Video Center
   b. Backend creates and stores the ANS documents
   c. Backend resolves references

2. Processing: The backend does the following:
   a. Validates content against the schema
   b. Manages references
   c. Updates cache

3. Delivery: PageBuilder does the following:
   a. Resolves content sources
   b. Transforms content
   c. Optimizes cache

To illustrate, let’s consider an article, termed as a story in ANS. This story comprises of text paragraphs, an embedded image, and an author.

The following JSON provides a simplified view of the story in its ANS format. Some of the metadata has been excluded for readability.

{
  "_id": "GT68FH2GYMZCMDCIYWMPITIDUB5",
  "canonical_website": "arcxpsite",
  "content_elements": [
    {
      "_id": "PY4FH2GYMZCMDCIYWMPITICVA4",
      "content": "Beginning in late July or early August of 2024,...",
      "type": "text"
    },
    {
      "_id": "LGANVKR4NFHKTFLEND7BJHEACE",
      "content": "For years, the Mount Blue Sky Scenic Byway...",
      "type": "text"
    },
    {
      "referent": {
        "id": "MUMQSJXQFRE3HAKLMTK3T3R4QU",
        "type": "image",
        "referent_properties": {
          "subtitle": "Colorado's Front Range"
        }
      },
      "type": "reference",
      "_id”: “MUMQSJXQFRE3HAKLMTK3T3R4QU"
    },
    {
      "_id": "BA3ELFFQUVC65LVVAKSS35HWXM",
      "content": "The main focus of the project...",
      "type": "text"
    }
  ],
  "credits": {
    "by": [
      {
        "referent": {
          "id": "brianpreece",
          "type": "author"
        },
        "type": "reference"
      }
    ]
  },
  "headlines": {
    "basic": "Iconic Mountain-Top Highway is About to Close for 2 Years"
  },
  "type": "story",
  "version": "0.10.10"
}

Data Representation

Normalized 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 with the id and type of the target object.

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.

• Uses reference syntax shorthand for embedded objects
• Contains essential properties only
• Reduces redundancy
• Improves performance
• Used for create and update operations
• Represents the latest saved state

The left side shows an 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.

Denormalized ANS

A denormalized document contains the complete content body as intended for consumer viewing. 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.

• Contains complete, expanded (inflated) content
• Replaces references with full object details
• Used in view layers: Browsers, apps, and feeds
• Includes all child objects in their full form

Elements

Core Elements

Every ANS document includes the following fundamental elements or properties:

{
   "_id": "unique-identifier",
   "type": "content-type",
   "version": "ans-version",
   "headlines": {
     "basic": "Main headline"
   },
   "content_elements": [],
   "credits": {},
   "taxonomy": {},
   "additional_properties": {}
}

Note

The exact structure varies by content type, but all documents share these basic building blocks.

Content Elements

The content_elements array is the primary method for expressing content structure in stories. The sequence of content elements reflects the logical order of content within a story, dictating what the consuming application should see and in what order.

The following snippet exemplifies text and image elements inside the content_elements array.

{
  "content_elements": [
    {
      "type": "text",
      "content": "Article text here..."
    },
    {
      "type": "image",
      "referent": {
        "id": "IMAGE_ID",
        "type": "image"
      }
    }
  ]
}

Content elements recap

• Maintain strict ordering
• Support multiple types such as, text, images, videos
• Allow custom element types
• Define the consumer-facing content sequence

Reference System

ANS uses a reference system to manage relationships between documents. The following snippet exemplifies a reference content type:

{
  "type": "reference",
  "referent": {
    "id": "UNIQUE_ID",
    "type": "image",
    "referent_properties": {
      "caption": "Custom caption for this usage"
    }
  }
}

Note

Each document supports a maximum of 300 denormalized references.

ANS references:

• Maintain positional order
• Support customized properties per usage
• Enable automatic propagation of updates

Referent Updates

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 Caching within Arc XP.

Note

Some Arc XP objects do not cause a referent update. References to Site Service sections do not update in parent objects until the parent object itself undergoes a save event.

Inline Entities

Used for lightweight, embedded content that doesn’t need independent storage. In those scenarios, you can use inline entities instead of references.

An inline entity is like a pre-resolved reference, included identically in both normalized and denormalized documents. It acts as a second object that travels with the containing parent object, which you cannot reference or edit independently. A common example of inline entities is authors, which you store in credits.by within ANS.

Use inline entities only for authors, tags, and distributors. For example, use inline entities when you need to record an author, tag, or distributor that does not need to be available globally in Arc XP. Instead, frame its use with syntax that ties it directly to the context of the parent object, as shown in the following example:

{
  "_id": "DEFGHIJKLMNOPQRSTUVWXYZABC",
  "type": "story",
  "version": "0.10.9",
  "headlines": {
    "basic": "Man Bites Cat"
  },
  "credits": {
    "by": [
      {
        "type": "author",
        "name": "Dr. Suess"
      }
    ]
  }
}

Custom Referent Properties

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.

ANS FIELD	ANS OBJECT TYPE	DESCRIPTION
content_elements	story gallery	Content elements are an ordered list of variably-typed elements, including text, images, and videos
promo_items	story gallery	Lists of promotional content
credits	story gallery video image	Authors attributed to the content
related_content	story video	Lists of content items this object is related to
taxonomy.primary_section taxonomy.sections	gallery video	Holds Site Service sections
website_primary_section website_sections	story	Holds Site Service sections

recap

• Customize the original properties of a child object
• Does not update or change the original information on the source material

Additional Properties

Several ANS types include a field named additional_properties. This field is reserved for custom use and must be valid JSON, but its specific use is undefined by ANS. This is an advanced field that should be used only after fully understanding its implications.

The following snippet exemplifies an object with custom fields inside the additional_properties field.

{
  "additional_properties": {
    "custom_field": "value",
    "organization_data": {}
  }
}

Caution

Data within additional_properties is not searchable in Content API. See Searchable Text Fields for more information.

Best Practices

To ensure reliable content rendering and management, Arc XP recommends adhering to the following best practices:

Reference Management

• Use references for reusable content
• Monitor reference limits
• Consider cache implications

Content Structure

• Maintain consistent taxonomy
• Use appropriate content types
• Follow schema guidelines

Performance

• Optimize reference usage
• Implement efficient caching
• Monitor payload sizes

Limitations

ANS offers a complete and extensible schema, but it also has the following limitations:

• Limits denormalized references to 300 for each document
• Requires schema validation
• Has complex cache invalidation
• Adds overhead to content transformation

Caution

Exceeding reference limits can lead to incomplete content resolution.

Further Reading

• Content API Documentation

• For more detailed information on how to construct ANS when creating or updating an Arc XP object, refer to the following articles:

  • How To Write The Minimum Ans For A Viable Video Document
  • How To Write The Minimum Ans For A Viable Image Document
  • How To Write The Minimum Ans For A Viable Gallery Document