Working with Single and Multiple Reference Fields in the Contentstack SaaS Headless CMS

This blog post explains how the Contentstack SaaS headless CMS stores the values of reference fields as lists even when there is only a single referenced entry.

In Contentstack, each simple field type can store either a single value, or multiple values. For example, to associate a single date with a event, a developer could create a date field that did not allow multiple values. If an event may occur on multiple dates, then the developer can mark that date field as multiple.

For most field types, the selection of single or multiple affects the resulting JSON data structure. Specifically, if a field allows a single value, then the JSON representation is that of a single key; if a field can store multiple values, then its JSON representation is that of an array. This simplifies processing the JSON, as developers do not need to constantly take the first element of arrays that contain a single element.

A single string field might appear in the JSON representation of an entry like this:

"field_id": "only value",

A string field that supports multiple values might appear in the JSON like this:

"field_id": [
  "first value",
  "second value"
],

In .NET entry models, we can model the single string as a string property, and model the list as a list property of the string type.

The reference field type is an exception to the rule of how fields configured to store a single value rather than multiple values represent their content. In Contentstack, a reference field contains the content type and unique identifier of another entry. In other words, each instance of a reference field contains multiple values: the ID of the selected entry and the ID of its content type.

Whether you mark a reference field as single or multiple, its JSON representation appears as an array. Here is an example of a single entry in a reference field.

"reference": [
  {
    "uid": "blte2ae716c63763b24",
    "_content_type_uid": "contenttypeid1"
  }
],

Here is an example of multiple entries in a reference field.

"reference": [
  {
    "uid": "blte2ae716c63763b24",
    "_content_type_uid": "contenttypeid1"
  },
  {
    "uid": "bltd4d1675b52a3a61c",
    "_content_type_uid": "contenttypeid2"
  }
],

To access these values, model reference fields as lists, even if the fields can only reference a single entry, and retrieve that first element from the list when needed.

My explanation for this exception is that this allows a more unified programming model for this specific case and simplifies converting reference fields that allow a single entry to reference fields that allow multiple entries, which somehow seems more likely for the reference field type than for other field types such as link that represent fields configured not to store multiple without the JSON array tokens.

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: