docmeta:kg:1.0.0-proposal.1

The question it answers: what does the knowledge graph know about this page? A common vocabulary that any graph builder or retrieval tool can implement. Files without a kg key pass. The block itself is closed, so a misspelled field fails loudly.

The block

Field	Notes
`label`	The one canonical name of the concept this page is about (`skos:prefLabel`)
`alt-labels`	Every other name; what search matches (`skos:altLabel`)
`broader` · `narrower`	Parent and child concepts. Each requires `label`, so there are no synonyms of nothing
`related-concepts`	Associated concepts (`skos:related`). The page-level `related-pages` relates pages; this relates concepts
`concepts`	What the page covers (`dcterms:subject`). The same fact as the page-level field, one level deeper
`type`	iiRDS topic type: `task` · `concept` · `reference` · `learning` · `troubleshooting` · `form`. The same fact as the page-level `type`, one level deeper
`applies-to` · `not-applicable-to`	Product/variant labels, positive and negative scope (`iirds:relates-to-product-variant`)
`about-product-lifecycle`	Which product phases the content covers (never the page’s own lifecycle): `administration` · `customization` · `update` · `deployment` · `integration` · `deinstallation`
`about-product-aspect` · `not-about-product-aspect`	`architecture` · `interface` · `system-requirement` (iiRDS Software domain)
`sections`	Per-heading typing, keyed by heading slug: the same fields, one heading down
`revision-of` · `derived-from`	Document lineage (`prov:wasRevisionOf`, `prov:wasDerivedFrom`)
`provenance`	The machine-proposal trail: which model proposed which kg fields, at what confidence

Every label field takes one string or a non-empty list without duplicates. The three iiRDS enums stay closed because iiRDS publishes the lists. That is the kind of authority the family’s no-invented-enums rule asks for.

Example

kg:
  label: Operator installation
  broader: [Operator]
  related-concepts: [Helm chart]
  type: task
  applies-to: [operator-1.4]
  about-product-lifecycle: [deployment]
  sections:
    verify-the-rollout:
      type: reference
  provenance:
    - generated-by: claude-opus-4-6
      fields: [broader, related-concepts]
      confidence: { broader: 0.88, related-concepts: 0.9 }

Design decisions

The closed block is the one exception to the family’s flat-keys rule. It is what lets a closed, typo-catching block coexist with an open page.
The deeper declaration wins; the page level is the fallback. Some facts appear in both the block and a page-level field: type, concepts and applies-to. There the block’s declaration wins, fact by fact, and the page-level field feeds the graph when the block is silent. When kg.type is absent, an implementer may derive it from the page’s type (how-to → task, tutorial → learning, explanation → concept). An explicit block always wins.
Plain-language kebab names; the RDF mapping lives in the descriptions. iiRDS itself spells its properties in kebab-case (has-topic-type), so mirroring a vocabulary’s internal spellings in the key names gains nothing. label is skos:prefLabel, and each field description carries its mapping.
The about- prefix makes the subject explicit. about-product-lifecycle: [deinstallation] describes what the content covers. A page about uninstalling is not a deprecated page. The page’s own life is lifecycle.
Overlap between applies-to and not-applicable-to is checked at the graph layer. JSON Schema sees one file at a time, so the check does not happen here.

What reviewers should poke at

Two questions. Does the closed block plus open page root land well for graph implementers? And do the plain-language renames (label, about-product-aspect) read better than the SKOS and iiRDS spellings they replaced?