Data Model Deep Dive

This guide provides a deep understanding of the Agility CMS data model, including the three-layer architecture, relationships, and design patterns.

Three-Layer Architecture

The Agility data model uses a three-layer architecture:

Layer 1: Models (Schema Layer)

Purpose: Define structure and schema

Models are blueprints that define:

• What fields exist
• Field types (text, image, linked content, etc.)
• Validation rules
• Default values

Model Types:

• Page Models: Define page structure (content zones, layout)
• Component Models: Define reusable UI component structure
• Content Models: Define reusable content item structure

Layer 2: Instances (Data Layer)

Purpose: Actual data instances

Instances are the actual data:

• Pages: Page instances created from page models
• Components: Component instances with actual data
• Content Items: Standalone content pieces created from content models

Layer 3: Relationships (Reference Layer)

Purpose: Connect entities together

Relationships connect entities:

• Sitemap: Organizes pages and defines URLs
• Page → Components: Pages contain references to components
• Component → Content: Components display content items
• Content → Content: Content items can link to other content items

Model Design Patterns

Content Model Patterns

Pattern 1: Standalone Content

Use Case: Single, independent piece of content

Example: Author profile

• Name, title, headshot
• Used in multiple places
• Managed independently

Pattern 2: Collection Content

Use Case: Related items that form a collection

Example: Blog Posts

• Multiple posts with similar structure
• Need to be queried/filtered
• Support pagination

Pattern 3: Linked Content

Use Case: Content with relationships

Example: Blog Post

• Links to Author (one-to-one)
• Links to Category (one-to-one)
• Links to Tags (many-to-many)

Component Model Patterns

Pattern 1: Simple Component

Use Case: Direct field mapping

Example: Hero component

• Heading, description, image, CTA
• All fields stored directly in component

Pattern 2: Content-Linked Component

Use Case: Component that displays content items

Example: Post Listing component

• Links to Posts content list
• Displays filtered/sorted posts

Pattern 3: Nested Component

Use Case: Component with nested content

Example: Bento Section

• Component has nested Bento Cards
• Cards fetched separately using reference name

Relationship Patterns

One-to-One

Example: Post → Author

• One post has one author
• Author can have multiple posts (reverse: many-to-one)

One-to-Many

Example: Post → Tags

• One post has many tags
• Tags can be on multiple posts (reverse: many-to-many)

Many-to-Many

Example: Post ↔ Tags

• Posts can have multiple tags
• Tags can be on multiple posts

Parent-Child

Example: BentoSection → BentoCards

• Parent component references child content list
• Children fetched separately using reference name

Content Model Types

Content Items

Characteristics:

• Single, standalone instances
• Best for: Authors, Categories, Global Settings
• Managed as individual items

Use When:

• Content is unique (one instance)
• Content doesn't need to be queried as a list
• Content is referenced by other content

Content Lists

Characteristics:

• Collections of related items
• Best for: Blog Posts, Testimonials, Pricing Tiers
• Support querying, filtering, pagination

Use When:

• Multiple items with same structure
• Need to query/filter items
• Items form a logical collection

Design Considerations

Reusability

Question: Will this content be used in multiple places?

• Yes → Content Model: Create reusable content model
• No → Component Field: Store directly in component

Relationships

Question: Does this content relate to other content?

• Yes → Linked Content Field: Use linked content fields
• No → Standalone: Keep content independent

Querying Needs

Question: Do you need to query/filter this content?

• Yes → Content List: Use content list for querying
• No → Content Item: Use content item for single instance

Personalization

Question: Does this content need personalization?

• Yes → Audience/Region Fields: Add personalization fields
• No → Standard Content: Use standard content model

Best Practices

1. Plan Models First: Design content models before building components
2. Identify Reusability: Determine what content should be reusable
3. Design Relationships: Plan how content relates to other content
4. Consider Queries: Design for efficient querying
5. Plan for Growth: Design models that scale

---

Next: Content Strategy - Content modeling strategies