Skip to main content

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.

TypeDescription
stringA string of text that may contain unicode characters
numberAny numeric type. It can be an integer or floating point number
integerAn integral number
booleanA value that can be true or false
objectA nested inline JSON object that can contain properties
arrayA JSON array containing ordered elements. Each entry in the array can be any data type
imageA reference to a user selectable image file stored outside Amplience
videoA reference to a user selectable video file stored outside Amplience
content relationshipA 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
Link copied!

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.

FormatDescription
textA string of natural language text
uriA universal resource identify which must be valid according to RFC3986. Must be a full URI of the format https://www.amplience.com
date-timeMust be a valid date and time as defined in RFC 3339, section 5.6.
dateMust be a valid date as defined in RFC 3339, section 5.6. Introduced in JSON Schema draft 7.
timeMust be a valid time as defined in RFC 3339, section 5.6. The time zone is optional. Introduced in JSON Schema draft 7.
emailMust be a valid email address as defined in RFC 5322, section 3.4.1
markdownTells the user interface to display a markdown editor. The value can be any valid string.
colorTells 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
Link copied!

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
Link copied!

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
Link copied!

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
Link copied!

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
Link copied!

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
Link copied!

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
Link copied!

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
Link copied!

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
Link copied!

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
Link copied!

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
Link copied!

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
Link copied!

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
Link copied!

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
Link copied!

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
Link copied!

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
Link copied!

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.

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
Link copied!

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
Link copied!

Inline content
Link copied!

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
Link copied!

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

JSON Schema

Content types

Validation