Canonical Pattern For CMS/BFF

2026-03-04

Purpose

This document codifies the required CMS/BFF pattern for content objects used by headless site scaffolding.

The goal is to keep object persistence concerns inside CMS/BFF, while allowing site/page intent and front-end delivery concerns to remain separate.

Required Pattern

1. For every content object, the BFF should:
2. expose a canonical immutable identifier
3. expose a 6-digit hash tag derived from the underlying object ID

4. support a client-supplied slug field as part of the content

5. Return the full article content fields needed by pages:

6. tags
7. categories
8. excerpt

9. featureImageUrl

10. Author object consists of two fields:

11. a string for name

12. an authorKey field referencing the underlying author identity

13. Article collections must be first-class objects.

14. Return article collections with these fields:

15. collectionKey
16. name
17. description
18. scope

19. imageUrl

20. Article collections must expose membership as an ordered array of stable article references, for example [articleKey1, articleKey2, ...].

Boundary Rule

The following are not article-collection concerns and should not be pushed into the collection object:

• hero eyebrow
• hero title
• hero description
• grid heading
• grid description

These belong to site/page presentation intent, not to headless CMS object design.

Rationale

• canonical identifiers support stable persistence and reference
• hash tags support compact object shorthand
• slugs support readable delivery concerns
• collections should represent reusable content grouping
• page presentation remains a separate concern owned by site/page intent