This blog post introduces a series about JSON data formats used by the Contentstack SaaS headless CMS.
- Contentstack JSON Data Formats: Introduction and Scalars – Deliverystack.net
- Contentstack JSON Data Formats: Modular Blocks Fields – Deliverystack.net
- Contentstack JSON Data Formats: Entry Structure – Deliverystack.net
- Contentstack JSON Data Formats: Assets and File Fields – Deliverystack.net
- Contentstack JSON Data Formats: Complex Fields – Deliverystack.net
Other than the binary components of media assets, Contentstack uses JSON (JavaScript Object Notation) to exchange all data.
The primary use of JSON in Contentstack is to represent entries. Entries are records stored in the CMS that contain values for the fields defined by their content types, which are data structures that you define in the CMS. Contentstack APIs and webhooks add JSON metadata superstructures around the JSON representations of entries. Software development kits for JavaScript and other languages wrap underlying HTTPS APIs, typically abstracting entry JSON as programming objects or otherwise rather than requiring developers to understand APIs and metadata.
Scalars
JSON uses strings of characters to represent all scalar values including Booleans, numbers, and dates. Scalars are atomic values that consist of anything that is itself not JSON. Scalar values can be large and complex, such as embedded XML, and can specify URLs or other external data sources including additional JSON resources. JSON readers are responsible for determining the machine and logical types of scalar values such as Boolean, integer, float, date, and string, and for retrieving data from referenced URLs or otherwise where appropriate.
Default Scalar Field Types
Contentstack provides the following default scalar types:
- Boolean (Checkbox): Contains the string “true” (checked) or “false” (unchecked).
- Single-Line Textbox: String
- Multi Line Textbox: String
- Rich Text Editor: HTML (technically a string)
- Markdown: Generally requires transformation to HTML using an SDK (also technically a string)
- Number: Also…technically…a…string. Hunh.
- Select (Single Value): String
- Date: UTC (2021-11-25T20:45:11.000Z). That’s a string.
- URL: String
- Custom: Depending on requirements, custom field types can store individual scalar values (strings) or complex JSON structures.
Entry JSON Structure
Contentstack constructs the JSON structure of an entry from the identifiers of all the fields defined by its content type, including value (scalar or multiple) fields, group and global fields, modular blocks fields, and the identifiers of individual blocks in modular blocks fields. Consider these identifiers to be unique at any level within the JSON structure, though fields nested within groups and modular blocks can re-use field identifiers used at other levels. Field identifiers should be simple but comprehensive enough to identify their purpose. Configure field identifiers to control the JSON format used to represent your data.
The JSON representation of an entry contains a key for each field identifier in its content type, followed by the value of the field. All content types include the default Title field with title as its identifier, therefore any entry may appear as follows:
{
title: "entrytitlevalue”,
// ...
}
While we often think of fields as storing scalar values, fields are just keys in the JSON structure. Their values can be scalars or can consist of lists and more complex JSON structures.
Multiple Fields
Contentstack allows fields to repeat. Rather than a single field containing a single value, “multiple” fields can contain multiple instances of a single field value structure. The scalar field types have a multiple property that allows the entry to store multiple values (the select field uses the label Multiple Choices for this option). A multiple scalar field contains a list of the scalar field type.
"mymultiplefield": [ "firstfieldvalue", "secondfieldvalue" //… ],
For non-scalar field types including select fields that allow multiple selections, the non-scalar structure repeats. For example, a repeating link field appears as follows.
"link": [
{
"title": "First Link Title",
"href": "https://first.url"
},
{
"title": "Second Link Title",
"href": "https://second.url"
}
],
Reference and Select Fields
Reference fields store the content type identifier(s) and the identifier of the selected entry or entries as a list of values regardless of whether their configuration allows selection of a single entry or multiple entries. A single entry in a reference field is always a list with a single element.
"referencefieldid": [
{
"uid": "bltbb63a53059579d5a",
"_content_type_uid": "mb"
}
],
Select fields configured to allow selection of a single entry store a scalar value:
"singleselectfieldid": "selectedoption",
Select fields configured to allow selection of a multiple values store a list of scalars:
"multipleselectfieldid": [ "firstoption", "secondoption" ],
This difference is important: you can convert a single reference field to a multiple reference field, but you cannot convert a single select field to a multiple select field. If there is any chance that a select field may need to be multiple in the future, use a multiple select field, and if necessary, use validation or other techniques to restrict it to a single value. I cannot think of a logical use case that would not involve a group field, but multiple reference fields are allowed, where multiple select fields are not allowed –
Group Fields and Global Fields
Group fields and global fields are equivalent in that they contain nested fields, resulting in a hierarchical JSON structure where the key is the identifier of the group field or the reference to a global field in the content type. A global field is functionally a group field defined for reuse by multiple content types. The key in the JSON is the ID of the reference to the field in the content type, not the ID of the global field definition.
mygrouporglobal: {
myfield: "fieldvalue",
//…
}
Modular Blocks Fields
Modular blocks fields allow much more complex hierarchical JSON structures within fields.
Deliverystack.net 
8 thoughts on “Contentstack JSON Data Formats: Introduction and Scalars”