Model Governance for Content Types

Governance standards keep your content models consistent, scalable, and safe to evolve across your stack. This guide shows you how to introduce content model changes without breaking the websites, applications, or integrations that depend on your structured content.

This guide is for:

• Solution architects
• Developers who manage content models
• Teams responsible for maintaining structured content at scale

• Understand how to create and manage content types.
• Identify the systems that consume your content, such as websites, apps, and APIs.

Use consistent, predictable naming for content type and field UIDs.

Recommended guidelines:

• Use lowercase snake_case (for example, blog_post or hero_title).
• Keep names semantic and stable so they reflect purpose, not UI labels.
• Avoid generic names such as data, info, or content.
• Use consistent suffixes where helpful: _title, _description, _image, _url, _slug, and _cta_label.

Why this matters: Consistent naming keeps integrations stable and easier to maintain over time.

Example conventions:

When you update a content model, choose the least disruptive approach.

• Add new optional fields without modifying existing ones.
• Existing integrations are unaffected.

• Create a new content type (for example, blog_post_v2).
• Use this approach when the structure changes significantly.

• Migrate entries to the new structure.
• Update the consuming systems.
• Deprecate the old fields or content types.

Best practice: Treat content model changes like API changes, and always evaluate downstream impact.

Avoid removing or repurposing fields immediately. Instead, follow a staged lifecycle.

Recommended lifecycle:

1. Mark the field as deprecated (for example, [Deprecated] hero_subtitle).
2. Stop using it in new content.
3. Migrate existing entries to replacement fields.
4. Update all consuming systems.
5. Remove the field only after validation.

• Identify all consuming systems, such as web, mobile, APIs, and automations.
• Define required versus optional field behavior.
• Review locale and environment impact.
• Plan for backward compatibility.
• Define a rollback strategy.

• Validate entries using the Delivery API.
• Confirm field mappings in the consuming systems.
• Monitor for errors, such as missing or renamed fields.

Content types are branch-specific, so manage schema changes carefully.

• Apply changes in a non-production branch first.
• Test entries, APIs, and rendering.
• Promote to production only after validation.

Why this matters: Unvalidated changes in production can break content delivery and integrations.

For each content type, maintain documentation that includes:

• Purpose and owner
• Required fields
• Reference dependencies
• Deprecated fields and their replacements
• Last reviewed date

Consistent documentation supports long-term maintainability and reduces risk during updates.