Designing a Canonical Article Schema That Agents Can Trust

An autonomous publishing workflow can produce fluent prose and still fail operationally. The title appears on the page but not in the feed. A draft leaks into the sitemap. Two agents use different date formats. A source URL survives in research notes but disappears before review. The article is readable, yet nobody can connect the published page to the workflow run that created it.

These are not primarily writing failures. They are contract failures.

A canonical article schema gives every participant—research agent, writer, editor, validator, build process, and reviewer—the same definition of a publishable article. It specifies which facts must exist, how they are represented, and which combinations are allowed. The schema becomes trustworthy when it is narrow enough to enforce, expressive enough to preserve evidence, and shared by every output path.

The goal is not to collect the most metadata. It is to make the smallest set of promises that the publishing system can consistently keep.

One article should have one authoritative record

When a title lives in front matter, a publication date is embedded in a template, and an RSS description is maintained somewhere else, the system has several competing records. They will eventually drift. An agent may update one field and have no reason to know that two copies remain.

Instead, store editorial content and structured metadata together in one canonical article record. The site page, blog index, sitemap, RSS feed, social metadata, and structured data should derive from that record. Those outputs may transform values, but they should not invent independent versions of them.

This establishes a useful flow:

1. an agent proposes a complete article record;
2. a validator accepts or rejects it;
3. renderers consume only accepted records; and
4. generated outputs can be traced back to the same source file and commit.

The result is less reconciliation work. More importantly, a reviewer can inspect one change and understand what every downstream channel will receive.

Separate editorial identity from presentation

A durable schema begins with identity and lifecycle fields, not page layout. For a small repository-native publication, a practical core might include:

• title, slug, description, and excerpt for identity and discovery;
• publishedAt, updatedAt, and status for lifecycle state;
• author and tags for attribution and organization;
• featuredImage and featuredImageAlt for media;
• canonicalUrl for URL intent;
• sources for research provenance; and
• qaScore and workflowRun for operational provenance.

These fields describe the article rather than a particular HTML template. A redesign can change cards, typography, or page structure without rewriting the content contract.

Avoid turning front matter into an unbounded settings object. Presentation instructions such as headlineFontSize or cardBorderColor tie an article to today's renderer. If a genuine editorial distinction is needed—such as a feature story versus a field note—model that distinction explicitly and let the design system decide how to present it.

Required means required at the publishing boundary

JSON Schema distinguishes between properties that are described and properties that are actually required. A property listed under properties remains optional unless it also appears in required [1]. That detail mirrors an important editorial rule: documentation alone does not create a guarantee.

For published content, require every field needed to render, discover, audit, and verify the article. Then define the field precisely:

• dates use one YYYY-MM-DD format;
• slugs match a lowercase, hyphenated pattern;
• status is an enum rather than arbitrary prose;
• source entries require a title, absolute URL, and access date;
• QA scores are numeric and stay inside a declared range; and
• workflow identifiers cannot be blank.

Nullability deserves an explicit decision. In JSON, a property whose value is null is different from a missing property [1]. That distinction can be useful. For example, requiring featuredImage while allowing null says, “Every article must make a deliberate image decision.” Omitting the field cannot silently mean the same thing.

The validation boundary should also account for lifecycle. A draft may legitimately lack a publication date or final canonical URL. A record with status: published may not. Conditional rules prevent a flexible draft model from becoming a permissive production model.

Model provenance as data, not a footnote

Research provenance should survive the transition from notes to published article. A structured sources array lets the validator check that every entry has the information a reviewer needs. It also makes sources visible in a normal code review rather than trapping them in an agent transcript or temporary workspace.

Operational provenance answers a different set of questions: Which workflow run produced this version? What QA result did the editor assign? Which commit entered production? Not all of that information must live in front matter. Commit and pull-request identifiers already belong naturally to the repository and run record. But the canonical article should carry enough of a stable link—such as workflowRun—to join those records without guessing.

Do not mistake provenance for proof that every claim is correct. A URL proves only that a source was recorded. The research step must still verify that the source is authoritative, relevant, reachable, and accurately represented. The editor must still check whether the article's claims are supported.

Make downstream promises explicit

Metadata is valuable because other parts of the system depend on it. Those dependencies should be designed, not assumed.

The slug determines the route and therefore must be unique. The publication state determines whether the article may appear on the public blog index, in RSS, and in the sitemap. The description may populate search and social metadata. The dates may drive sorting and structured data. Schema.org's Article vocabulary includes properties such as headline, author, datePublished, and dateModified, providing a common model for article information exposed to other systems [2].

Canonical URL handling is another cross-output promise. Google describes rel="canonical" as a strong signal for the representative URL and recommends absolute, self-referential canonical links on canonical pages [3]. A repository may allow canonicalUrl: null to mean “derive the absolute production URL from the configured site origin and slug.” That is safe only if the meaning is documented, implemented once, and tested. It must not mean “render no canonical information.”

Image metadata needs similar care. The W3C Web Accessibility Initiative says informative images need text alternatives that convey their essential information, while purely decorative images should use an empty alternative [4]. A schema cannot decide whether prose is good alternative text, but it can prevent an image path from being accepted without an explicit accessibility decision.

Validate the contract at more than one level

Field validation catches malformed records, but trustworthy publishing also requires collection and output checks.

At the record level, validate types, required fields, formats, allowed values, and combinations. At the collection level, reject duplicate slugs and, where the editorial policy requires it, suspiciously overlapping titles. Confirm that published dates are plausible and source records are complete.

At the output level, build the site and inspect the behavior created from the record:

• the article route exists and contains the expected title and metadata;
• the blog index includes published content and excludes drafts;
• the sitemap contains the intended canonical route once;
• RSS contains the correct title, link, date, and description; and
• page metadata and structured data agree with the source record.

This layered approach matters because a valid article object can still be consumed incorrectly. A typo in a feed generator will not be found by front-matter validation. Conversely, checking rendered HTML without validating the source makes it harder to identify where a bad value entered the system.

Failures should stop publication with a specific message. “Invalid article” is not actionable. “publishedAt must match YYYY-MM-DD” tells an agent what to correct without inviting speculative changes.

Evolve the schema without breaking trust

A canonical schema will change. The safe way to evolve it is to treat changes as contract migrations.

First, identify every producer and consumer. Producers include agents, authoring tools, and import scripts. Consumers include validators, templates, feeds, sitemaps, tests, and external integrations. Then choose whether the change is backward-compatible.

Adding an optional field is usually easier than renaming a required field. A rename may need a staged migration: accept both names temporarily, update all existing records and consumers, reject conflicts, then remove the old name. If different versions must coexist, add an explicit schema version and define how each version is normalized before rendering.

Defaults should be used sparingly. A default can reduce repetitive input, but it can also conceal a missing editorial decision. Automatically defaulting status to published, for example, creates an unsafe failure mode. Defaults are most appropriate when the value is genuinely mechanical and visible after normalization.

Finally, test the validator with bad fixtures as well as good ones. A trustworthy contract is defined partly by what it refuses: an invalid date, a duplicate slug, a published article without sources, an image without an alternative-text decision, or an unknown lifecycle state.

Trust comes from shared enforcement

Agents do not trust a schema because it is described in a prompt. They trust it because the same contract is available at generation time, checked before merge, used by every renderer, and reflected in production verification.

That suggests a practical operating rule for Coffee House Digital: keep the canonical article schema close to the content, make validation deterministic, and record workflow evidence where it survives the run. Let agents draft within that boundary, let editors judge meaning and quality, and let protected repository controls decide whether the validated change may ship.

The schema then becomes more than metadata. It becomes the handoff language between editorial intent and software behavior—small enough to understand, strict enough to stop unsafe publication, and stable enough for every agent in the system to rely on.

Sources

1. JSON Schema, “Object.” Accessed September 17, 2026. https://json-schema.org/understanding-json-schema/reference/object
2. Schema.org, “Article.” Accessed September 17, 2026. https://schema.org/Article
3. Google Search Central, “How to specify a canonical URL with rel=canonical and other methods.” Accessed September 17, 2026. https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls
4. W3C Web Accessibility Initiative, “Images Tutorial.” Accessed September 17, 2026. https://www.w3.org/WAI/tutorials/images/