About Hierarchies

Hierarchies allow you to model tree structures of content. A hierarchy is a natural way of using a tree structure to represent the relationship between objects. It might be a page structure for a website, a list of worldwide store locations organised by country and city, a structured list of product content, app settings or a list of ingredients and meal types for a recipe site. Hierarchies lend themselves to many use cases.

In Dynamic Content, a hierarchy provides a way to link content items together. The content items in a hierarchy are normal content items that have relationships to each other. Because they are normal content items, you can work with these content items independently and manage and publish items in the normal way. The main difference is that a content item that is part of a hierarchy will have a relationship with its parent.

Example hierarchy

The example below shows one possible use case, a website menu that's built from a hierarchy. On the left you can see the hierarchy as modelled in Dynamic Content. Users can see at a glance how the website is structured and where content should be displayed. On the right is how the hierarchy is consumed in the app, providing the structure for the site navigation.

Hierarchies let users see the whole context. It might be a page or website layout, a buyer's guide or a list of tags to apply to blog posts. The user interface makes it easy to see all of the tree, and decide where to add and remove nodes if they need to.

Schema examples

You can add each of the schema examples in this section to your Dynamic Content hub by choosing "Content type schemas" from the development menu, then "Create schema", and selecting "Start with an example" from the create schema window. Choose the schema you would like to add from the hierarchies category. See using the schema examples for more details.

Example 1: The site menu

The example shown below is a simple hierarchy representing the menu for a website, including sections for mens, womens, electricals and a blog.

Each node in the hierarchy will be a site-menu-item content item, so the childContentTypes array in our schema will include a single entry for the https://example.com/site-menu-item content type schema.

The trait:sortable object is set up to support the hierarchy drag and drop feature. Users will be able to drag hierarchy nodes to anywhere within the hierarchy.

Because hierarchies are just content items, you can link all or part of a hierarchy to another content item with a content-link or content-reference. For example, we could assign a category such as electricals to a banner so that appropriate content is shown when the user browses to each section of the site.

The schema also includes a title and a description for each section. The complete schema is shown below.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "https://schema-examples.com/site-menu-item",
    "$comment": "Docs: https://amplience.com/docs/development/schema-examples/hierarchies/site-menu-hierarchy.html",
    "title": "Site menu hierarchy",
    "description": "A simple hierarchy used to model site navigation. Supports hierarchy drag and drop.",
    "allOf": [
        {
            "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content"
        },
        {
            "$ref": "http://bigcontent.io/cms/schema/v2/hierarchy#/definitions/hierarchy-node"
        }
    ],
    "trait:hierarchy": {
        "childContentTypes": [
            "https://schema-examples.com/site-menu-item"
        ]
    },
    "trait:sortable": {
        "sortBy": [
            {
                "key": "default",
                "paths": [
                    "/_meta/hierarchy/position"
                ]
            }
        ]
    },
    "type": "object",
    "properties": {
        "title": {
            "title": "Title",
            "description": "Title used for the menu item",
            "type": "string",
            "minLength": 0,
            "maxLength": 100
        },
        "description": {
            "title": "Description",
            "description": "description",
            "type": "string",
            "minLength": 0,
            "maxLength": 100
        },
        "_meta": {
            "type": "object",
            "properties": {
                "deliveryKey": {
                    "type": "string",
                    "title": "Delivery key",
                    "description": "The delivery key is used as the URL slug"
                }
            }
        }
    },
    "propertyOrder": []
}

The Hierarchy API can be used to traverse the tree and return the children of each node.

Example 2: Multiple content types: the page hierarchy

This more advanced example makes use of two content types to implement an ideas and advice section on a website.

The page-hierarchy content type (1 in the image above) represents a category such as "Lighting and electrical" or "Heating and plumbing". It contains a title, description, image and a ranking. The page-hierarchy-node content type (2 in the image above) is the help page itself, including content such as text and images.

The start of the page-hierarchy schema is shown below. The childContentTypes array in the trait:hierarchy object contains two items: the page-hierarchy and the page-hierarchy-node. This is because we want to be able to add one category as a child of another and to add the help pages as children of a category.

The page-hierarchy schema

{
   "$schema":"http://json-schema.org/draft-07/schema#",
   "$id":"https://schema-examples.com/page-hierarchy",
   "title":"Page Category",
   "description":"Category that can contain pages or subcategories",
   "allOf":[
      {
         "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/content"
      },
      {
         "$ref":"http://bigcontent.io/cms/schema/v2/hierarchy#/definitions/hierarchy-node"
      }
   ],
   "trait:hierarchy":{
      "childContentTypes":[
         "https://schema-examples.com/page-hierarchy",
         "https://schema-examples.com/page-hierarchy-node"
      ]
   },
…

The page-hierarchy-node schema

Note that for the page-hierarchy-node schema the childContentTypes array is empty because we don't want to add any children to page hierarchy nodes.

{
   "$schema":"http://bigcontent.io/cms/schema/v2/schema#",
   "$id":"https://schema-examples.com/page-hierarchy-node",
   "title":"Page",
   "description":"Page as a hierarchy node",
   "allOf":[
      {
         "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/content"
      },
      {
         "$ref":"http://bigcontent.io/cms/schema/v2/hierarchy#/definitions/hierarchy-node"
      }
   ],
   "trait:hierarchy":{
      "childContentTypes":[

      ]
   },
…

Example 3: Using a hierarchy to tag content: the ingredients hierarchy

In this example an ingredients hierarchy is used to tag recipes. There are 2 content type schemas: the ingredients hierarchy and the recipe schema which uses an array of content types to allow the user to choose one or more items from the hierarchy. This puts the user in control by allowing recipes to be tagged dynamically rather than having to choose from a preset list of values.

The recipe content item tagged with multiple items from the hierarchy is shown below. Note that this schema makes use of the [/docs/dev-tools/content-modeling/hierarchies/managing-hierarchies/#the-hierarchy-chooser-extension) to make it easy to browse and add items from a hierarchy rather than a flat view of content items.

The ingredients property in the recipe schema is an array of content links of the ingredients-list type. Users can choose one or more ingredients to tag the recipe. A search index could then be used to allow the user to find recipes which have been tagged with their chosen ingredients.

   "ingredients":{
      "title":"ingredients",
      "type":"array",
      "minItems":0,
      "maxItems":10,
      "items":{
         "allOf":[
            {
               "$ref":"http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
            },
            {
               "properties":{
                  "contentType":{
                     "enum":[
                        "https://schema-examples.com/ingredients-list"
                     ]
                  }
               }
            }
         ]
      }
   }

Related pages

Creating content type schemas for hierarchies

Sorting hierarchy nodes

Using the schema examples

Retrieving content from a hierarchy

Working with hierarchies

Hierarchy API

List, filter and sort content

Hierarchies limits