Tree fields

Tree fields are a specific type of custom field whose values are organized as a hierarchy of nodes. They can be used to model taxonomies such as categories, industries, topics, or any data that naturally fits in a tree. Tree field values can be assigned to Exhibitors, People, Products (Items) and Plannings (Sessions).

A tree field is made of nodes identified by a path. Nodes can be selectable (assignable to an entity) or non-selectable (used only as grouping labels in the hierarchy). Each node carries its own translated labels.

Paths are represented as a separator-joined string using |~^ as the separator. For example, a sub-category SUB-1 under the category CAT-1 under ROOT is represented by the path ROOT|~^CAT-1|~^SUB-1.

Objects

1. Create a FieldDefinition of type tree

The createFieldDefinition mutation is used to create a new custom field. To create a tree field, set type to TREE and provide the initial tree structure through the following inputs:

treeOptions — the list of selectable nodes. Each option is defined by a path, which is an array of string node identifiers from the root to the target node.
treeTranslations — the translated labels of every node in the tree (both selectable and non-selectable). Each entry has a value (the full node path joined with |~^) and a list of translations per language.

Selectable vs. labeled nodes

Not every node needs to be selectable. Intermediate (grouping) nodes are allowed to exist in treeTranslations without appearing in treeOptions. However every node referenced in a path — whether selectable or not — must have a corresponding entry in treeTranslations so it can be displayed with a proper label.

Arguments

eventId — The Id of the Event on which the custom field needs to be created.
name — The name of the custom field.
target — The Entity on which the custom field needs to be created (PEOPLE, EXHIBITOR, SESSION or ITEM).
type — Must be TREE.
treeOptions — The list of selectable node paths.
treeTranslations — The labels of every node of the tree, in every language.

Query

mutation createFieldDefinition($input: CreateFieldDefinitionV2Input!) {
  createFieldDefinition(input: $input) {
    event {
      id
    }
    fieldDefinition {
      ... on TreeFieldDefinition {
        id
        name
        tree {
          value
          path {
            value
            translations {
              language
              value
            }
          }
        }
      }
    }
    errors {
      code
      message
    }
  }
}

Variables

{
  "input": {
    "eventId": "RXZlbnRfMQ==",
    "name": "Industry",
    "target": "EXHIBITOR",
    "type": "TREE",
    "isEditable": true,
    "isVisible": true,
    "translations": [
      { "language": "en_US", "name": "Industry" },
      { "language": "fr_FR", "name": "Secteur d'activité" }
    ],
    "treeOptions": [
      { "path": ["ROOT", "CAT-1"] },
      { "path": ["ROOT", "CAT-1", "SUB-1-1"] },
      { "path": ["ROOT", "CAT-1", "SUB-1-2"] },
      { "path": ["ROOT", "CAT-2"] },
      { "path": ["ROOT", "CAT-2", "SUB-2-1"] }
    ],
    "treeTranslations": [
      {
        "value": "ROOT",
        "translations": [
          { "language": "en_US", "value": "Root" },
          { "language": "fr_FR", "value": "Racine" }
        ]
      },
      {
        "value": "ROOT|~^CAT-1",
        "translations": [
          { "language": "en_US", "value": "Category 1" },
          { "language": "fr_FR", "value": "Catégorie 1" }
        ]
      },
      {
        "value": "ROOT|~^CAT-1|~^SUB-1-1",
        "translations": [
          { "language": "en_US", "value": "Sub Category 1-1" },
          { "language": "fr_FR", "value": "Sous-catégorie 1-1" }
        ]
      },
      {
        "value": "ROOT|~^CAT-1|~^SUB-1-2",
        "translations": [
          { "language": "en_US", "value": "Sub Category 1-2" },
          { "language": "fr_FR", "value": "Sous-catégorie 1-2" }
        ]
      },
      {
        "value": "ROOT|~^CAT-2",
        "translations": [
          { "language": "en_US", "value": "Category 2" },
          { "language": "fr_FR", "value": "Catégorie 2" }
        ]
      },
      {
        "value": "ROOT|~^CAT-2|~^SUB-2-1",
        "translations": [
          { "language": "en_US", "value": "Sub Category 2-1" },
          { "language": "fr_FR", "value": "Sous-catégorie 2-1" }
        ]
      }
    ]
  }
}

2. Update a FieldDefinition of type tree

The updateFieldDefinition mutation can also be used on a tree field to replace the whole tree structure (treeOptions and treeTranslations) in a single call.

⚠️ Do not use updateFieldDefinition once values are assigned

Avoid using updateFieldDefinition to modify the tree structure of a FieldDefinition whose values are already assigned to entities (Exhibitors, People, Products or Plannings). This mutation overwrites the whole tree and performs no validation to preserve existing assignments, which can result in orphaned or inconsistent values.

Once the tree is in use, prefer the dedicated node-level mutations:

createTreeFieldNode
updateTreeFieldNode
moveTreeFieldNode
deleteTreeFieldNode

These mutations provide validation and ensure data consistency when nodes are added, renamed, moved or removed.

3. Create a tree node — `createTreeFieldNode`

The createTreeFieldNode mutation adds a new node to an existing tree at a specific position, relative to an existing reference node.

Arguments

fieldDefinitionId — The Id of the tree FieldDefinition to add a node to.
targetNode — The full path of the reference node used for positioning (e.g. ROOT|~^CAT-1).
position — Where to place the new node relative to targetNode: ABOVE, BELOW or INSIDE.
nodeId — The identifier of the new node (e.g. SUB-NEW). Combined with its parent path, it forms the new node's full path.
translations — The translated labels for the new node.
isSelectable — Whether the new node should be assignable to entities (present in treeOptions) or used only as a grouping label.

Query

mutation CreateTreeFieldNode($input: CreateTreeFieldNodeInput!) {
  createTreeFieldNode(input: $input) {
    fieldDefinition {
      ... on TreeFieldDefinition {
        id
        tree {
          value
          path {
            value
            translations {
              language
              value
            }
          }
        }
      }
    }
    errors {
      code
      message
      path
    }
  }
}

Variables

{
  "input": {
    "fieldDefinitionId": "RmllbGREZWZpbml0aW9uXzY=",
    "targetNode": "ROOT|~^CAT-1",
    "position": "INSIDE",
    "nodeId": "SUB-1-3",
    "isSelectable": true,
    "translations": [
      { "language": "en_US", "value": "Sub Category 1-3" },
      { "language": "fr_FR", "value": "Sous-catégorie 1-3" }
    ]
  }
}

4. Update a tree node — `updateTreeFieldNode`

The updateTreeFieldNode mutation updates an existing node's translations and/or its selectability. It does not move the node in the tree — use moveTreeFieldNode for that.

Arguments

fieldDefinitionId — The Id of the tree FieldDefinition.
currentNodePath — The full path of the node to update (e.g. ROOT|~^CAT-1|~^SUB-1-1).
translations (optional) — When provided, replaces all existing translations of the node.
isSelectable (optional) — When provided, toggles whether the node can be assigned to entities.

Query

mutation UpdateTreeFieldNode($input: UpdateTreeFieldNodeInput!) {
  updateTreeFieldNode(input: $input) {
    fieldDefinition {
      ... on TreeFieldDefinition {
        id
        tree {
          value
          path {
            value
            translations {
              language
              value
            }
          }
        }
      }
    }
    errors {
      code
      message
      path
    }
  }
}

Variables

{
  "input": {
    "fieldDefinitionId": "RmllbGREZWZpbml0aW9uXzY=",
    "currentNodePath": "ROOT|~^CAT-1",
    "isSelectable": true,
    "translations": [
      { "language": "en_US", "value": "Category 1 — Updated" },
      { "language": "fr_FR", "value": "Catégorie 1 — Mise à jour" }
    ]
  }
}

5. Move a tree node — `moveTreeFieldNode`

The moveTreeFieldNode mutation moves a node (and all its descendants) to a different position in the tree. Existing values assigned to the node or its descendants are kept in sync with the new path.

Arguments

fieldDefinitionId — The Id of the tree FieldDefinition.
currentNodePath — The current full path of the node to move.
targetNode — The full path of the reference node used for the destination.
position — Where to place the moved node relative to targetNode: ABOVE, BELOW or INSIDE.

Query

mutation MoveTreeFieldNode($input: MoveTreeFieldNodeInput!) {
  moveTreeFieldNode(input: $input) {
    fieldDefinition {
      ... on TreeFieldDefinition {
        id
        tree {
          value
          path {
            value
            translations {
              language
              value
            }
          }
        }
      }
    }
    errors {
      code
      message
      path
    }
  }
}

Variables

{
  "input": {
    "fieldDefinitionId": "RmllbGREZWZpbml0aW9uXzY=",
    "currentNodePath": "ROOT|~^CAT-2|~^SUB-2-1",
    "targetNode": "ROOT|~^CAT-1|~^SUB-1-1",
    "position": "ABOVE"
  }
}

6. Delete a tree node — `deleteTreeFieldNode`

The deleteTreeFieldNode mutation deletes a node and all its descendants from the tree. The Ids of the deleted FieldValue entities are returned in the payload so clients can reconcile their own state.

Cascading delete

Deleting a branch node deletes every descendant as well. Any value assigned to the deleted nodes will be removed from the related Exhibitors, People, Products or Plannings.

Arguments

fieldDefinitionId — The Id of the tree FieldDefinition.
currentNodePath — The full path of the node to delete.

Query

mutation DeleteTreeFieldNode($input: DeleteTreeFieldNodeInput!) {
  deleteTreeFieldNode(input: $input) {
    deletedFieldValueIds
    fieldDefinition {
      ... on TreeFieldDefinition {
        id
        tree {
          value
          path {
            value
            translations {
              language
              value
            }
          }
        }
      }
    }
    errors {
      code
      message
      path
    }
  }
}

Variables

{
  "input": {
    "fieldDefinitionId": "RmllbGREZWZpbml0aW9uXzY=",
    "currentNodePath": "ROOT|~^CAT-1"
  }
}

Objects​

1. Create a FieldDefinition of type tree​

Arguments​

Query​

Variables​

2. Update a FieldDefinition of type tree​

3. Create a tree node — createTreeFieldNode​

Arguments​

Query​

Variables​

4. Update a tree node — updateTreeFieldNode​

Arguments​

Query​

Variables​

5. Move a tree node — moveTreeFieldNode​

Arguments​

Query​

Variables​

6. Delete a tree node — deleteTreeFieldNode​

Arguments​

Query​

Variables​

Objects

1. Create a FieldDefinition of type tree

Arguments

Query

Variables

2. Update a FieldDefinition of type tree

3. Create a tree node — `createTreeFieldNode`

Arguments

Query

Variables

4. Update a tree node — `updateTreeFieldNode`

Arguments

Query

Variables

5. Move a tree node — `moveTreeFieldNode`

Arguments

Query

Variables

6. Delete a tree node — `deleteTreeFieldNode`

Arguments

Query

Variables