{
  "@context": "https://ptpge.org/v1/context.jsonld",
  "id": "https://api.ptpge.org/v1/deprecation-policy",
  "type": "Policy",
  "policy_version": "0.9 — Beta",
  "effective_date": "2026-05-27",
  "applies_to_text": "`/v1/` while `MATURITY = \"beta\"` (see §5 and §10 for production-tier upgrades)",
  "title": "PTPGE API Deprecation Policy",
  "sections": [
    {
      "heading": "1. Core commitments",
      "id": "core-commitments"
    },
    {
      "heading": "2. Term lifecycle states",
      "id": "term-lifecycle-states"
    },
    {
      "heading": "3. Deprecation notice and retirement windows",
      "id": "deprecation-notice-and-retirement-windows"
    },
    {
      "heading": "4. Breaking vs. non-breaking changes",
      "id": "breaking-vs-non-breaking-changes"
    },
    {
      "heading": "5. Maturity levels",
      "id": "maturity-levels"
    },
    {
      "heading": "6. Major version transitions (v1 → v2)",
      "id": "major-version-transitions-v1-v2"
    },
    {
      "heading": "7. Communication channels",
      "id": "communication-channels"
    },
    {
      "heading": "8. Reporting concerns",
      "id": "reporting-concerns"
    },
    {
      "heading": "9. Policy changes",
      "id": "policy-changes"
    },
    {
      "heading": "10. Graduating MATURITY from beta to production",
      "id": "graduating-maturity-from-beta-to-production"
    },
    {
      "heading": "11. Maintainers and governance",
      "id": "maintainers-and-governance"
    }
  ],
  "source": "https://github.com/ptpge/ptpge/blob/main/docs/DEPRECATION-POLICY.md",
  "license": "https://creativecommons.org/licenses/by/4.0/",
  "body_md": "# PTPGE API Deprecation Policy\n\n**Version:** 0.9 — Beta\n**Effective:** 2026-05-27\n**Applies to:** `/v1/` while `MATURITY = \"beta\"` (see §5 and §10 for production-tier upgrades)\n**Endpoint:** `https://api.ptpge.org/v1/deprecation-policy`\n\nThis policy describes how PTPGE handles changes to the API contract during the Open Beta period — what consumers can rely on, what may change, and how breaking changes are signalled and timed. Commitments are calibrated to the current operational maturity. When the API graduates from beta to production (see §10), several commitments are strengthened. The graduation itself is announced in advance and recorded as a Strategic Decision.\n\nThis policy is part of the API contract; changes to this policy follow the rules in §9.\n\n## 1. Core commitments\n\n**Stable URI structure for `/v1/`.** Once a term URI has been published under `https://ptpge.org/v1/`, the URL scheme and path conventions will not be restructured within v1. New levels may be added (e.g., a deeper sub-category) without breaking existing terms.\n\n**Identifiers persist across data versions.** The `version` field on individual terms uses ISO-8601 dates (`YYYY-MM-DD`) and increments with content releases. A term's `id` (URI) does not change between content releases unless the term is formally deprecated and replaced (see §3).\n\n**URI resolvability — Beta tier (current).** URIs under `/v1/` will resolve for the duration of PTPGE operations. In the event that operations cease, the Maintainers (see §11) commit to:\n\n1. Minimum 90 days advance public notice via the changelog and direct email to registered integrators.\n2. Publication of the full `/v1/` corpus as a static read-only archive at `https://archive.ptpge.org/v1/`.\n3. Minimum 12 months of read-only availability of the archive from the date of operations cessation.\n\n**URI resolvability — Production tier (after §10 graduation).** URI resolvability strengthens to a minimum of 5 years from initial publication or 2 years from sunset, whichever is longer. The Maintainers also commit to depositing the corpus with a permanent identifier service (e.g., DOI via DataCite, or a w3id.org-fronted URI) before any operational cessation.\n\n## 2. Term lifecycle states\n\nEvery term carries a `status` field with one of three values:\n\n- **`proposed`** — The term is published but not yet finalised. Its definition, label, hierarchy or relations may still change without a deprecation notice. Consumers integrating against proposed terms accept that the meaning may be refined.\n\n- **`approved`** — The term is finalised. Changes from this state require a formal deprecation cycle (see §3).\n\n- **`deprecated`** — The term is scheduled for retirement. It remains resolvable. Required companion fields: `deprecatedOn` (date), `deprecationReason` (multilingual explanation), and either `replacedBy` (URI of successor) or an explicit note that no successor exists.\n\nState transitions: `proposed → approved → deprecated`. Reversion from `approved` back to `proposed` is not permitted; instead, the term is deprecated and a new term is created.\n\n## 3. Deprecation notice and retirement windows\n\nWhen an `approved` term is deprecated, timing depends on the API's current maturity tier:\n\n| Phase | Beta tier (current) | Production tier (after §10) |\n|---|---|---|\n| Notice | Minimum **3 months**; flip to `status: deprecated`; populate `replacedBy` + `deprecationReason`; changelog + Atom updated | Minimum **6 months** |\n| Sunset | Minimum **6 months**; term remains fully functional; reminders via changelog | Minimum **12 months** |\n| Total minimum window | **9 months (best effort)** | **18 months (contractual)** |\n\nCritical exceptions (security-relevant, legally-required, or data-integrity-threatening removals) may use a shorter window with explicit announcement at either tier.\n\nAfter retirement, the URI continues to resolve and returns the deprecated record with `replacedBy` pointers — never a 404 — for the duration of URI resolvability commitments in §1.\n\n## 4. Breaking vs. non-breaking changes\n\nThe following are **non-breaking** and may happen at any release without notice, at either maturity tier:\n\n- Adding new terms (new URIs that did not exist before)\n- Adding new fields to existing terms (e.g., new language labels, new `altLabel` entries, new `properties` keys)\n- Adding new relations (`narrower`, `related`, `closeMatch`) that did not exist before\n- Adding new languages to the multilingual index for any term\n- Promoting a term from `proposed` to `approved`\n- Promoting a language entry from `langStatus: draft` to `langStatus: production`\n- Bug fixes that do not change semantic meaning (typos, formatting, broken links in scopeNotes)\n\nThe following are **breaking** and follow §3 deprecation rules at the current tier:\n\n- Removing a term that was `approved`\n- Changing the URI of an `approved` term\n- Changing the meaning of an `approved` term in a way that would invalidate existing references\n- Removing or renaming a JSON-LD field that consumers may have indexed (e.g., `definition`, `notation`, `narrower`)\n- Changing the JSON-LD `@context` in a way that alters how existing fields are interpreted\n\nThe following are **changes to the API contract itself** and require their own dedicated announcement:\n\n- Moving from `/v1/` to `/v2/` (new major version — see §6)\n- Changing the deprecation policy (this document — see §9)\n- Changing the maturity status of the API (`beta → production` — see §10)\n\n## 5. Maturity levels\n\nThe API publishes a global maturity flag at `/v1/version.json` under `maturity`:\n\n- **`alpha`** — Internal stealth use only. Structure and content may change without notice.\n- **`beta`** *(current)* — Open Beta. Structural changes are still possible but require a changelog entry. Term-level deprecations follow §3 at the beta tier. Consumers are expected to track the changelog Atom feed.\n- **`production`** — All commitments in this policy apply at the production tier (see §10 for the full list of upgrades). Structural changes require advance notice via blog post + Atom + direct email to known integrators.\n\nMaturity transitions are announced via the changelog at least 30 days in advance and are recorded as Strategic Decisions in the public log.\n\n## 6. Major version transitions (v1 → v2)\n\nIf structural choices at `/v1/` prove to be wrong in a way that cannot be patched without violating §4 breaking-change rules, a new major version is published in parallel.\n\n| Step | Beta tier (current) | Production tier (after §10) |\n|---|---|---|\n| Public RFC before v2 freeze | Minimum **30 days** | Minimum **60 days** |\n| `/v2/` published alongside `/v1/` | Required | Required |\n| Crosswalk at `/v1-to-v2/crosswalk.json` | Required | Required |\n| `/v1/` sunset duration after v2 launch | Minimum **12 months** | Minimum **24 months** |\n| Migration SDK | Best effort | Required |\n| `/v1/` URI resolvability post-sunset | Per §1 beta tier | Per §1 production tier |\n\n`/v1/` URIs continue to resolve within the resolvability commitments in §1. They return the deprecated record with `replacedBy` pointers.\n\n## 7. Communication channels\n\nChanges are announced through:\n\n- **Changelog** (`https://api.ptpge.org/changelog.html`) — human-readable\n- **Changelog Atom feed** (`https://api.ptpge.org/changelog.atom`) — machine-subscribable\n- **Version endpoint** (`https://api.ptpge.org/v1/version.json`) — current data version, maturity, deprecation counters\n- **This policy** (`https://api.ptpge.org/v1/deprecation-policy`) — current rules\n- **Direct email** to registered integrators — best-effort at beta tier, contractual at production tier (registration via `register.ptpge.org`)\n\nAt the beta tier, integrators are expected to subscribe to the Atom feed or poll `/v1/version.json` periodically. Direct email at beta is best-effort and should not be relied on as the sole notification channel.\n\n## 8. Reporting concerns\n\nConsumers who believe a deprecation is mis-categorised (e.g., a term marked non-breaking but actually breaking for their use case) should report via:\n\n- GitHub Issues on the public `ptpge/ptpge` repository\n- Email to `api@ptpge.org`\n\n**Response expectations:**\n\n- **Beta tier (current):** Best-effort response. The Maintainers aim to acknowledge reports within 5 business days, but make no contractual commitment at this tier. Substantive responses follow on a best-effort basis as bandwidth allows.\n- **Production tier (after §10):** The Maintainers commit to acknowledging reports within 5 business days and providing a substantive response within 15 business days.\n\n## 9. Policy changes\n\nThis policy itself is versioned. Changes follow these rules:\n\n- **Editorial clarifications** (wording, typos, examples) may be made without notice; the patch version bumps (0.9 → 0.9.1).\n- **Substantive changes** that affect consumer obligations or rights require:\n  - **Beta tier:** Minimum 30 days advance notice via the changelog, with a minor version bump (0.9 → 0.10).\n  - **Production tier:** Minimum 90 days advance notice, with a minor version bump.\n- **Major changes** require a major version bump and follow the §6 process for the policy document itself.\n\nSignificantly, this policy may **strengthen** commitments at any time without advance notice (subject to changelog announcement). It may not **weaken** commitments without the full notice period and a recorded Strategic Decision explaining why.\n\nThe previous version of this policy remains available at `/v1/deprecation-policy/history/`.\n\n## 10. Graduating MATURITY from beta to production\n\nThe transition from `MATURITY = \"beta\"` to `MATURITY = \"production\"` is itself a Strategic Decision and triggers the following commitment upgrades:\n\n| Commitment | Beta value (current) | Production value |\n|---|---|---|\n| URI resolvability (operational) | Duration of operations | 5 years minimum, or 2 years post-sunset (whichever is longer) |\n| URI resolvability (post-cessation) | 12 mo static archive at archive.ptpge.org | Deposit with permanent identifier service before cessation |\n| Approved-term deprecation notice | 3 mo minimum | 6 mo minimum |\n| Approved-term sunset | 6 mo minimum | 12 mo minimum |\n| v1→v2 sunset | 12 mo minimum | 24 mo minimum |\n| Public RFC for v2 | 30 days | 60 days |\n| Migration SDK | Best effort | Required |\n| Response acknowledgement | Best effort | 5 business days (contractual) |\n| Response substantive | Best effort | 15 business days (contractual) |\n| Policy change notice (substantive) | 30 days | 90 days |\n| Direct email to integrators | Best effort | Contractual |\n\n**Graduation criteria (all must be met before `MATURITY = \"production\"`):**\n\n1. At least 12 months of stable Open Beta operation.\n2. At least 3 external Founding Partners integrated and operational against the API.\n3. The Pre-Open-Beta Checklist (`docs/PRE-OPEN-BETA-CHECKLIST.md`) is fully resolved with no remaining blockers.\n4. A documented incident-response procedure has been tested at least once.\n5. A Strategic Decision recording the graduation is signed by all current Maintainers.\n6. A public announcement at least 30 days in advance of the transition.\n\nThese graduation criteria are themselves part of this policy. They may be **tightened** (more requirements added) by Strategic Decision at any time, but they may not be **loosened** without the full §9 notice period.\n\n## 11. Maintainers and governance\n\n**PTPGE Maintainers** are the named individuals responsible for the operational integrity of this API and the commitments in this policy. The current Maintainers are:\n\n- **Patrik Knutsson** (Tangerin AS) — lead Maintainer, taxonomy and API operations\n\nAdditional Maintainers may be added by Strategic Decision. The phrase \"the Maintainers\" in this document refers to the current Maintainer roster acting by majority consensus (or unanimously when only one Maintainer is listed).\n\nA future transition to a formal Editorial Board, Advisory Board, or independent Foundation structure is itself a Strategic Decision and is one of the candidate triggers for tightening graduation criteria in §10.\n\nThe Maintainers commit to making the operational structure of PTPGE transparent: the current Maintainer roster, governance model, and key Strategic Decisions are published in the public repository.\n\n---\n\n**Maintained by:** PTPGE Maintainers (see §11)\n**Source:** `docs/DEPRECATION-POLICY.md` in the PTPGE repository\n**License:** [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/)\n"
}