Data types

Properties must be one of the following data types. These are standard types defined in the JSON Schema specification, together with some Amplience specific extensions.

See the validation page for details of the validations that can be applied to each of these data types.

Type	Description
string	A string of text that may contain unicode characters
number	Any numeric type. It can be an integer or floating point number
integer	An integral number
boolean	A value that can be true or false
object	A nested inline JSON object that can contain properties
array	A JSON array containing ordered elements. Each entry in the array can be any data type
image	A reference to a user selectable image file stored outside Amplience
video	A reference to a user selectable video file stored outside Amplience
content relationship	A reference to other Content stored inside the CMS. Several different forms of content relationship are available to suit your use case

The snippets below show examples of each property.

Strings

Strings can have a format field defined. As well as validating the value of the string, this also controls how the string will be shown in the content form. This is known as a semantic hint.

The markdown format is an Amplience specific format which is used as a semantic hint by the user interface to open the markdown editor to allow the user to edit the value.

The string formats are shown in the table below. For those formats where we've included an example, just click the link to go directly to the example on this page.

Format	Description
text	A string of natural language text
uri	A universal resource identify which must be valid according to RFC3986. Must be a full URI of the format https://www.amplience.com
date-time	Must be a valid date and time as defined in RFC 3339, section 5.6.
date	Must be a valid date as defined in RFC 3339, section 5.6. Introduced in JSON Schema draft 7.
time	Must be a valid time as defined in RFC 3339, section 5.6. The time zone is optional. Introduced in JSON Schema draft 7.
email	Must be a valid email address as defined in RFC 5322, section 3.4.1
markdown	Tells the user interface to display a markdown editor. The value can be any valid string.
color	Tells the user interface to display a color picker.

See validation for a full list of supported text formats.

Examples of the string formats are shown below.

Text

The following shows a simple text field representing a headline, with a maximum length of 256 characters. The UI in the content editing form shows the current and maximum character count.

"properties": {
  "headline": {
    "title": "Headline",
    "description": "The main title of this banner",
    "type": "string",
    "format": "text",
    "minLength": 5,
    "maxLength": 256
  }
}

URI

The uri format must be a complete uri such as http://example.com.

The following shows the callToActionUrl field from the tutorial banner example:

"properties": {
  "callToActionUrl": {
    "title": "Call to action URL",
    "description": "The URL for the call to action",
    "type": "string",
    "format": "uri",
    "maxLength": 256
  }
}

Date-time

A date in the date-time format must be a full date combined with the time including the time zone offset, for example: "2019-09-25T17:20:39+00:00".

"properties": {
  "date": {
     "title": "Creation date",
     "description": "The creation date",
     "type": "string",
     "minLength": 0,
     "maxLength": 50,
     "format": "date-time"
    }
  }

Date

A full date including the year, month and day, for example "2019-09-18".

"properties": {
  "date": {
     "title": "date",
     "description": "The date",
     "type": "string",
     "minLength": 0,
     "maxLength": 20,
     "format": "date"
    }
  }

Time

A time with an optional time zone offset, for example "17:23:07+02:00".

"properties": {
  "time": {
     "title": "time",
     "description": "The time",
     "type": "string",
     "minLength": 0,
     "maxLength": 20,
     "format": "time"
    }
  }

Email

The email format must be a complete, valid email address of the form myname@example.com. The following shows a example string property with this format:

"properties": {
  "email": {
    "title": "email",
    "description": "email address",
    "type": "string",
    "format": "email"
  }
}

Markdown

The markdown format does not do any validation of the string, because the entire value is treated as markdown format. When the content editing form encounters a string property in markdown format, it provides a full markdown editor.

"properties": {
  "blogtext": {
    "title": "blogtext",
    "description": "text for the blog",
    "type": "string",
    "format": "markdown"
  }
}

Color

The color format to strings that will display a color picker in the content form.

To use the color picker add a string property to your schema and specify the format as color.

"properties": {
    "theColor": {
        "title": "Color",
        "description": "Pick a color",
        "type": "string",
        "format": "color"
    }
}

Number

In the example below, the bannerOpacity property is defined as a number. The minimum and maximum keywords are used as additional validation to ensure that the number entered is between 0 and 1.

"properties": {
  "bannerOpacity": {
    "title": "opacity",
    "description": "A value between 0 and 1 (e.g. 0.3)",
    "type": "number",
    "minimum": 0,
    "maximum": 1
  }
}

The content form UI enforces the validation defined for this property. So if the user attempts to add a value greater than 1.01, a warning is displayed and the content cannot be saved until they correct the error.

Integer

The integer type is an integral value. In the snippet below there is no maximum set, but it doesn't make any sense for a stock value to fall below 0.

"properties": {
  "stockLevel": {
    "title": "stock level",
    "description": "The stock level for this item",
    "type": "integer",
    "minimum": 0
  }
}

Boolean

The boolean type is a simple true or false. In the example below, the user will choose whether to select an option for the way a banner is displayed on mobile screen sizes.

"properties": {
  "stackMobileLayout": {
    "title": "Stack mobile layout",
    "description": "Enable to allow banner text to stack underneath the image on small screens",
    "type": "boolean"
  }
}

Array

The array property is often used to hold a list of external objects, such as in the carousel example where the slides property contains the carousel slide items. The maxItems validation keyword is used to set the maximum number of items, in this case carousel slides, that can be added to 6.

Below is an example of the array property type:

"properties": {
  "slides": {
    "type": "array",
    "items": {
      "allOf": [
        {
          "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
        },
        {
          "properties": {
            "contentType": {
              "title": "Carousel Slides",
              "enum": [
                "https://s3-eu-west-1.amazonaws.com/amp-product/tutorials/dynamiccontenttutorials/carouselslide.json"
              ]
            }
          }
        }
      ],
      "minItems": 1,
      "maxItems": 6,
      "title": "Carousel Slides",
      "description": ""
    }
  }
}

Arrays are also useful for simple types, such as shown in the following example:

"properties": {
  "primitiveList": {
    "type": "array",
    "items": {
      "description": "Primitive list item description",
      "type": "string",
      "title": "Primitive list item"
    }
  }
}

Image

An image-link property, together with an alt text property, is shown below.

When the content form encounters an image-link property, the user can launch an image browser and choose an image from their media library.

{
  "properties": {
    "image": {
      "title": "Image",
      "allOf": [
        {
          "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
        }
      ]
    },
    "altimagetext": {
      "title": "Alt image text",
      "description": "The text to be displayed if the image cannot be displayed",
      "type": "string",
      "minLength": 0,
      "maxLength": 100
    }
  }
}

Video

An video-link property, together with a title text property, is shown below.

When the content form encounters an video-link property, the user can launch an image browser and choose an video from their media library.

{
  "video": {
    "title": "video",
    "allOf": [
      {
        "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/video-link"
      }
    ]
  },
  "videotitle": {
    "title": "Video title",
    "description": "Enter the title for the video",
    "type": "string",
    "minLength": 0,
    "maxLength": 50
  }
}

Object

Objects are nested inline objects with properties. The following shows a background property within which there are two properties: alt which is a string and image which is a link to an external image.

{
  "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"
          }
        ]
      }
    }
  }
}

Content relationships

We support several different ways of linking content together.

Content links and content references are both ways of defining properties that include content created from other content types. You can also define inline content, using mixins to load content from other content types and display it within the content form.

For a content-link or content-reference property, the content form displays a content chooser, allowing users to choose the content that the property will link to.

In the examples below, the contentType enum is used to specify that only content created from the https://schema-examples.com/media content type can be chosen. The contentType enum can contain as many types as you need.

While the properties shown below contain a link or reference to a single content item, you'll often use an array to contain links to multiple content items.

You can read more about content relationships in relationship concepts.

Content link

Using a content-link you are linking a parent content item to a child content item. When the parent item is published, all its descendants will be published too.

{
  "type": "object",
  "properties": {
    "content_Link": {
      "title": "Media content item linked",
      "allOf": [
        {
          "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
        },
        {
          "properties": {
            "contentType": {
              "enum": ["https://schema-examples.com/media"]
            }
          }
        }
      ]
    }
  }
}

Content reference

Using a content-reference you can link to external content items, but retrieve those items only when needed.

{
  "content_Reference": {
    "title": "Media content item referenced",
    "allOf": [
      {
        "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-reference"
      },
      {
        "properties": {
          "contentType": {
            "enum": ["https://schema-examples.com/media"]
          }
        }
      }
    ]
  }
}

Mixins

Inline content

With a mixin you can support inline content, as shown in the inline_Content property below. A mixin allows you to reference externally defined content and display this inside the same content form. You do this by including the other schema using the $ref keyword. The content is created from an external schema, but the content itself is all included in the same content item, is not managed separately and cannot be shared with other content items.

{
  "inline_Content": {
    "type": "object",
    "allOf": [
      {
        "$ref": "https://schema-examples.com/media"
      }
    ]
  }
}

Partials

A partial is a schema that just contains a "definitions" section. These definitions can be used in multiple schemas. In order to include a property that is defined in a partial, you just need to make sure that the partial is created on your hub. Partials are not registered.

{
  "link_from_partial": {
    "allOf": [
      {
        "$ref": "https://schema-examples.com/various-partials#/definitions/link"
      }
    ]
  }
}

Related pages

JSON Schema

Content types

Validation