Skip to content
docmeta

docmeta:lifecycle:1.0.0-proposal.1

The question it answers: where is this page in its life? It carries one rule: a deprecated page must say what comes next, either a successor, a removal date, or both.

Fields

Section titled “Fields”
Field Type Notes
lifecycle enum draft · published · deprecated · archived
replaced-by string, non-empty The page, id, or URL that supersedes this one
supersedes string or list Pages this one replaced. The record survives after the old page is deleted
remove-by W3CDTF date The date the page should be removed by

The conditional: lifecycle: deprecated requires replaced-by or remove-by (or both). A page can reach end of life without a successor, and requiring a replacement in every case would force a false value into it. But “deprecated” with no horizon and no successor is a permanent state, and that is what the rule forbids.

Examples

Section titled “Examples”
---
title: Configure the legacy exporter
description: The exporter settings for operator releases before 1.4.
lifecycle: deprecated
replaced-by: configure-the-collector
remove-by: 2027-01-01
---

The valid no-successor form:

lifecycle: deprecated
remove-by: 2027-01-01     # ends without a replacement; legal

Design decisions

Section titled “Design decisions”
  • The enum is closed, and the cost is recorded. The family’s default is to never invent an enum. This ladder catches typos such as depreciated and makes the deprecation rule enforceable. The cost: an org with its own stages (experimental, retired) must override the key. This and visibility are the only invented enums in all nine vocabularies, and both are keys that downstream tooling branches on.
  • remove-by is a date. A removal date gives a build something to act on. A boolean flag only says the page will go away someday, and pages flagged that way tend to stay forever. Ansible’s deprecation practice, which records a removal date, is the model.
  • The inverse edges live on two files, and the schema says so. replaced-by (old page to new) and supersedes (new page to old) describe one fact from two files. JSON Schema validates one file at a time, so the pair is not cross-checked here. A knowledge graph is where the two edges reconcile: the kg vocabulary’s revision-of emits the same prov:wasRevisionOf predicate. As with the review dates, this vocabulary records the fact and states the limit of what it can check.
  • lifecycle is editorial state; visibility is access. Who may see the page is visibility. The two axes are independent: lifecycle: draft with visibility: internal (unfinished, but visible inside the org) is a legal, common page.

What reviewers should poke at

Section titled “What reviewers should poke at”

The enum’s cost. Is draft · published · deprecated · archived universal enough to justify rejecting every org’s experimental and retired until they override the key?