---
canonical: https://amplience.com/developers/docs/dev-tools/content-modeling/hierarchies/hierarchy-schemas/
title: Creating a schema for hierarchies
description: How to create content type schemas for hierarchy nodes
image: https://cdn.media.amplience.net/i/ampproduct/schema-editor-hierarchy-trait-1?w=1200&h=630
image_width: 1200
image_height: 630
audience: Developer
date_published: 2025-01-30
date_modified: 2025-04-30
---

# Creating a schema for hierarchies

A [hierarchy](https://amplience.com/developers/docs/dev-tools/content-modeling/hierarchies/about-hierarchies/) 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](https://amplience.com/developers/docs/dev-tools/content-modeling/hierarchies/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:

```json
{
	"$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.

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

		]
	},
```

The schema editor includes [shortcuts](#adding-traits-in-the-schema-editor) to make it easier to add traits to your schemas.

> **Note: 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](https://amplience.com/developers/docs/user-guides/produce-content/hierarchies/#converting-existing-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](https://amplience.com/developers/docs/user-guides/produce-content/hierarchies/#unsupported-content-types).

## Adding traits in the schema editor

The [schema editor](https://amplience.com/developers/docs/dev-tools/guides-tutorials/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.

![Using a shortcut to add a hierarchy trait in the schema editor.](https://cdn.media.amplience.net/i/ampproduct/schema-editor-hierarchy-trait-1?w=1880&fmt=png 'Using a shortcut to add a hierarchy trait in the schema editor.')

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.

![Adding the childContentTypes array.](https://cdn.media.amplience.net/i/ampproduct/schema-editor-hierarchy-trait-2?w=1880&fmt=png 'Adding the childContentTypes array.')

## Related pages

[Introducing hierarchies](https://amplience.com/developers/docs/dev-tools/content-modeling/hierarchies/about-hierarchies/)

[Creating content type schemas for hierarchies](https://amplience.com/developers/docs/dev-tools/content-modeling/hierarchies/hierarchy-schemas/)

[Working with hierarchies](https://amplience.com/developers/docs/user-guides/produce-content/hierarchies)

[List, filter and sort content](https://amplience.com/developers/docs/apis/content-delivery/filter-api)

[Hierarchy API](https://amplience.com/developers/docs/apis/content-delivery/hierarchy-api)

[Hierarchies limits](https://amplience.com/developers/docs/apis/limits/#hierarchies)