---
canonical: https://amplience.com/developers/docs/schema-reference/json-schema/
title: Introducing JSON Schema

description: Amplience uses an open standard called JSON Schema that provides a flexible way of modeling data from which content authoring forms can be generated for users.
audience: Developer
date_published: 2022-07-12
date_modified: 2026-06-01
---

# Introducing JSON Schema

## Introduction

A schema defines the data model for a content type.

We use an open standard called [JSON Schema](https://json-schema.org/) 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](https://amplience.com/developers/docs/dev-tools/guides-tutorials/schema-editor) to create schemas and add them to your hub.

## Example schema

We'll use the banner from the [get started](https://amplience.com/developers/docs/start) 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`.

```json
{
  "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.

```json
{
  "type": "object",
  //highlight-start
  "properties": {
    "headline": {
      "type": "string"
    },
    "strapline": {
      "type": "string"
    }
  }
  //highlight-end
}
```

### 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:

```json
{
  "type": "object",
  "properties": {
    "headline": {
      //highlight-start
      "title": "Headline",
      "description": "The main title of this banner",
      //highlight-end
      "type": "string"
    },
    "strapline": {
      //highlight-start
      "title": "Strapline",
      "description": "The subtitle of this banner",
      //highlight-end
      "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:

```json
{
  "type": "object",
  "properties": {
    "headline": {
      "title": "Headline",
      "description": "The main title of this banner",
      "type": "string",
      //highlight-start
      "maxLength": 70
      //highlight-end
    },
    "strapline": {
      "title": "Strapline",
      "description": "The subtitle of this banner",
      "type": "string",
      //highlight-start
      "maxLength": 70
      //highlight-end
    }
  }
}
```

See [validation](https://amplience.com/developers/docs/schema-reference/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:

```json
{
  "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.

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

You can include video in your content by adding the `video-link` definition to a property. See the [media](https://amplience.com/developers/docs/schema-reference/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.

```json
{
  //highlight-start
  "$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"
    }
  ],
  //highlight-end
  "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](https://amplience.com/developers/docs/dev-tools/guides-tutorials/content-types) to find out more.

<br/>

> **Info:** ### Content relationships
> 
> <br/>
> 
> 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](https://amplience.com/developers/docs/concepts/relationships).

## 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.

```json
   "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](#constants).

#### 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.

```json
"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](https://amplience.com/developers/docs/schema-reference/schema-examples/core-concepts/default) for many more snippets.

#### Usage notes

- Default is not currently supported for arrays of type `object` or nested arrays.

- Default is not currently supported for [localized fields](https://amplience.com/developers/docs/dev-tools/guides-tutorials/localization).

- 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"
	}
}
```

### Read only properties

Read only and write only properties are supported, as defined in the [JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/annotations). A read only property cannot be modified.

In the example below, the country property is set as read only. This annotation can be combined with conditionals so that the property is disabled based on the state of other properties.

```json
"properties": {
		"country": {
			"title": "Country",
			"description": "Enter the country to ship to",
			"type": "string",
			"minLength": 0,
			"maxLength": 255,
			"readOnly":true
		}
	}
```

Write only properties are also supported. This annotation will not affect the authoring experience, but is used as a setting for APIs.

## Related pages

[JSON Schema](https://json-schema.org/)

[Data types](https://amplience.com/developers/docs/schema-reference/data-types)

[Data types- content relationships](https://amplience.com/developers/docs/schema-reference/data-types#content-relationships)

[Content types](https://amplience.com/developers/docs/concepts/content-types)

[Validation](https://amplience.com/developers/docs/schema-reference/validation)

[Content relationship concepts](https://amplience.com/developers/docs/concepts/relationships)

[Working with content types](https://amplience.com/developers/docs/dev-tools/guides-tutorials/content-types)

[The schema editor](https://amplience.com/developers/docs/dev-tools/guides-tutorials/schema-editor)

[Schema examples](https://amplience.com/developers/docs/schema-reference/schema-examples)