Introducing JSON Schema

Introduction

A schema defines the data model for a content type.

We use an open standard called JSON Schema to provide you with a powerful and flexible way of modeling your data. JSON schema describes the format of JSON structures using a set of keywords that you combine to create complex structures.

When users create content from a content type, the CMS will interpret the schema and generate an easy to use authoring interface on the content form that matches the structure you defined, including any validation rules you have included in the schema.

You can use the schema editor to create schemas and add them to your hub.

Example schema

We'll use the banner from the get started tutorial to walk you through how a schema is structured. The banner contains a heading, subheading, background image and a call to action and demonstrates the key concepts of modeling using JSON Schema.

After some boilerplate definitions, the structure of a schema starts with the type keyword. In this case, the structure is an object.

{
  "type": "object"
}

To define individual properties you use the properties keyword. We'll start with properties named headline and strapline. The property name is used to refer to the property in the JSON output returned from the CMS.

{
  "type": "object",
  "properties": {
    "headline": {
      "type": "string"
    },
    "strapline": {
      "type": "string"
    }
  }
}

Title & description

Each property can have an optional title and description. Both the title and description appear on the content form and provide more information to the user about what the property is used for.

We'll add a title and description to the properties we just defined:

{
  "type": "object",
  "properties": {
    "headline": {
      "title": "Headline",
      "description": "The main title of this banner",
      "type": "string"
    },
    "strapline": {
      "title": "Strapline",
      "description": "The subtitle of this banner",
      "type": "string"
    }
  }
}

Validation

JSON Schema provides validation keywords that you can use to apply rules to your content. Each data type supports various validations: for example you can specify the minimum and maximum length of text and the minimum and maximum value for a number.

For the banner we'll add some validation to ensure that headline and streamline both have a maximum length of 70 characters so there won't be too much text to display. The user won't be able to enter more than 70 characters for these properties.

To do this we'll use the maxLength keyword:

{
  "type": "object",
  "properties": {
    "headline": {
      "title": "Headline",
      "description": "The main title of this banner",
      "type": "string",
      "maxLength": 70
    },
    "strapline": {
      "title": "Strapline",
      "description": "The subtitle of this banner",
      "type": "string",
      "maxLength": 70
    }
  }
}

See validation for more details of the validations available for each data type.

Nested objects

Next we'll define the call to action. This consists of the call to action text and the URL that will be launched when the user clicks the call to action button. We'll implement this property as a nested object: a property that has its own properties:

{
  "link": {
    "type": "object",
    "title": "Link",
    "properties": {
      "url": {
        "title": "URL",
        "description": "The url that will be opened when link is clicked",
        "type": "string"
      },
      "title": {
        "title": "Title",
        "description": "Text displayed for the link",
        "type": "string"
      }
    }
  }
}

Structuring the link property as a nested object makes it easy to use in different schemas.

Media

The banner also contains a background image and some alt text that will be displayed if the image can't be shown. Because this is a common definition that we might want to re-use in other schemas, we'll structure the background property as a nested object.

For the image property, we want the user to choose an image from their media library. To do this we include the Amplience specific image-link definition as shown below. When the content form encounters an image-link property, the user can launch an image browser and choose an image from their library.

The JSON output for content created from this schema will include the data to construct the image URL for the image the user selected.

{
  "background": {
    "type": "object",
    "title": "Background image",
    "properties": {
      "alt": {
        "title": "Alternative text",
        "description": "Alternative text for the background image",
        "type": "string"
      },
      "image": {
        "title": "Image",
        "description": "The image for the background of this banner",
        "allOf": [
          {
            "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
          }
        ]
      }
    }
  }
}

You can include video in your content by adding the video-link definition to a property. See the media page to find out more.

Schema URL and vocabulary

There are some definitions that must be included at the top of each schema.

• $schema - The $schema keyword tells the system what version of JSON Schema we are using. We currently support JSON Schema draft 7. This is referred to as the schema vocabulary.
• $id - The $id keyword gives the schema a unique id so it can be referenced. The format of this is a URL that can be any value but must be unique within a hub.
• allOf - This includes the Amplience specific definitions that tell the CMS that this schema is a content type. It adds some extra metadata properties to your content type that the CMS will populate automatically.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://schema-examples.com/tutorial-banner",
  "allOf": [
    {
      "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content"
    }
  ],
  "title": "Example Banner",
  "description": "Banner used for code examples in developer portal",
  "type": "object",
  "properties": {
    "headline": {
      "title": "Headline",
      "description": "The main title of this banner",
      "type": "string",
      "maxLength": 70
    },
    "strapline": {
      "title": "Strapline",
      "description": "The subtitle of this banner",
      "type": "string",
      "maxLength": 70
    },
    "background": {
      "type": "object",
      "title": "Background image",
      "properties": {
        "alt": {
          "title": "Alternative text",
          "description": "Alternative text for the background image",
          "type": "string"
        },
        "image": {
          "title": "Image",
          "description": "The image for the background of this banner",
          "allOf": [
            {
              "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
            }
          ]
        }
      }
    },
    "link": {
      "type": "object",
      "title": "Link",
      "properties": {
        "url": {
          "title": "URL",
          "description": "The url that will be opened when link is clicked",
          "type": "string"
        },
        "title": {
          "title": "Title",
          "description": "Text displayed for the link",
          "type": "string"
        }
      }
    }
  },
  "propertyOrder": []
}

Now that the schema is complete it can be registered as a content type. See working with content types to find out more.

info

Content relationships

You can model more complex structures by linking multiple pieces of content together. We provide you with multiple ways of modelling these content relationships using JSON Schema. You can read more in content relationship concepts.

Other features

Comments

Comments can be added to a property or at the root level of a schema using the $comment keyword. They are not shown in the content form and do not affect the functionality of the schema. Comments are intended to provide notes to developers maintaining a schema.

"date": {
    "title": "date",
    "description": "description",
    "type": "string",
    "minLength": 0,
    "maxLength": 50,
    "format": "date",
    "examples": [
        "2019-10-15",
        "2018-07-31"
    ],
    "$comment": "A string property with the date format"
}

Examples

The examples keyword allows developers to include an array of example acceptable values for a property. These examples are then displayed in the content form in the production view as hints to the user.

A property including examples is shown below. This is a string with date format for which some sample valid values have been provided.

"date": {
    "title": "date",
    "description": "description",
    "type": "string",
    "minLength": 0,
    "maxLength": 50,
    "format": "date",
    "examples": [
        "2019-10-15",
        "2018-07-31"
    ]
}

In the content form, any properties with examples will be displayed with a "i" icon to the right of the property. Click this icon to display the examples in a pop up window.

Examples don't change the functionality or validation of a schema, but they do provide useful hints to the user.

Default values

The default keyword allows you to set the default value of an item. You can use default with strings, numbers, booleans and lists, as well as content and image links.

To use default, include it in a property definition. The property shown below is a number between 0 and 100. We want to set the default value to 90. The property will be set to this value when content created from this schema is first opened in the content form. The user can change the value if they wish.

   "properties":{
      "numberValue":{
         "title":"title",
         "description":"description",
         "type":"number",
         "minimum":0,
         "maximum":100,
         "default":90
      }
   }

If you use the const keyword to define a value for a property that cannot be changed, then the default keyword will not override what's defined in the constant.

Strings

The default value for a string property is easy to set up, as shown in the example property below.

Note that the maximum length of the string is 20 characters. If we specify a default that is greater than 20 characters in length, then the schema can be saved and registered, but when the content form is opened, a warning message is displayed in the stringProperty field and the content cannot be saved until the field contains less than 20 characters.

"properties":{
      "stringProperty":{
         "title":"A string with a default value",
         "type":"string",
         "minLength":0,
         "maxLength":20,
         "default":"Some example text"
      }
   }

You can also use default with arrays, image links, content links and enums. See the default example for many more snippets.

Usage notes

• Default is not currently supported for arrays on object or nested arrays.

• Default is not currently supported for localized fields.

• Currently a slot item containing a default content link cannot be added an edition, because in this context a snapshot id is expected rather than a content id.

Constants

The const keyword is used to specify the value of a property and indicate that it cannot be changed. You can use const with strings, numbers and other property types such as media links. For example, you could specify a set image that is always included with a content type, or some settings that cannot be changed.

The example below shows a shippingcountry property is defined as a string with the value of "United Kingdom".

"shippingcountry": {
    "title": "Ship to",
    "description": "description",
    "type": "string",
    "const": "United Kingdom"
        }

const arrays

To specify an array of constants you could define a property as follows:

"conststringarray": {
    "type": "array",
    "const": [
        "one",
        "two"
    ],
    "items": {
        "type": "string"
    }
}

Related pages

JSON Schema

Data types

Data types- content relationships

Content types

Validation

Content relationship concepts

Working with content types

The schema editor

Schema examples