Contentstack JSON Data Formats: Entry Structure

This blog post, part of a series about JSON data formats in the Contentstack SaaS headless CMS, describes how Contentstack represents entries as JSON, where entries are records in the CMS that contain values for the fields defined by the content types associated with those entries.

• Contentstack JSON Data Formats: Introduction and Scalars – Deliverystack.net

Every Contentstack entry includes the default Title field with the title key to contain the title of the entry in the CMS. You can change certain properties of this field in each content type, but you cannot remove it.

Every entry includes the default Tags field with the tags key to contain tags for the entry. You cannot change properties of this field and you cannot remove it.

Content types that represent web pages include the URL field which uses the URL field type that can only appear once in each content type. Entries associated with content types that include the URL field include the url key.

Entries include several other default keys that do not appear as fields in the CMS user interface for the entry.

• uid: Globally unique identifier for entry (bltbb63a53059579d5a)
• locale: Identifies the language and region associated with the entry (en-us)
• created_by: ID of CMS user (bltf659c3e814f4dce6)
• updated_by: ID of CMS user (bltf659c3e814f4dce6)
• created_at: 2021-11-29T14:25:20.747Z
• updated_at: 2021-11-30T11:55:35.423Z
• ACL: Access Control List (for content access restrictions).
• _version: 5
• _in_progress: false

Publishing

Entries include information about their most recent publishing state in a publish_details key.

"publish_details": [
{
  "environment": "blt32092e3976f60b0b",
  "locale": "en-us",
  "time": "2021-11-30T16:08:47.288Z",
  "user": "bltf659c3e814f4dce6",
  "version": 1
}

When using a content management authorization token rather than content delivery token, setting the include_publish_details query string parameter to true returns publishing details for all environments as a list.

"publish_details": [
  {
    "environment": "blt32092e3976f60b0b",
    "locale": "en-us",
    "time": "2021-12-01T15:36:23.390Z",
    "user": "bltf659c3e814f4dce6",
    "version": 1
  },
  {
    "environment": "blt4e5b024295a0e4f2",
    "locale": "en-us",
    "time": "2021-12-01T15:36:23.397Z",
    "user": "bltf659c3e814f4dce6",
    "version": 1
  }
]

Workflow

Entries can include metadata about their workflow state, but only when accessed using content management rather than content delivery APIs and only when the include_workflow query string parameter is true.

• Access Contentstack Entry Workflow Information – Deliverystack.net

When requested, entries include a _workflow key that looks like the following.

"_workflow": {
  "uid": "bltb7970cc88b1d1e47",
  "updated_at": "2021-04-02T00:21:35.506Z",
  "updated_by": "bltf659c3e814f4dce6",
  "version": 468,
  "assigned_to": [],
  "assigned_by_roles": [],
  "name": "editorial",
  "color": "#2196f3"
}

Example

The minimal structure of an entry follows, excluding details only available through content management rather than content delivery APIs.

{
  "_version": 1,
  "locale": "en-us",
  "uid": "bltb001c2cd672a1518",
  "ACL": {},
  "_in_progress": false,
  "created_at": "2021-12-01T15:33:11.635Z",
  "created_by": "bltf659c3e814f4dce6",
  "tags": [],
  "title": "Entry Title",
  "updated_at": "2021-12-01T15:33:11.635Z",
  "updated_by": "bltf659c3e814f4dce6",
  "publish_details": {
    "environment": "blt4e5b024295a0e4f2",
    "locale": "en-us",
    "time": "2021-12-01T15:36:23.266Z",
    "user": "bltf659c3e814f4dce6"
}

Miscellaneous

To optimize payloads, you can use operators to specify exactly which fields to include or exclude.

• https://www.contentstack.com/docs/developers/apis/content-delivery-api/#only-operator
• https://www.contentstack.com/docs/developers/apis/content-delivery-api/#exclude-operator

GraphQL requires that you specify the fields to include.

• GraphQL Content Delivery API for Developers | Contentstack

You can cause Contentstack to inline JSON from referenced entries into other entries:

• https://www.contentstack.com/docs/developers/apis/content-delivery-api/#include-reference