JSON Tree Introduction in v16.9

Overview

This page describes the JSON-based taxonomy tree storage model introduced in brXM version 16.9. The JSON tree model is designed to improve performance for large taxonomy trees by storing the entire category hierarchy as a single binary property.

Purpose

The JSON tree feature provides an alternative to the traditional JCR node-tree representation for taxonomy documents. When enabled, it serializes the category hierarchy into a single hippotaxonomy:categories binary property, replacing the tree of child hippotaxonomy:category JCR nodes.

Taxonomy Storage Models

JCR Node-Tree Model (Before 16.9)

Prior to version 16.9, taxonomy categories were stored as child nodes under a hippotaxonomy:taxonomy node. Each category was represented as a separate JCR node with localized properties.

/content/taxonomies/exampletaxonomy/exampletaxonomy:
  /main-category:
    jcr:primaryType: hippotaxonomy:category
    hippotaxonomy:key: main-category
    locale.en.name: Main category
    locale.en.description: Description of main category
    locale.en.synonyms: [Synonym 1, Synonym 2]
    locale.nl.name: Hoofdcategorie
    locale.nl.description: Beschrijving van hoofdcategorie
  /secondary-category:
    jcr:primaryType: hippotaxonomy:category
    hippotaxonomy:key: secondary-category
    locale.en.name: Secondary category
    locale.en.description: Description of secondary category
    locale.en.synonyms: [Synonym 1, Synonym 2]
    locale.nl.name: Secundaire categorie
    locale.nl.description: Beschrijving van secundaire categorie 

JSON Tree Model (16.9 and Later)

Starting with version 16.9, taxonomy categories can be stored as a JSON array in the hippotaxonomy:categories binary property. This approach eliminates the need for individual category nodes.

/content/taxonomies/exampletaxonomy/exampletaxonomy/hippotaxonomy:categories:
[
  {
    "key": "main-category",
    "name": "Main category",
    "children": [],
    "infosByLocale": {
      "en": {
        "name": "Main category",
        "description": "Description of main category",
        "synonyms": [ "Synonym 1", "Synonym 2" ]
      },
      "nl": {
        "name": "Hoofdcategorie",
        "description": "Beschrijving van hoofdcategorie"
      }
    }
  },
  {
    "key": "secondary-category",
    "name": "Secondary category",
    "children": [],
    "previous": "main-category",
    "infosByLocale": {
      "en": {
        "name": "Secondary category",
        "description": "Description of secondary category",
        "synonyms": [ "Synonym 1", "Synonym 2" ]
      },
      "nl": {
        "name": "Secundaire categorie",
        "description": "Beschrijving van secundaire categorie"
      }
    }
  }
]

The JSON tree model improves performance by reducing the number of database records and queries required to access taxonomy data.

Configuration

To enable the JSON tree model for a taxonomy plugin instance, set the following property in the CMS plugin configuration node:

/hippo:configuration/hippo:frontend/cms/cms-services/taxonomyService:
  taxonomy.json.tree.enabled: true

• If taxonomy.json.tree.enabled is false or not set (default), both the Taxonomies perspective and the delivery tier use the existing JCR category tree.
• If the flag is true and a taxonomy document has not been migrated, both perspectives continue to use the JCR category tree.
• If the flag is true and a taxonomy document has been migrated, both perspectives use the JSON tree model.

Upgrade Considerations

After upgrading to version 16.9, you can choose to use the JSON tree model for taxonomy documents with large category trees. This is recommended for projects experiencing performance issues due to large taxonomies, but it is not required for all projects.

Both the CMS and the delivery tier support both the JCR node-tree and JSON tree models.

Migrating Existing Taxonomies

Version 16.9 provides a Groovy updater script named TaxonomyJsonMigrator, available in the Updater Editor. This script:

• Visits all hippotaxonomy:taxonomy nodes
• Converts their JCR category trees to the JSON tree model
• Removes the category nodes to improve performance

For large taxonomy trees, use the updater script to automate migration. The script does not create entries in the revision history.

With default settings, migrating a JCR tree with approximately 4,000 categories to the JSON tree model takes about 15–20 seconds.

Important:
After migrating a taxonomy document to the JSON tree model, you cannot revert it to the JCR category tree model.