YAML Format

This page describes the YAML format used for config definitions in Bloomreach Content source files. For additional context and examples, see Manage Configuration and Manage Content.

Overview

Bloomreach Content configuration uses YAML format compliant with version 1.1. Each module contains multiple configuration source files. These files can define one or more config definitions, each representing a tree of nodes and properties. These trees are merged into the Configuration Model. Modules can also include content source files, which define a single node tree rooted at a base node. Content sources are not merged into the Configuration Model but are applied based on specific actions.

Node Tree Structure

Each configuration tree starts at a specific base node and recursively defines properties and child nodes.

definitions:
  config:
    /path/to/base-node:
      property: value
      /child-node:
        jcr:primaryType: some:type

In this example, the tree is rooted at /path/to/base-node. The path must be absolute (start with /). The definition adds a property named property with value value to base-node and creates a child node named child-node with primary type some:type. The repository must recognize the primary type for node creation to succeed.

A property is defined by a YAML key that does not start with /. Child nodes are defined by keys that start with /. Child nodes can also have their own properties and further nested child nodes.

Properties

Defining Properties

You can define properties using a simple key-value syntax:

property: value

Multiplicity

To define multi-valued properties, use square brackets:

property1: []
property2: [value]
property3: [value1, value2, value3]
  • property1 is an empty multi-valued property.
  • property2 is a single-valued property in multi-valued form.
  • property3 contains three values.

Type Detection

If you do not specify a type, Bloomreach Content infers it from the value. The following types are detected automatically:

  • string
  • long
  • double
  • boolean (true, false)
  • date

If a double value does not include a decimal point, it may be interpreted as long. To ensure a value is treated as double, add .0 to the number.

For other types, specify the type explicitly:

uri:
  type: uri
  value: http://www.example.com

Explicit type declaration is required for:

  • binary
  • name
  • path
  • reference
  • weakreference
  • uri
  • decimal (for integers larger than long supports)

These types correspond to JCR property types.

For properties named jcr:primaryType and jcr:mixinTypes, the type name is assumed.

If a multi-valued property has no values, the type defaults to string. To use a different type, specify it:

multi-valued-long:
  type: long
  value: []

All values in a multi-valued property must have the same type. Mixed types will cause a parsing error.

Reference and Weakreference Properties

You can define reference and weakreference properties in three ways:

  1. By UUID:

    reference-property:
  type: reference # or weakreference
  value: cafebabe-cafe-babe-cafe-babecafebabe

  2. By absolute path:

    absolute-path-reference-property:
  type: reference
  path: /some/node/path

  3. By path relative to the definition root node (supported only in content definitions):

    definitions:
  config:
    /path/to/base-node:
      jcr:primaryType: some:type
      node-b-reference:
        type: reference
        path: node-a/node-b # relative to /path/to/base-node
      /node-a:
        jcr:primaryType: some:type
        /node-b:
          jcr:primaryType: some:type
          root-node-reference:
            type: reference
            path: '' # reference to /path/to/base-node

Relative paths are used for content extraction and relocation, preserving internal references when node UUIDs change. References outside the content definition must use absolute paths or UUIDs.

External Resources

You can externalize property values to resource files, which is useful for complex or binary values.

single-valued-resource:
  type: string
  resource: schema/my-schema.xml
multi-valued-resource:
  type: binary
  resource: [image1.png, image2.png]
  • A relative resource path (not starting with /) is resolved relative to the source file.
  • A resource path starting with / is resolved relative to the module's hcm-config directory.

Property Merging

When merging configuration definitions, a property defined in a later definition replaces the earlier value by default. If the new value differs in type or multiplicity, an error occurs.

You can control merging behavior with the following operations:

override-property:
  operation: override
  type: long
  value: [12, 35]
  • Use override to change the type or multiplicity. You must specify the new type.
add-values-property:
  operation: add
  value: [green, yellow]
  • Use add to append values to a multi-valued property. For example, if the property previously contained green and blue, the result is green, blue, green, yellow.
delete-property:
  operation: delete
  • Use delete to remove a property. Any attempt to re-add or merge values into a deleted property results in an error.

Nodes

Primary Type and Mixins

To create a node, you must specify its primary type using the jcr:primaryType property. The type must be registered in JCR before node creation.

If you need to change the primary type of an existing node, use the override operation:

/pre-existing-node:
  jcr:primaryType:
    operation: override
    value: different:type

Nodes can have zero or more mix-in types, specified using the jcr:mixinTypes property as a multi-valued property. To add mix-ins to an existing node, use the add operation:

/pre-existing-node:
  jcr:mixinTypes:
    operation: add
    value: [additional:mixin]

If you specify jcr:mixinTypes without an operation, the new set replaces the existing set. If the new set removes any existing mix-ins, the merge fails unless you use override:

/pre-existing-node:
  jcr:mixinTypes:
    operation: override
    value: [first:mixin, third:mixin]

This removes any mix-ins not listed in the new value.

Creating New Nodes

To create a new node, specify the primary type on the base node or any child node:

/path/to/base-node:
  jcr:primaryType: some:type

This creates base-node as a child of to. The parent node must already exist.

/path/to/base-node:
  /child:
    jcr:primaryType: some:type

This creates a new child node under base-node. base-node must already exist.

Multi-level paths below the root node are not supported:

/path/to/base-node:
  /parent/child:
    jcr:primaryType: some:type

This is invalid. Instead, define the full path as the base node:

/path/to/base-node/parent/child:
  jcr:primaryType: some:type

Or define each segment separately:

/path/to/base-node:
  /parent:
    /child:
      jcr:primaryType: some:type

Merging Nodes

When a definition specifies a node that already exists in the Configuration Model, Bloomreach Content merges the new definition into the existing node. New properties are added, and existing property values are replaced. For details on property merging, see the previous section.

If a pre-existing node has child nodes, and the new definition specifies child nodes with the same name, these child nodes are also merged.

/path/to/existing-base-node:
  new-property: value
  existing-property: new-value
  /existing-child:
    new-property: value
    existing-property: new-value
  /new-child:
    jcr:primaryType: some:type
  • new-child is added as a new child node. It must specify a primary type.

Node Operations

Additional operations can be applied to nodes during merging. These operations use meta properties with the .meta: namespace to avoid conflicts with actual node properties.

Inserting Nodes

To control the order of child nodes, use .meta:order-before to insert a new node before a specific sibling. If not specified, new nodes are added as the last sibling.

/path/to/base-node:
  /new-child:
    jcr:primaryType: some:type
    .meta:order-before: sibling-name

This inserts new-child before sibling-name.

You can also use .meta:order-before on a new base node:

/path/to/new-base-node:
  jcr:primaryType: some:type
  .meta:order-before: sibling-name

To insert a node as the first sibling, use an empty value:

/path/to/new-base-node:
  jcr:primaryType: some:type
  .meta:order-before: ''

If the parent node's primary type claims that child order is significant but you want to ignore order changes, set .meta:ignore-reordered-children to true:

/path/to/base-node:
  jcr:primaryType: mistakenly:ordered
  .meta:ignore-reordered-children: true

Use this only if the node type was defined incorrectly.

Deleting Nodes

To delete a node and its subtree from the Configuration Model and repository, set .meta:delete to true:

/path/to/to-be-deleted-node:
  .meta:delete: true

If a later definition tries to access or recreate this node or its subtree, an exception is thrown.

Same Name Siblings

By default, nodes with the same path are merged into a single node. For example:

/path/to/base-node:
  jcr:primaryType: some:type
  /sibling:
    jcr:primaryType: some:type
    property: value1

and

/path/to/base-node:
  jcr:primaryType: some:type
  /sibling:
    jcr:primaryType: some:type
    property: value2

result in a single sibling node with the property value from the last definition.

To create same name siblings, use explicit indices:

/path/to/base-node:
  jcr:primaryType: some:type
  /sibling[2]:
    jcr:primaryType: some:type
    property: value2

The first sibling can be written as:

/path/to/base-node:
  jcr:primaryType: some:type
  /sibling[1]:
    jcr:primaryType: some:type
    property: value1

You do not need to specify [1] unless there are multiple siblings. Indices are omitted in serialization unless required. Do not use indices in base paths.

Managing same name sibling indices across modules or projects is complex and error-prone. Avoid same name siblings when possible.

YAML Export and Import in the Console

You can use the Console to import and export nodes as YAML source files. Use zipped YAML sources when working with binary properties (such as images).

Share Feedback
Page: /build/configuration-management/yaml-format
Section: Build
Category *