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.

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.

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.

GraphQL requires that you specify the fields to include.

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

2 thoughts on “Contentstack JSON Data Formats: Entry Structure

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: