JSON schema for creating a content type

Contentstack understands JSON data. If you want to create a content type through API or a JSON file (instead of through the user interface), you need to create a JSON file that contains the content type schema, and use the ‘Import content type’ link in the product or send the schema as body in the API request. 

Each field added in the content type has its own schema. Let’s see how the schema of all the field looks like, and how to use them in the content type JSON file.

JSON Schema of Fields

Title

The Title field is the title of the entry and will have a unique value, i.e., entries cannot have the same title.

The schema of the Title field is given as follows:

{
    "display_name": "Title",
    "uid": "title",
    "data_type": "text",
    "mandatory": true,
    "unique": true,
    "field_metadata": {
        "_default": true
    },
    "multiple": false
}

The parameters in the above JSON body is explained in the ‘Common field parameters’ section.

To mark this field as non-unique, you need to set the unique parameter to false.

URL

The URL field allows you to enter a URL of the entry. 

The schema of the URL field is given as follows:

{
    "display_name": "URL",
    "uid": "url",
    "data_type": "text",
    "mandatory": true,
    "field_metadata": {
        "_default": true
    },
    "multiple": false,
    "unique": false
}

The parameters in the above JSON body is explained in the ‘Common field parameters’ section.

Single line textbox

The Single line textbox field supports only plain text and is often used when the expected input value is some short text.

The schema of the Single line textbox field is given as follows:

{
    "data_type": "text",
    "display_name": "Single line textbox",
    "uid": "single_line",
    "field_metadata": {
        "description": "",
        "default_value": ""
    },
    "format": "",
    "error_messages": {
        "format": ""
    },
    "multiple": false,
    "mandatory": false,
    "unique": false
}

The parameters in the above JSON body is explained in the ‘Common field parameters’ section. This field posses a couple of parameters that needs to be added specifically to it and is explained below:

  • format: This parameter takes a regex that you can use to validate the value of a field.
  • error_messages: This parameter is the error message that will be displayed if a field value is not validated. You can set a format for it as well.

Multi line textbox

The Multi Line Textbox field accepts multi-line arbitrary text, and is used to enter a large chunk of data.

The schema of the Multi line textbox field is given as follows:

{
    "data_type": "text",
    "display_name": "Multi line textbox",
    "uid": "multi_line",
    "field_metadata": {
        "description": "",
        "default_value": "",
        "multiline": true
    },
    "format": "",
    "error_messages": {
        "format": ""
    },
    "multiple": false,
    "mandatory": false,
    "unique": false
}

The parameters in the above JSON body is explained in the ‘Common field parameters’ section. This parameter posses a couple of parameters, such as format and error_messages’, that are common to the ‘Single line textbox’ field.

Rich text editor

The Rich Text Editor field accepts a variety of data type, such as text, images, and videos and allows you to format the content entered in the field.

The schema of the Rich text editor field is given as follows:

{
    "data_type": "text",
    "display_name": "Rich text editor",
    "uid": "rich_text_editor",
    "field_metadata": {
        "allow_rich_text": true,
        "description": "",
        "multiline": false,
        "rich_text_type": "advanced"
    },
    "multiple": false,
    "mandatory": false,
    "unique": false
}

The parameters in the above JSON body is explained in the ‘Common field parameters’ section.

Within the field_metadata parameter, you can provide the keys given below:

  • allow_rich_text: This key determines whether the editor will support rich text, and is set to true by default for Rich Text Editors.
  • description: This key allows you to provide the content for the Rich text editor field. 
  • multiline: This key provides multi line capabilities to the Rich text editor.
  • rich_text_type: This key lets you enable either the basic or advanced editor to enter your content.

Markdown

The Markdown field accepts text in markdown format which is essentially an easy-to-read text that is marked with certain tags or formatting instructions. 

The schema of the Markdown field is given as follows:

{
    "data_type": "text",
    "display_name": "Markdown",
    "uid": "markdown",
    "field_metadata": {
        "description": "",
        "markdown": true
    },
    "multiple": false,
    "mandatory": false,
    "unique": false
}

The parameters in the above JSON body is explained in the ‘Common field parameters’ section.

To enable the field to accept markdown content, you need to set a key, "markdown": true, in the field_metadata parameter.

Select

The ‘Select’ field allows users to choose one or more options from a set of predefined choices that can be displayed in the form of radio buttons, checkboxes, or dropdown options.

The schema of the Select field is given as follows:

{
    "data_type": "text",
    "display_name": "Select",
    "display_type": "dropdown",
    "enum": {
        "advanced": false,
        "choices": [{
            "value": "1"
        }, {
            "value": "2"
        }, {
            "value": "3"
        }]
    },
    "multiple": true,
    "uid": "select",
    "field_metadata": {
        "description": "",
        "default_value": ""
    },
    "mandatory": false,
    "unique": false
}

The parameters in the above JSON body is explained in the ‘Common field parameters’ section.

Additionally, you need to set the parameters given below:

  • display_type: This parameter allow you to assign a display type either in the form of radio button, checkboxes, or dropdown.
  • enum This parameter allow you to provide the choice for the ‘Select’ field.

Modular Blocks

The ‘Modular Blocks’ field allows content managers to dynamically create and modify components of a page or app on the go.

The schema of a 'Modular Blocks' field consisting of a 'Single Line Textbox' and a 'Rich Text Editor' is given as follows:

{
    "data_type": "blocks",
    "display_name": "Modular Blocks",
    "abstract": "Create content dynamically",
    "blocks": [{
        "title": "Block",
        "uid": "block",
        "autoEdit": true,
        "schema": [{
                "data_type": "text",
                "display_name": "Single line textbox",
                "abstract": "Name, title, email address, any short text",
                "uid": "single_line",
                "field_metadata": {
                    "description": "",
                    "default_value": ""
                },
                "class": "high-lighter",
                "format": "",
                "error_messages": {
                    "format": ""
                }
            },
            {
                "data_type": "text",
                "display_name": "Rich text editor",
                "abstract": "Long text with formatting options",
                "uid": "rich_text_editor",
                "field_metadata": {
                    "allow_rich_text": true,
                    "description": "",
                    "multiline": false,
                    "rich_text_type": "advanced"
                },
                "class": "high-lighter"
            }
        ]
    }],
    "multiple": true,
    "uid": "modular_blocks",
    "field_metadata": {}
}

Number

The Number field accepts numeric data where you can enter any kind of numbers such as phone number or zip code.

The schema of the Number field is given as follows:

{
    "data_type": "number",
    "display_name": "Number",
    "uid": "number",
    "field_metadata": {
        "description": "",
        "default_value": ""
    },
    "multiple": false,
    "mandatory": false,
    "unique": false
}

The parameters in the above JSON body is explained in the ‘Common field parameters’ section.

You need to enter the data_type parameter as number.

Boolean

The Boolean field accepts a true or false value.

The schema of the Boolean field is given as follows:

{
    "data_type": "boolean",
    "display_name": "Boolean",
    "uid": "boolean",
    "field_metadata": {
        "description": "",
        "default_value": ""
    },
    "multiple": false,
    "mandatory": false,
    "unique": false
}

The parameters in the above JSON body is explained in the ‘Common field parameters’ section.

You need to enter the data_type parameter as boolean.

Date

The Date field renders a calendar that allows the user to select a date and time, which is accepted in the ISO format

The schema of the Date field is given as follows:

{
    "data_type": "isodate",
    "display_name": "Date",
    "uid": "date",
    "startDate": null,
    "endDate": null,
    "field_metadata": {
        "description": "",
        "default_value": ""
    },
    "multiple": false,
    "mandatory": false,
    "unique": false
}

The parameters in the above JSON body is explained in the ‘Common field parameters’ section.

You need to enter the data_type parameter as isodate, and provide the startDate and endDate parameters if you want to display a date range.

File

The File field lets you upload or use files in your entry.

The schema of the File field is given as follows:

{
    "data_type": "file",
    "display_name": "File",
    "uid": "file",
    "extensions": [],
    "field_metadata": {
        "description": "",
        "rich_text_type": "standard"
    },
    "multiple": false,
    "mandatory": false,
    "unique": false
}

The parameters in the above JSON body is explained in the ‘Common field parameters’ section.

Set the data_type parameter as file and add the extensions parameter. Additionally, mention the "rich_text_type": "standard" key in the field_metadata parameter.

Link

The Link field accepts a valid static or relative URL and a title.

The schema of the Link field is given as follows:

{
    "data_type": "link",
    "display_name": "Link",
    "uid": "link",
    "field_metadata": {
        "description": "",
        "default_value": {
            "title": "",
            "url": ""
        }
    },
    "multiple": false,
    "mandatory": false,
    "unique": false
}

The parameters in the above JSON body is explained in the ‘Common field parameters’ section.

Set the data_type parameter as linklink, and add title and url in the default_value key within the field_metadata parameter.

Reference

The Reference field allows you to create references to entries of the same content type or other content types.

The schema of the Reference field is given as follows:

{
    "data_type": "reference",
    "display_name": "Reference",
    "reference_to": "",
    "field_metadata": {
        "ref_multiple": false
    },
    "uid": "reference",
    "mandatory": false,
    "multiple": false,
    "unique": false
}

The parameters in the above JSON body is explained in the ‘Common field parameters’ section.

You need to mention either the same content type or another content type that your parent content type will refer to in the reference_to parameter.

Group

The Group field allows you to create a group of multiple fields.

The schema of the Group field is given as follows:

{
    "data_type": "group",
    "display_name": "Group",
    "field_metadata": {},
    "schema": [{
        "data_type": "text",
        "display_name": "Single line textbox",
        "uid": "single_line",
        "field_metadata": {
            "description": "",
            "default_value": ""
        },
        "format": "",
        "error_messages": {
            "format": ""
        },
        "multiple": false,
        "mandatory": false,
        "unique": false
    }],
    "uid": "group",
    "multiple": true,
    "mandatory": false,
    "unique": false
}

The parameters in the above JSON body is explained in the ‘Common field parameters’ section.

The details of the fields that have to be added in the Group field are mentioned in the schema parameter.

Custom Field – Group Within Group

You can create a custom field by adding a ‘Group’ field within another ‘Group’ field.

The schema of the Group Within Group field is given as follows:

{
    "data_type": "group",
    "display_name": "Group_within_group",
    "field_metadata": {},
    "schema": [{
        "data_type": "group",
        "display_name": "Group_within_group_subgroup",
        "field_metadata": {},
        "schema": [{
            "data_type": "text",
            "display_name": "Single line textbox",
            "uid": "single_line",
            "field_metadata": {
                "description": "",
                "default_value": ""
            },
            "format": "",
            "error_messages": {
                "format": ""
            },
            "multiple": false,
            "mandatory": false,
            "unique": false
        }],
        "uid": "group_within_group_subgroup",
        "multiple": true,
        "max_instance": 2,
        "mandatory": false,
        "unique": false
    }],
    "uid": "group_within_group",
    "multiple": false,
    "mandatory": false,
    "unique": false
}

The parameters in the above JSON body is explained in the ‘Common field parameters’ section.

The max_instance parameter lets you decide the maximum limit for your internal Group, within the main Group schema.

Custom Field – Extensions

You can create a custom field that you can use in your content types.

The schema of the Extension field is given as follows:

{
    "display_name": "Extension",
    "uid": "text",
    "data_type": "json",
    "extension_uid": "blt002c000ce00b00000",
    "mandatory": true,
    "field_metadata": {
        "_default": true
    },
    "multiple": false,
    "unique": false
}

Field parameters explained

Let’s see the parameters in the schema in detail:

Parameters Description Supported fields
display_name This parameter determines the display name of a field. All fields
uid This parameter is the unique id of each field. All fields
data_type This parameter determines what value can be provided to the Title field. All fields
field_metadata This parameter allows you to enter additional data about a field. Also, you can add additional values under ‘field_metadata’.

  • _default: This parameter allows you to set default fields for content types.
  • default_value: This key allows you to set a default value for a field.
  • allow_rich_text: This key determines whether the editor will support rich text, and is set to ‘true’ by default for Rich Text Editors.
  • download This key allows you to provide the content for the Rich text editor field.
  • download This key provides multi line capabilities to the Rich text editor.
  • rich_text_type: This key lets you enable either the ‘basic’ or ‘advanced’ editor to enter your content.
  • download This key lets you assign a field to be a markdown by setting its value to ‘true’.
All fields
multiple This parameter allows you to assign multiple values to a field. By default, this parameter is set to ‘false’ for the ‘Title’ field. All fields
mandatory This parameter determines whether a field can be left without a value or not. If the mandatory parameter of a field is set to ‘true’, the user cannot leave this field empty. All fields
unique This parameter decides whether the value entered in the field has to be unique or not. All fields
format This parameter takes a regex that you can use to validate the value of a field. Single line textbox, Multi line textbox
error_messages This parameter is the error message that will be displayed if a field value is not validated. You can set a format for it as well. Single line textbox, Multi line textbox
enum This parameter allows you to provide the choice for the ‘Select’ field. Select
reference_to This parameter allows you to set a reference to any content type. Reference
format This parameter allows you to set the schema for ‘Group’ and nested Group fields. Group, nested Group fields
schema The details of the fields that have to be added in the Group field are mentioned in the schema parameter. Group, Nested Group fields
max_instance This parameter lets you decide the maximum limit for your internal Group, within the main Group schema. Nested Group fields
Was this article helpful?
top-arrow