This issue covers the technical architecture of Content Guidelines, an experimental feature that allows site owners to define content creation preferences.

Parent Issue: #75171
Design Discussion - #75260
Make Post: https://make.wordpress.org/ai/2026/02/04/content-guidelines-a-gutenberg-experiment

Proposed Architecture Overview

Storage

Custom post type with JSON blob storage

The current implementation uses a single Custom Post Type (CPT) (wp_content_guideline) with the complete guidelines structure stored as JSON in the post_content field.

This approach provides:

• Atomic updates (all-or-nothing saves prevent partial/inconsistent state)
• Single database row per site (simple, predictable scaling)
• Easy versioning using WordPress native CPT revisions (captures entire state)
• Flexible schema without requiring database migrations
• Simple import/export (single JSON file)
• AI-ready consumption (straightforward JSON parsing)
• No complex multi-post coordination

Trade-offs:

• Cannot query individual categories independently
• Not leveraging WordPress as a CMS for text content
• Always fetches all data (even when filtering by category)

Guideline Categories

Five categories:

The MVP starts with these five categories, but the JSON schema is flexible and supports additional categories through its additionalProperties design - no code changes required to add new categories.

JSON Schema

Guidelines follow a flexible JSON schema:
Example:

{
  "version": "1.0.0",
  "status": "draft" | "published",
  "createdBy": 1,
  "createdAt": "2026-01-15T09:00:00Z",
  "modifiedBy": 1,
  "modifiedAt": "2026-01-20T14:30:00Z",
  "publishedBy": 1,
  "publishedAt": "2026-01-20T14:30:00Z",
  "changeLog": "Optional user description of changes",
  "guideline_categories": {
    "copy": {
      "label": "Copy Guidelines",
      "guidelines": "Conversational but authoritative...",
      "purpose": "Informs AI-generated text"
    },
    "images": { ... },
    "site": { ... },
    "blocks": {
      "core/paragraph": {
        "guidelines": "Keep paragraphs to 2-3 sentences..."
      },
      "core/heading": {
        "guidelines": "Use clear, descriptive headings..."
      }
    },
    "other": { ... }
  }
}

Schema features:

• Semantic versioning for tracking iterations
• Full audit trail (created/modified/published metadata)
• Optional changelog for human-readable descriptions
• Flexible additionalProperties allows nested sub-categories
• Free-form guidelines text at core

REST API

Namespace: __experimental (MVP)

Endpoints:

Security & Validation:

• JSON encoding with XSS prevention: JSON_HEX_TAG | JSON_HEX_AMP
• Content sanitization via wp_kses_post() for all string values
• Basic Block name validation: regex /^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/
• Maximum length constraints: 5000 chars for guidelines, 200 chars for labels
• Database escaping with wp_slash()

Permissions:

• Create/Update/Delete: Admin-only (manage_options capability)
• Viewing: Editor+ (with future per-post overrides planned)

Architectural Discussion Points

The following sections outline key architectural decisions made in the current MVP implementation. As an experimental feature behind a flag, we have the flexibility to start with simpler approaches and iterate based on real-world usage and community feedback. The goal of this discussion is to validate whether the MVP choices provide a solid foundation, or if we should invest in alternative architectures before wider adoption.

1. Storage Architecture

Current Approach: JSON Blob

The MVP stores all guidelines as a JSON blob in a custom post type's post_content field.

Important context: Guidelines are meta-content (configuration), not publishable content. Similar to theme.json or site settings, they configure how content should be created rather than being content themselves. This distinction informs the storage architecture choice—treating guidelines as structured configuration data rather than CMS-managed content.

✅ Benefits:

• Atomic updates (no partial/inconsistent state)
• Single database row (simple scaling)
• Easy versioning (revisions capture full state)
• Flexible schema (no migrations needed)
• Simple import/export (one JSON file)

❌ Trade-offs:

• Cannot query individual categories independently
• Always fetches all data (even when filtering by category)
• Treats guidelines as configuration rather than CMS-managed content

Alternative: Separate Posts Per Category

Each guideline category could be stored as a separate WordPress post.

✅ Benefits:

• Each category is a post (native WP content)
• Can query/cache individual categories
• Richer content with block editor possible
• WordPress-native approach for text

❌ Trade-offs:

• Complex update coordination across posts
• Revision management across multiple posts
• Potential consistency issues (partial updates)
• How to handle block-specific guidelines? (hundreds of posts?)

Discussion: Is the JSON blob approach acceptable for an experimental MVP to validate the feature concept? The simplicity allows us to ship faster and gather real-world feedback. If needed, we can refactor to separate posts architecture in a future iteration based on actual usage patterns and performance data.

2. Category Extensibility

Current Approach: Five starter Categories with Flexible Schema

The MVP starts with five categories: Copy, Images, Site, Blocks, Other. The JSON schema's flexible design allows additional categories to be added without code changes.

✅ Benefits:

• Simple, predictable structure for baseline use cases
• Clear UI organization with well-defined categories
• Schema supports additional categories via additionalProperties
• No database migrations needed to add new categories

❌ Trade-offs:

• UI currently only exposes the five categories
• No formal plugin API for registering categories in the admin interface
• No hierarchical organization of categories
• Additional categories would need custom UI implementation

Alternative: WordPress Taxonomies

Categories could be registered via WordPress taxonomy system.

✅ Benefits:

• WordPress-native categorization
• Extensible by plugins (register_taxonomy())
• Hierarchical structure for complex sites
• Per-site customization (e.g., "Reviews Guidelines", "News Guidelines")
• Multi-site flexibility

❌ Trade-offs:

• UI complexity (users manage taxonomies)
• Potential fragmentation (inconsistent usage)
• How to enforce baseline categories?

Future Enhancement Options:

• Add plugin API to register categories in the admin UI
• Support WordPress taxonomies for hierarchical organization
• PHP filters for customizing category list: apply_filters('gutenberg_content_guidelines_categories', $categories)

Discussion: The current approach provides five well-defined categories with a flexible schema that already supports additional categories. The main question is whether the MVP should include a formal plugin API for registering categories in the UI, or if we should wait to see if there's demand for this extensibility before adding the complexity. Is starting with 5 categories and a flexible schema reasonable, with the option to add a plugin API in a future iteration if needed?

MVP Philosophy & Experimental Flag

MVP Scope:

• Provide way for users to add/modify guidelines
• Support draft → published workflow
• Behind Gutenberg experiment flag (gutenberg-content-guidelines)
• No impact when disabled
• Start simple, iterate based on feedback - gather real-world usage data before committing to complex architectural decisions

Benefits of Experimental Flag:

• Can make breaking changes safely
• Gather real-world feedback
• Validate architectural decisions with usage data
• Refactor if community consensus emerges

We're taking an iterative MVP approach: start simple, gather real-world feedback, then enhance based on actual usage patterns. We're seeking input on these architectural decisions to ensure this feature aligns with WordPress Core principles and scales for all use cases. Your feedback is greatly appreciated!

cc @andrewserong @talldan @Mamaduka @mtias @youknowriad