Content architecture principles
Purpose: Design content trees that survive years of authoring: hierarchy, reuse, references and naming.
Who this page is for
| Audience | Why it matters to you |
|---|---|
| All engineers | Structure decisions are the hardest to change later |
| Tech leads | Review guide |
Principles
| Principle | Practice |
|---|---|
| Hierarchy = navigation = permissions | The /content tree should mirror the site IA; ACLs and MSM both key off it |
| Facts once, presentation many | Premium value lives in one CF; pages, cards, comparison tables all reference it |
| Reference, don't copy | Store paths to shared content (CF/XF/assets); copies rot |
| Author-sized chunks | A node an author edits should map to a task they think of ("edit benefits") |
| Name for stability | Node names become URLs — lowercase, hyphenated, never renamed casually |
| Type properties honestly | Booleans, numbers, dates as real types — queries, models and dialogs all benefit |
Reference integrity
AEM does not enforce referential integrity like a relational DB. When content is referenced by path:
- Moving/renaming updates references only where AEM's tooling knows about them (page moves offer reference updates) — CF/XF references in custom properties need your components to be resilient.
- Deleting referenced content is possible; the Sites console warns, but code must handle dangling references (null-check adapted fragments).
Anti-patterns
| Anti-pattern | Why it hurts |
|---|---|
| JSON blobs in string properties | Unqueryable, unauthorable, untyped |
| Deep trees for data that is really a list | Query and iterate cost, authoring pain |
| Layout facts in content ("leftColumn": true) | Couples content to today's design |
| Duplicating shared legal text per page | Compliance updates become a 50-page hunt |
| Meaningful node names encoding data | Data belongs in properties; names are identifiers |