DOC-6939 Add schema_version and since to the AI outputs

[andy-stark-redis]

Adds schema_version and since to the AI-facing JSON and Markdown outputs — items C1 and C3 of DOC-6939. Both were agreed with the applied AI team rather than assumed.

C3 — since was their only hard blocker

Their observation 01: the Markdown metadata block carries since for command pages, the JSON does not, so a consumer indexing or filtering on version information could not move to the feed without dropping that filter.

It now appears in the JSON, straight from the command pages' frontmatter — on 574 records, matching exactly the 574 source files that declare it. Section pages don't gain a spurious empty field.

C1 — schema_version, with the semantics that make it useful

A single integer, in every per-page JSON record and in the Markdown metadata block, currently 1. It lives in one place — aiSchemaVersion in config.toml — so there's one value to bump rather than four templates to keep in step.

The semantics are their own definition, and they're the point of the field:

• Increments only when the record's shape changes — a field added, removed or renamed, or a new value entering the role vocabulary.
• Never changes when content changes. Their words: a version that moves with content is a second content hash, and they'd learn to ignore it. Use content_hash for content, schema_version for "your parser may need attention".

That distinction is written into both the config comment and the published docs, because the field is worthless without it.

Worth stating what does not bump it, since the temptation will be there: changing what a field contains is not a shape change. The page id going from a filename to a path (#3761) is a value change, so version 1 covers both that and this.

Verification

Built and transformed the combined state, since #3761 landed first and the two had never been built together:

Records	5,733
schema_version	1 on all 5,733, and in the Markdown metadata block
Records carrying since	574 (against 574 source files declaring it)
Distinct page ids	5,733, 0 colliding
content_hash verifies	5,687 / 5,687

commands/set comes out as id='commands/set', schema_version=1, since='1.0.0'.

One thing hardened beyond the ask

The transform now declares both fields on its input and output interfaces. They were already surviving, because the object spread carries unknown keys at runtime — but nothing said so, and a future refactor replacing the spread with explicit field copying would have silently dropped the one field consumers gate their parsing on. Declaring them makes the survival deliberate rather than incidental.

What a reviewer should focus on

• schema_version is a contract-shaped field. Once published, consumers will gate behaviour on it, so the discipline about when it increments matters more than the field itself. The Constraint trailer and the config comment both state it.
• Adding the field is itself a shape change, which is the chicken-and-egg case: version 1 is defined as "the shape as of this release" rather than pretending an earlier version existed.

Not in this PR

C4 (redirect map), C5 (splitting interface-only metadata from semantic metadata) and C6 (a machine-readable marker on the code-examples legend) are still open, as is the decision on D5 — versioned pages serving an untransformed schema at the documented URL shape.

🤖 Generated with Claude Code

---

Note

Low Risk
Additive feed fields and documentation with no auth or runtime behavior changes; consumers must treat schema_version as a parser contract.

Overview
Adds schema_version and since to the AI-facing per-page JSON feed and Markdown metadata, driven by a single aiSchemaVersion param in config.toml (currently 1).

schema_version is documented as a shape-only contract: bump it when fields or role vocabulary change, not when page content changes (use content_hash for that). It is emitted from all four Hugo templates (single/section × JSON/Markdown).

since is added to JSON output when front matter defines it (command pages), matching what Markdown metadata already exposed, and omitted elsewhere so non-command records do not get an empty field.

Published AI Agent Resources docs gain a schema-version section and table rows for both fields. The NDJSON transform types in transform_json_sections.ts now declare schema_version and since on input/output so they survive explicit refactors, not only object spread.

^{Reviewed by Cursor Bugbot for commit c1cace7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Staging links:
https://redis.io/docs/staging/DOC-6939-schema-version/ai-agent-resources/

[github-actions]

🧠 Redis Memory

Found 5 related items from repository history:

• Commit — DOC-6939 Add schema_version and since to the AI outputs

  DOC-6939 Add schema_version and since to the AI outputs

• PR — DOC-6939 Correct stale document count in the NDJSON feed docs

  Fixes the stale document count on the AI agent resources page — item A1 of DOC-6939.

• PR — DOC-6939 Document feed coverage and the section role vocabulary

  Documents feed coverage and the section role vocabulary on the AI agent resources page — items B2 and B3 of DOC-6939. Documentation only:

• PR — DOC-6939 Make the page-level id unique

  Makes the page-level id unique — item A4 of DOC-6939.

• Commit — DOC-6939 Keep code-block headings out of the TOC, and close a fence that hid three sections

  DOC-6939 Keep code-block headings out of the TOC, and close a fence that hid three sections

Memory updated at c1cace7

[github-actions]

DOC-6939

[dwdougherty]

Approved.

[andy-stark-redis]

Thanks @dwdougherty !