Creating a schema for hierarchies

A hierarchy is a tree of nodes, each of which is a content item. Each node can have descendants, or child nodes. You can model a hierarchy in which all nodes are the same content type, or choose to define your hierarchy so it can contain items of multiple content types.

In each content type schema that defines a content item that can be added as a node to a hierarchy, you will need to specify the content types of the items that can be added as child nodes. To do this you will make use of Amplience specific extensions to the JSON Schema standard.

You can find example hierarchies in the schema library available from the "Create Schema" dialog in Dynamic Content. The schemas are also included on the About hierarchies page.

Including the hierarchy definitions

In your schema core definitions you will need to include the hierarchy definitions as follows:

"$ref": "http://bigcontent.io/cms/schema/v2/hierarchy#/definitions/hierarchy-node"

Your schema will now look something like:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "https://example.com/site-menu-item",

    "title": "Site menu",
    "description": "A node in the site menu hierarchy",

    "allOf": [
        {
          "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content"
        },
        {
          "$ref": "http://bigcontent.io/cms/schema/v2/hierarchy#/definitions/hierarchy-node"
        }
    ],

...

}

The hierarchy trait

The trait keyword is an Amplience specific keyword that is used to include additional information about a schema. By including trait:hierarchy you can specify that a content item created from this schema can be added to a hierarchy. You also provide a childContentTypes array that defines the type of content items that can be added as child nodes. You can leave this array blank if you want a node created from the schema to be a leaf node with no children.

In the example shown below, we are modelling a hierarchy for a site menu. Each node in the hierarchy will be the same content type, so we just include the schema itself in the array. Only content items created from the schema registered with the URL https://example.com/site-menu-item can be added as children.

"trait:hierarchy": {
        "childContentTypes": [
            "https://example.com/site-menu-item"

        ]
    },

The schema editor includes shortcuts to make it easier to add traits to your schemas.

Changing a schema to use the hierarchy-trait

If you change a schema to include the hierarchy-trait object, any content items created with the schema prior to the change will need to be converted to reflect the update to being hierarchical content. Your users will be notified if a content item needs converting. See Converting items for use with hierarchies.

Unsupported content type nodes

If you remove a content type from the childContentTypes and nodes of that type are still included in a hierarchy, this creates "unsupported content type" nodes. Unsupported content type nodes will prevent drag and drop of nodes within a branch. For more information, see the User guide - Unsupported content type nodes.

Adding traits in the schema editor

The schema editor includes shortcuts for adding a trait:hierarchy object to your schema. Just type control + space and and choose "trait:hierarchy" from the popup menu.

The trait will be added to your schema. Click inside the trait object, type control + space again and choose "childContentTypes" from the menu. Then add any content types you want to allow to be added as children of nodes of the type defined in the schema.

Related pages

Introducing hierarchies

Creating content type schemas for hierarchies

Working with hierarchies

List, filter and sort content

Hierarchy API

Hierarchies limits