Schema reference: new features

As part of this release of Next Generation Authoring, we've added support for some additional features included in JSON schema Draft 7.

Conditionals

Conditionals (if/ then/ else) allow you to set the state and value of one or more properties in a schema, based on the state of another property. For example, you can use conditionals to enable or disable a property based on a user selection, or hide or show one or a group of properties.

In this section we've provided examples of some of the common uses for conditionals. See conditionals- schema examples for more.

info

We don't currently support all of the features specified in the JSON schema conditionals reference. In particular, wrapping multiple if/then conditions inside allOf is not supported.

Hiding and showing properties

In this example the date field is shown or hidden based on the state of the hasDate field.

"properties": {
        "event": {
            "title": "Event",
            "description": "Our client meetings",
            "type": "object",
            "properties": {
                "title": {
                    "title": "Event Name",
                    "type": "string"
                },
                "hasDate": {
                    "type": "boolean"
                }
            },
            "if": {
                "properties": {
                    "hasDate": {
                        "const": false
                    }
                }
            },
            "then": {},
            "else": {
                "properties": {
                    "date": {
                        "type": "string",
                        "format": "date"
                    }
                }
            }
        }
    }

Conditional validation

In the example shown below, the country property is used to determine the validation used for the addressCode property. Different validation is used for a UK or US address.

    "properties": {
        "addresssValidation": {
            "type": "object",
            "title": "Address validation",
            "properties": {
                "country": {
                    "type": "string",
                    "title": "Choose Country",
                    "default": "uk",
                    "oneOf": [
                        {
                            "const": "uk",
                            "title": "United Kingdom"
                        },
                        {
                            "const": "us",
                            "title": "United States"
                        }
                    ]
                }
            },
            "if": {
                "properties": {
                    "country": {
                        "const": "uk"
                    }
                }
            },
            "then": {
                "properties": {
                    "addressCode": {
                        "type": "string",
                        "title": "Post Code",
                        "pattern": "^[A-Z]{1,2}[0-9][0-9A-Z]? [0-9][A-Z]{2}$"
                    }
                }
            },
            "else": {
                "properties": {
                    "addressCode": {
                        "type": "string",
                        "title": "Zip code",
                        "pattern": "^[0-9]{5}(?:-[0-9]{4})?$"
                    }
                }
            }
        }
    }

Read only properties

Read only and write only properties are now supported, as defined in the JSON Schema specification. A read only property cannot be modified.

Read only property example

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.

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

Hidden properties

You can add ui:component: "none" to a property to hide it from the user so it's not shown on the content form. Hidden properties can be const values, or updated using the Content Management API rather than from the content form.

If a value is set for a hidden property it will be shown in the JSON output for a content item, but it will not be displayed in the content form.

"properties": {
        "hiddenItem": {
            "title": "hiddenItem",
            "type": "string",
            "ui:component": "none"
        }
    }

Usage notes

• Note that properties with no value set will not be included in the JSON output for a content item

• Be careful of listing this property as required. Users could end up not being able to save their content form but with no indication as to why. This could happen if developers update the content item using the Content Management API while users are updating the content item in the content form.

Content palettes

A content palette allows you to select from an array of objects of different types, defined with the oneOf keyword.

Each object in the array should be defined in the following format. oneOf validation dictates that a value needs to match against one and only one schema in its array, so a const is needed to differentiate each item. "ui:component":"none" is used so that the const value is not shown in the form.

The example below shows an image property with an image link and a string for alt text. This is one of the objects included in the array that is shown to the user as a content palette.

   "type":"object",
   "title":"Simple Image",
   "properties":{
      "type":{
         "const":"image",
         "ui:component":"none"
      },
      "image":{
         "title":"Image",
         "allOf":[
            {
               "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
            }
         ]
      },
      "alttext":{
         "type":"string",
         "title":"Image Alt text"
      }
   }

The full exampleList array property shown below defines three objects: markdown text, an image link with alt text and a string used to represent a link address.

If there are 3 or fewer items defined in the array then the user selects content using buttons, while more than 3 items are shown in a menu with optional icons. See supported icons for a list of the icons that are available to use in the selection menu of content palettes.

{
  "properties": {
    "exampleList": {
      "type": "array",
      "title": "Flexible list",
      "items": {
        "oneOf": [
          {
            "type": "object",
            "title": "Rich Text block",
            "properties": {
              "type": {
                "const": "paragraph",
                "ui:component": "none"
              },
              "body": {
                "type": "string",
                "format": "markdown",
                "title": "For headings or paragraphs"
              }
            }
          },
          {
            "type": "object",
            "title": "Simple Image",
            "properties": {
              "type": {
                "const": "image",
                "ui:component": "none"
              },
              "image": {
                "title": "Image",
                "allOf": [
                  {
                    "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
                  }
                ]
              },
              "alttext": {
                "type": "string",
                "title": "Image Alt text"
              }
            }
          },
          {
            "type": "object",
            "title": "Link",
            "properties": {
              "type": {
                "const": "link",
                "ui:component": "none"
              },
              "linkitem": {
                "type": "object",
                "title": "Link Details",
                "properties": {
                  "linklabel": {
                    "title": "Link Label",
                    "type": "string"
                  },
                  "linkaddress": {
                    "type": "string",
                    "title": "Link Address",
                    "ui:component": {
                      "params": {
                        "placeholder": "http://"
                      }
                    }
                  }
                },
                "propertyOrder": []
              }
            }
          }
        ]
      }
    }
  }
}

Go to content palette, schema examples for more examples of content palettes in use.

Improved validation

Support has now been included for the contains keyword for use with array properties.

Contains

Contains allows you to specify that an array must contain at least one item that matches specified schema. This can include a number which is greater than or equal to a specified amount, a string greater than a specified length or a string equal to a value defined in a const.

The example below shows the use of contains to validate two array properties.

"properties": {
        "numberArray": {
            "title": "Number array",
            "description": "An array of numbers",
            "type": "array",
            "minItems": 0,
            "maxItems": 10,
            "items": {
                "type": "number"
            },
            "contains":
                {
                    "type": "number",
                    "minimum": 10
                }
        },
        "stringArray": {
            "title": "String array",
            "description": "An array of strings",
            "type": "array",
            "minItems": 0,
            "maxItems": 10,
            "items": {
                "type": "string"
            },
            "contains":
                {
                    "type": "string",
                    "minLength": 10
                }
        }
    }

Required properties

There are some differences in the way required properties are handled in Next Generation Authoring. To ensure that users will not be able to save a content item without filling in a valid value for a required property, you need to make the field required and include some additional validation. Even if the required field is edited and left empty, it cannot be saved until it passes the specified validation.

To ensure that a string field must be entered and include a non empty value we include it in the list of required properties and set the minLength of the string to 1.

"properties": {
        "textString": {
            "title": "A string of text",
            "description": "This field is required",
            "type": "string",
            "minLength": 1
        }
    },
    "required": [
        "textString"
    ]

In the example below we have an array of strings and want to ensure that at least one item is added to the array. The tags array is included in the list of required properties and minItems is set to 1. For additional validation we have also set the minLength of each string entered to be 1.

"properties": {
        "tags": {
            "title": "Tags",
            "description": "A list of tags",
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
                "type": "string",
                "minLength": 1
            }
        }
    },
    "required": [
        "tags"
    ]