docmeta:structure:1.0.0-proposal.1

The question it answers: what does this page connect to? This vocabulary describes relationships between pages, which no generator owns. It never describes position in a navigation tree, which every generator does. There is no ordering, no parent, and no nav title here.

Fields

Field	Type	Notes
`applies-to`	string or list	Flat product, variant, or version labels: `operator-1.4`, `kubernetes`
`not-applicable-to`	string or list	The exclusion `applies-to` alone cannot state: `operator-1.4` yes, `operator-1.4-fips` no
`concepts`	string or list	Controlled glossary terms. Core’s `keywords` is free words; this is the curated list
`prerequisites`	string or list	Pages, ids, or capabilities the reader needs first
`next-steps`	string or list	Sensible follow-ons, unordered. Several are allowed, unlike the generator’s single `next`. A more advanced page on the same topic goes here
`related-pages`	string or list	Related pages, ids, or URLs. A site renders this list as “See also”

Every field accepts one string or a non-empty list without duplicates.

Example

---
title: Install the operator on Kubernetes
description: Deploy the operator with Helm and verify the rollout.
applies-to: [operator-1.4, kubernetes]
not-applicable-to: [operator-1.4-fips]
concepts: [Operator, Helm chart]
prerequisites: [create-api-token]
next-steps: [verify-rollout, configure-alerts]
related-pages: [operator-architecture]
---

Design decisions

This vocabulary stops at relationships. A field that duplicates something the generator already owns under a second name is worse than a collision, because a collision at least fails loudly. next-steps is several unordered suggestions. The generator’s next and prev position keys are a different fact and stay with the generator.
“A more advanced page” is a next-steps entry. Review asked whether the family needs a way to point at a deeper treatment of the same topic. It already has one. There is no advanced or deeper-dive key and no ordering among next-steps, because “more advanced” is a claim about the reader, not about the page. It can be derived: two pages share concepts while pointing at personas of different levels. The same reasoning removed reader expertise from this family, since level belongs to the persona definitions a page points at. The cost: a docs set with no persona definitions yet cannot derive it. That is the same trade the audience vocabulary makes for teams starting out.
“See also” is a label for related-pages. The heading most docs sites render is editorial; the key underneath it stays semantic. There is no see-also alias. One fact reachable by two keys is the kind of second surface this family exists to prevent, and an alias is permanent. Your style guide might split “See also”, for the same product, from “Learn more”, off-site. related-pages already accepts URLs, so that split is a rendering decision over one field.
applies-to is flat. Named dimensions (product:, deployment:, generation:) were designed and then removed. An org that needs axes can prefix its labels (deploy:kubernetes) or overlay its own schema. This is a headline open question for the review.
The negative exists at both levels. not-applicable-to was added in review round 5 for parallelism. The kg block’s applies-to had a page-level counterpart, and its not-applicable-to did not. So the only way to say “not the FIPS build” was to open a kg block for one field. Checking that the two lists do not overlap is a graph-layer (SHACL) check at both levels. JSON Schema cannot compare two sibling lists. So a page naming the same label on both sides passes here, and the contradiction surfaces at graph build. A test asserts that this passes, the same way one asserts that an overdue review passes.
Three fields are fallbacks for the kg block. applies-to, not-applicable-to, and concepts share names and shapes with their counterparts inside the kg vocabulary’s block. The rule is that the deeper declaration wins. When the kg block sets a fact, its value is used. When the block is silent, the page-level field feeds the graph. Both sides accept identical values by construction, using the same non-empty, duplicate-free list shape. So a promoted page-level value can never produce a document the kg block would reject.
related-pages says what it points at. The suffix exists because kg.related-concepts relates concepts. Each name now names its target.

What reviewers should poke at

The flat applies-to. Is the prefix-label convention a good enough escape hatch for orgs that filter by dimension (product, deployment, generation), or should named axes return?