JSON Content Brief Schema: 8 Fields for Publishable Drafts

Most teams assume a great brief is a well-written Google Doc. It reads nicely, gives context, and points the writer in the right direction. That works until you try to automate handoffs, validate claims, or publish at a daily cadence. Prose looks friendly to people, but it is opaque to machines. Ambiguity becomes rework. Rework becomes delay.

If you want publishing to run on its own, you need a spec that people can author and systems can enforce without interpretation. Treat the brief as a data contract. Encode the narrative and controls in a validator-ready schema so editors have clarity and engineering has certainty. Oleno runs this way because that is the only path to consistent, publishable output at scale.

Key Takeaways:

• Replace prose-only briefs with a validator-ready JSON contract that machines can enforce
• Encode eight fields that always ship: title, tl;dr, sections[], claims[], internal_links[], metadata, qa_gate, publish
• Fail fast on missing H1, ungrounded claims, and slug errors with precise rejection reasons
• Separate content fields from control fields to keep authors focused and automation safe
• Bring QA into the schema with a min_score and checks so failures surface early, not at publish time

Why Prose-Only Briefs Block Automation

The spec must be machine-readable

Most teams think “detailed” briefs solve handoffs. The problem is not detail, it is structure. Freeform text cannot be validated or tested. Your brief should function as a contract between people and systems. Define a minimal JSON schema that covers narrative structure, claims, internal links, and CMS metadata. Use explicit types, enums, and length limits so ingestion can reject bad input early with clear reasons.

Require a single H1, a predictable H2 and H3 hierarchy, and short, declarative section goals. Machines need consistency to parse and route. People appreciate it because the work is easier to scan and judge. Make each field independently testable with obvious failure modes. A missing H1 should block ingest. A vague “background” paragraph should not be allowed where a section goal is required.

Encode acceptance criteria next to each field definition. Add examples and counter-examples right where editors write. When teams can see what will pass before they draft, you avoid frustrating rework and ambiguous reviews. Include common failure reasons as enumerated values so your pipeline can return precise feedback immediately.

Human intent, machine enforcement

Keep narrative human-first, but make enforcement rules explicit. Capture intent in short fields: tl;dr for the promise, section goals for scope, acceptance rules for pass or fail. Machines can validate the format and required elements. Humans decide nuance inside those boundaries. Put both in the schema so editors know what breathes and what is locked.

Separate “content” from “control.” Fields like title, tl;dr, and sections[] carry what the reader will see. Fields like qa_gate, metadata, and internal_links[] carry the automation controls. That split lets engineering wire ingestion safely while content teams focus on value. Fail fast. If H1 or tl;dr is missing, stop. If a claim is ungrounded, mark it needs_source and block publishing. The point is not punishment, it is predictability.

The Real Spec Isn’t A Doc — It’s A JSON Contract

Schema over prose wins handoffs

Use a validator-ready JSON Schema, such as Draft 2020-12, to encode field names, types, length limits, and enums. This becomes the single source of truth for both editors and ingestion. With a published schema, you can run checks locally and in CI. Everyone ships against the same rules, and failures become quick, actionable fixes rather than long threads.

Make fields required by default, then opt into optional with intention. For publishable content, the eight required fields typically include: title, tl;dr, sections[], claims[], internal_links[], metadata, qa_gate, and publish. Optional fields, such as faq[] or images[], can sit behind feature flags so you add them when you need them, not by default.

Document “why” next to “what.” Brief writers follow standards they understand. Explain how each field maps to CMS targets and schema.org. When people see how a slug becomes a URL or how metadata lands in the head, compliance rises and handoffs shrink.

Acceptance criteria beat preferences

Preferences drift. Acceptance criteria do not. Define rules that can be programmatically checked for each field. For example, the title must be a non-empty string with one H1 semantic role. The tl;dr must be 30 to 60 words and mention the problem and the outcome. sections[] must include 4 to 6 H2s, each with 1 to 3 H3s that have clear goals.

Add schema-level dependencies. If a claim is marked grounded, require at least one kb_anchor_id that resolves to your Knowledge Base. If publish.target is “wordpress,” require endpoint and auth fields. If qa_gate.min_score is set, enforce it before any publish step. Provide rejection reasons as enums, such as MISSING_H1, TLDR_TOO_LONG, UNGROUNDED_CLAIM, INVALID_ANCHOR, SLUG_FORMAT_ERROR, QA_MIN_SCORE_NOT_MET. This turns reviews into specific fixes, not taste debates.

Curious what this looks like in practice? Try generating 3 free test articles now. Request a demo now.

The Hidden Cost Of Manual Brief-To-CMS Handoffs

Rework compounds quietly

Let’s say you ship 20 posts each month. If 30 percent bounce for missing H1 or bad slugs, and each fix costs 20 minutes across editor and engineer, you are burning about 2 hours every week on preventable issues. That is enough time to write another post, coach a writer, or improve your Knowledge Base. Instead, you wait on feedback loops that never had to exist.

Without a claims[] ledger, reviewers chase citations across comments and chat. Every “where did this come from?” steals attention and goodwill. One simple field, claim.text plus kb_anchor_id plus grounded status, removes ambiguity and speeds approvals, especially in regulated or technical teams. Internal links have a similar problem. Unstructured anchors turn into title case or long phrases. A schema-enforced anchor format, such as 2 to 5 lowercase words, plus an allowlist of URLs keeps links clean and consistent without manual reviews.

QA debt shows up at publish time

When QA criteria live in a wiki, teams find out at the end that a draft fails structure or voice. Bring those checks into qa_gate with a min_score and a list of checks. Fail early. Return rejection_reasons with human-friendly messages tied to the field that failed, such as “H2 count below minimum” or “kb_anchor_id invalid format.”

Encode retries for transient CMS errors at the publish layer, not in the editor’s calendar. If a webhook times out or a WordPress endpoint returns 502, your pipeline should retry with exponential backoff. Humans should not become schedulers. Track status transitions in the payload, for example validated to qa_passed to published. You do not need a dashboard just to see this. Your pipeline logs should record events so the system can retry intelligently and keep state consistent.

Ready to eliminate preventable rework and last-minute publish fails? Try using an autonomous content engine for always-on publishing. try using an autonomous content engine for always-on publishing.

What It Feels Like When Your Team Hits A Wall

Editors feel whiplash, engineers feel churn

Editors get whiplash from subjective feedback like “make it more structured” or “tighten this section” with no shared definition of done. Engineers get churn from ambiguous payloads that do not validate, then bounce back for fixes they cannot automate. A JSON brief schema reduces taste-based arguments and replaces them with rules everyone can see and test.

You might be worried about compliance or brand safety, but chasing sources across docs is a headache. A claims[] array with kb_anchor_id flips that script. One place to review grounding. One place to approve or reject. The back-and-forth slows, and trust rises because the evidence is attached to the claim, not floating in a comment.

Perspective shift: you own the inputs, we run the pipeline

You control Brand Studio, your Knowledge Base, and the posting cadence. The pipeline runs the sequence. When inputs are clean and schema-validated, output is predictable. If something breaks, it is immediately obvious whether the fix is content, control, or connector.

Do not try to solve everything with prompts. Prompts write words. Pipelines ship articles. Your schema is the meeting place, guardrails that let automation do its job without stepping on the narrative. The goal is not zero edits forever. It is to turn one-off feedback into a rule that improves every future post.

The JSON Content Brief Schema: Eight Fields That Ship

1) Schema overview: required vs optional

Start with the eight required fields that always ship. Everything else is optional and should be added only when needed.

• title: One H1 promise for the article
• tl;dr: A 30 to 60 word summary of problem and outcome
• sections[]: H2 and H3 structure with goals and short descriptions
• claims[]: A ledger of statements with grounding status
• internal_links[]: Anchors and URLs that are allowed and formatted
• metadata: Slug, title tag, meta description, schema types
• qa_gate: Min score, checks, current score, and results
• publish: Target, credentials, retries, and status

Sections[] should include each H2, an optional narrative_tag for internal mapping, 1 to 3 H3s, and clear goals. Keep headings 3 to 8 words. Ensure each H2 has at least one H3. Add section_id to each H2 for cross-references and straightforward CI assertions.

claims[] should include claim_id, text, kb_anchor_id[], grounded status with allowed values grounded or needs_source, and notes. If grounded is true, require at least one kb_anchor_id that resolves to a known document. If needs_source, allow the claim to exist during drafting, but block publish until it is grounded or removed.

2) Field definitions and acceptance criteria

Define acceptance rules that are explicit, brief, and testable.

• title: Non-empty string, single H1 semantic role, no emojis, avoid marketing fluff, suggested length 45 to 75 characters. Accept if it makes one clear promise.
• tl;dr: 30 to 60 words, names the problem and the outcome. Reject if too short, too long, or missing outcome.
• sections[]: 4 to 6 H2s, each with 1 to 3 H3s. Each H3 includes a short goal sentence. Reject if counts are outside bounds or goals are missing.
• claims[]: claim.text ≤ 280 characters. If grounded is true, kb_anchor_id[] length ≥ 1 and each anchor matches your KB index format, for example doc_id#chunk. Reject grounded claims without anchors. Allow needs_source during drafting but block publish.
• internal_links[]: anchor is 2 to 5 lowercase words. url must be in the allowlist. type is one of hub, spoke, or sitemap. priority is an integer.
• metadata: slug is kebab-case with lowercase letters and digits. title_tag is 45 to 60 characters. meta_description is 140 to 160 characters. schema is one of Article, HowTo, FAQPage, SoftwareApplication, or Product.
• qa_gate: min_score default 85. checks[] includes structure, voice, kb_accuracy, seo_structure, llm_clarity, narrative_order. status is pass or fail. Include rejection_reasons[] when fail.
• publish: target ∈ {wordpress, webflow, storyblok, webhook}. If target is wordpress, require endpoint, auth method, and retries. If webhook, require url and signature settings. retries includes max_attempts and backoff.

These rules make success objective. Editors can write with confidence. Engineering can wire enforcement once and move on.

3) Mapping to CMS metadata and schema.org types

Map schema fields to CMS metadata in a way that stays declarative. That keeps connectors simple and reduces custom code.

• metadata.title_tag → CMS SEO title
• metadata.meta_description → CMS meta description
• metadata.slug → URL path
• schema[] → JSON-LD injection

For WordPress, map body to post_content, title to post_title, and slug to post_name. Attach JSON-LD to the head via your theme or plugin. For Webflow and Storyblok, pass metadata and schema fields in the payload according to their APIs. For webhooks, include schema[] as a JSON-LD object for the receiver to place.

Choose schema.org types based on the content format. Article fits most posts. HowTo is for procedural guides. FAQPage when a dedicated FAQ is present. SoftwareApplication or Product when the page describes a product. Do not force schema when it does not match the content.

How Oleno Implements The Schema And Automates Publishing

Automated KB-claim validation

Remember that endless “source?” thread under a critical paragraph? Oleno removes it by attaching the Knowledge Base to drafting and validation. During drafting, Oleno populates kb_anchor_id[] for each claim marked grounded. It validates anchor existence with a lookup against your KB index. If a claim is needs_source, Oleno labels it and prevents publishing until it is grounded or removed.

Oleno also records grounded_status at draft time. Claims are grounded when anchors resolve, missing when anchors are absent, or invalid when anchor format fails. The QA checks reduce accuracy scores when claims are missing or invalid and include precise rejection reasons, such as UNGROUNDED_CLAIM, INVALID_KB_ANCHOR, or CLAIM_TOO_LONG. This turns what used to be a manual review loop into a fast, deterministic fix.

Integrating QA-Gate checks and retries

Oleno represents qa_gate as an object in the payload with min_score, checks[], score, status, and rejection_reasons[]. The QA-Gate must pass before any publish attempt. On fail, Oleno runs safe improvements automatically, such as slug formatting or anchor normalization, then retests. Each change increments version history and retries counters so you maintain a clean record without creating confusion.

Publishing reliability comes from idempotent, retry-aware connectors. Oleno classifies errors as transient or permanent. It retries WordPress on 429 and 5xx responses with exponential backoff. It retries webhooks on timeouts and network errors. It never duplicates publishes because it uses idempotency keys. This is how teams eliminate late-night manual retries and still keep a clean audit trail.

Sample payloads, CURL posts, and CI tests

Here is a compact example of a brief payload with the eight required fields:

{
  "title": "JSON Content Brief Schema: 8 Fields That Ship",
  "tl;dr": "Prose-only briefs collapse in automation. A JSON contract with eight fields makes handoffs testable and publishing predictable.",
  "sections": [
    {
      "section_id": "why-briefs-block",
      "h2": "Why Prose-Only Briefs Block Automation",
      "h3s": [
        { "h3": "The spec must be machine-readable", "goal": "Explain contract-first brief design" }
      ],
      "goals": "Show why structure beats prose"
    }
  ],
  "claims": [
    { "claim_id": "c1", "text": "Minimum QA score is 85", "grounded": true, "kb_anchor_id": ["qa-guide#min-score"] },
    { "claim_id": "c2", "text": "Schema-level anchors reduce review time by 50%", "grounded": "needs_source", "kb_anchor_id": [] }
  ],
  "internal_links": [
    { "anchor": "autonomous content operations", "url": "https://example.com/hub", "type": "hub", "priority": 90 }
  ],
  "metadata": {
    "slug": "json-content-brief-schema",
    "title_tag": "JSON Brief Schema: 8 Fields That Ship",
    "meta_description": "Replace prose-only briefs with a JSON contract so automation can validate, QA, and publish on its own.",
    "schema": ["Article"]
  },
  "qa_gate": {
    "min_score": 85,
    "checks": ["structure", "voice", "kb_accuracy", "seo_structure", "llm_clarity", "narrative_order"]
  },
  "publish": { "target": "wordpress", "endpoint": "https://cms.example.com/wp-json/wp/v2/posts", "auth": "bearer", "retries": { "max_attempts": 4, "backoff": "exponential" } }
}

A simple WordPress POST might look like:

curl -X POST "https://cms.example.com/wp-json/wp/v2/posts" \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{"title":"JSON Content Brief Schema: 8 Fields That Ship","content":"<html>...</html>","status":"draft","slug":"json-content-brief-schema"}'

Add CI tests that run on each pull request:

• Schema validation: valid payload passes, missing H1 fails with MISSING_H1
• KB lookup: grounded claim with missing kb_anchor_id fails with UNGROUNDED_CLAIM
• QA threshold: score 84 fails, 85 passes
• Slug formatter: “JSON Brief!” becomes “json-brief”
• Anchor rules: “Title Case Anchor” rejected as INVALID_ANCHOR

Want to see this pipeline run end to end without coordination overhead? Try Oleno for free. Request a demo.

Conclusion

Prose-only briefs feel flexible until you want reliability, speed, and scale. A JSON contract turns your brief into something machines can enforce and humans can trust. Eight required fields make success objective. Acceptance criteria and schema-level dependencies make failures specific and fixable. QA moves from a wiki to the payload. Publishing becomes a repeatable operation, not an on-call chore.

Oleno implements this model out of the box. Brand Studio defines voice. The Knowledge Base grounds claims. The QA-Gate enforces structure and accuracy. Connectors publish with retries and idempotency. When you adopt a contract-first brief, you stop debating style and start shipping predictable, high-quality content on a daily cadence.