Skip to content
manni

manni:kg:1.0.0-proposal.3

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

Section titled “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)

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.

Location. manni:kg:1.0.0-proposal.3 marks its one top-level key, kg, with "x-manni-location": "page". page means the value belongs in the document’s own metadata and is meant to reach delivered output. external means it belongs in the collection’s external-metadata manifest. A key is page when a third-party or user-owned agent fetching the page would act on it. kg is the categorization the delivered page’s consumers asked for. The fields in the table above carry no mark of their own. They travel with the block. See field location for how the marks are used.

Example

Section titled “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
meta-provenance:
  - generated-by: claude-opus-4-6
    fields: [/kg/broader, /kg/related-concepts]
    confidence: { /kg/broader: 0.88, /kg/related-concepts: 0.9 }

Design decisions

Section titled “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

Section titled “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?

Proposal 0046 removes kg.provenance, in draft 1.0.0-proposal.2. The trail for kg fields moves to the page-level meta-provenance in ai-context, where each field is a JSON Pointer under /kg/, such as /kg/broader. manni meta fill already writes meta-provenance by pointer for the fields it fills, while the draft stays under review. The block’s closed field list kept sections, revision-of and derived-from out of the trail, and a pointer cannot. That guard would move to the graph layer, where the harvest reports a machine attribution on those fields.