How to Structure Your Content

Overview

This page outlines best practices for structuring content in Bloomreach Content to support performance, maintainability, and usability.

Content Modeling Principles

The design of your content model directly affects system performance and maintainability. Once your system is live, restructuring content can be difficult and disruptive. Use the following guidelines to create an effective content structure.

Minimize Query Complexity

Efficient content models require simple queries for content delivery. If you notice that your queries are becoming complex, reconsider your content model.

A common mistake is storing metadata in folder nodes rather than directly on document nodes. This approach makes queries more difficult and limits your ability to use features like faceted navigation.

Hint: Store metadata as properties on the document node, not in folders or child nodes.

Properties used for sorting or faceted navigation must be direct properties of the document node. Do not store these properties in child nodes (such as compound blocks).

Avoid content structures where folders contain metadata about their documents. For example:

Warning:

• Bloomreach (folder)
  • Bloomreach Content (product)

This structure requires complex and inefficient queries.

Instead, use a structure like:

Hint:

• Products (folder)
  • Bloomreach Content (company = Bloomreach)

Here, the company property is stored on the document, making the document independent of its folder structure.

If you require folder-based access control (for example, restricting access to documents about Bloomreach products), you can nest folders but should still keep relevant metadata as document properties:

• Products (folder)
  • Bloomreach (folder)
    • Bloomreach Content (company = Bloomreach)

Maintaining the company property on the document enables faceted navigation and results in cleaner frontend code, even if you do not use faceted navigation immediately.

Document Model Node Type Hierarchy

The document model in Bloomreach Content uses a strict node type hierarchy. Child nodes of a hippo:handle node are document variants and must be of type hippo:document. Many platform features depend on this hierarchy.

Do not modify this hierarchy. Descendant nodes of a document variant must never be of type hippo:document.

Managing Folder Size

The number of items (documents and subfolders) in a single folder impacts both performance and user experience. Large folders increase retrieval times and make navigation difficult.

Hint: Keep the number of items (documents and subfolders) in each folder below 100.

Starting with brXM 16.9.0, you can enforce this limit using the Folder Item Limit Configuration.

To keep folder sizes manageable, use a hierarchical folder structure. For example, organize news articles by year and month:

News (folder)

• 2026 (folder)
  • 12 (folder)
    • Boxing Day Sale (news article)
    • New Year's Eve Special (news article)
  • 11 (folder)
    • Thanksgiving (news article)

This structure ensures that no folder contains more than 12 month folders per year. If you expect more than 100 articles per month, add subfolders for days.

Hint: Use folder hierarchies to keep the number of items per folder low.

Info: For more information, see Configure the CMS Folder Listing Page Size.