Sanity Portable Text Architecture Guide

Guide to defining, validating, and operating Portable Text in Sanity, covering requirements, minimal schema, trust boundaries, checks, failure modes and when to redesign.

Requirements

Editors need a WYSIWYG rich‑text field that can be rendered to web, mobile and print outputs. The content must stay portable, be versioned inside the Content Lake, and be queryable with GROQ. The schema should stay simple, and validation must happen at write time to prevent malformed data from entering the lake.

Smallest Suitable Design

Define a field of kind array whose of contains a single block type. This mirrors Portable Text’s canonical JSON shape and needs no custom types for basic rich text.

// schemas/post.js\nexport default {\n  name: 'post',\n  title: 'Post',\n  type: 'document',\n  fields: [\n    {\n      name: 'body',\n      title: 'Body',\n      type: 'array',\n      of: [{ type: 'block' }],\n    },\n  ],\n};\n

Each block JSON object includes optional style, list, marks (annotations) and children (inline spans or nested blocks). This is the minimal design that satisfies the requirements.

Trust / Data Boundaries

Sanity Studio validates incoming mutations against the declared schema before they are sent to the Content Lake. The Lake re‑validates the JSON blob on ingest and rejects any document that deviates from the declared block structure with a 400 response. API consumers therefore receive data that has already been vetted by the server‑side enforcement; trust is placed in the Content Lake, not the client.

Operational Checks

CI schema validation – Run sanity schema check in your CI pipeline (requires the Sanity CLI installed and a token with schema:read scope). This catches mismatches between the local schema files and the remote dataset.
Preview mode – Enable Studio’s preview pane to render Portable Text using your project’s serializers; this surfaces missing serializer issues early.
Webhook lint – Configure a publish webhook that receives the document, runs a lint step (e.g., checks for unknown marks or missing _type on blocks), and alerts on failure.
Monitor API errors – Track 400 validation errors from the Content Lake during write operations; a sudden increase indicates a schema or client issue.

Example: CI Schema Check Command

Run in the repository root:

# Requires: Sanity CLI v3+, SANITY_STUDIO_TOKEN with schema:read\nsanity schema check --dataset production\n

Expected check: the command exits with code 0 if the local schema matches the remote schema; non‑zero output lists mismatches. Risk: if the token lacks sufficient permissions the command will fail with an authentication error, not a schema mismatch.

Failure Modes and Design‑Change Triggers

Malformed Portable Text – Sending a block without _type or with an unknown mark results in a 400 validation error from the Content Lake, preventing the mutation from being applied.
Missing serializer – A custom mark defined in the schema but lacking a corresponding frontend serializer will be silently dropped in the rendered output, leading to content loss.
Document size limit** – The Content Lake imposes a 16 KB limit per document. Large inline images or excessive nesting can cause the limit to be exceeded, forcing a split into multiple blocks or moving binary data to asset references.
Real‑time collaborative editing beyond block‑level – If multiple users need to edit the same inline span concurrently, the block‑level granularity may become insufficient.
Complex block types – Requirements for embeddings, tables or custom widgets with their own schema fields exceed the generic block model.

When any of the above conditions arise, the design should evolve:

Introduce explicit block schemas (e.g., {type: 'image'}, {type: 'table'}) inside the of array.
Consider a separate document type for large assets or embeddings, referencing them by ID from Portable Text.
Adopt a custom block type with its own fields when inline collaboration on complex objects is required.

Practical Verification Steps

Create a new Sanity project, add the schema field shown above, start the studio, enter rich text with styles, lists and a custom mark, then publish.
Query the document via GROQ: *[_type == 'post']{body}. Verify the returned JSON matches the Portable Text spec (each object has _type: 'block', optional style, list, marks array, and children).
Attempt to insert an object missing _type or containing an unknown mark via the API (e.g., using curl with a mutation). Observe a 400 response with details about the invalid block, confirming server‑side enforcement.
Render the fetched Portable Text with @sanity/block-content-to-react using a minimal serializer set that includes handlers for all marks and styles present. Compare the output to the studio preview; mismatches indicate missing serializers.
In CI, add a test step that posts a known‑bad Portable Text payload and asserts the request fails (non‑2xx status). This demonstrates the validation gate works in automated pipelines.

Limitations

Portable Text is optimized for block‑level rich text. Storing large binary data directly inside blocks (e.g., base64 images) will quickly hit the 16 KB document limit and bypass Sanity’s asset management. Use the built‑in image block type, which stores only an asset reference, to stay within limits and gain proper asset handling. Additionally, any custom mark or block type must be mirrored in frontend serializers; otherwise the data persists in the lake but is not rendered, leading to silent loss.

Architecture Note: Using Sanity Portable Text as a Rich‑Text Field