This 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.

This policy is part of the API contract; changes to this policy follow the rules in §9.

1. Core commitments

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.

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).

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:

1. Minimum 90 days advance public notice via the changelog and direct email to registered integrators.
2. Publication of the full /v1/ corpus as a static read-only archive at https://archive.ptpge.org/v1/.
3. Minimum 12 months of read-only availability of the archive from the date of operations cessation.

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.

2. Term lifecycle states

Every term carries a status field with one of three values:

• 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.

• approved — The term is finalised. Changes from this state require a formal deprecation cycle (see §3).

• 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.

State transitions: proposed → approved → deprecated. Reversion from approved back to proposed is not permitted; instead, the term is deprecated and a new term is created.

3. Deprecation notice and retirement windows

When an approved term is deprecated, timing depends on the API's current maturity tier:

Critical exceptions (security-relevant, legally-required, or data-integrity-threatening removals) may use a shorter window with explicit announcement at either tier.

After 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.

4. Breaking vs. non-breaking changes

The following are non-breaking and may happen at any release without notice, at either maturity tier:

• Adding new terms (new URIs that did not exist before)
• Adding new fields to existing terms (e.g., new language labels, new altLabel entries, new properties keys)
• Adding new relations (narrower, related, closeMatch) that did not exist before
• Adding new languages to the multilingual index for any term
• Promoting a term from proposed to approved
• Promoting a language entry from langStatus: draft to langStatus: production
• Bug fixes that do not change semantic meaning (typos, formatting, broken links in scopeNotes)

The following are breaking and follow §3 deprecation rules at the current tier:

• Removing a term that was approved
• Changing the URI of an approved term
• Changing the meaning of an approved term in a way that would invalidate existing references
• Removing or renaming a JSON-LD field that consumers may have indexed (e.g., definition, notation, narrower)
• Changing the JSON-LD @context in a way that alters how existing fields are interpreted

The following are changes to the API contract itself and require their own dedicated announcement:

• Moving from /v1/ to /v2/ (new major version — see §6)
• Changing the deprecation policy (this document — see §9)
• Changing the maturity status of the API (beta → production — see §10)

5. Maturity levels

The API publishes a global maturity flag at /v1/version.json under maturity:

• alpha — Internal stealth use only. Structure and content may change without notice.
• 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.
• 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.

Maturity transitions are announced via the changelog at least 30 days in advance and are recorded as Strategic Decisions in the public log.

6. Major version transitions (v1 → v2)

If 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.

/v1/ URIs continue to resolve within the resolvability commitments in §1. They return the deprecated record with replacedBy pointers.

7. Communication channels

Changes are announced through:

• Changelog (https://api.ptpge.org/changelog.html) — human-readable
• Changelog Atom feed (https://api.ptpge.org/changelog.atom) — machine-subscribable
• Version endpoint (https://api.ptpge.org/v1/version.json) — current data version, maturity, deprecation counters
• This policy (https://api.ptpge.org/v1/deprecation-policy) — current rules
• Direct email to registered integrators — best-effort at beta tier, contractual at production tier (registration via register.ptpge.org)

At 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.

8. Reporting concerns

Consumers who believe a deprecation is mis-categorised (e.g., a term marked non-breaking but actually breaking for their use case) should report via:

• GitHub Issues on the public ptpge/ptpge repository
• Email to api@ptpge.org

• 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.
• Production tier (after §10): The Maintainers commit to acknowledging reports within 5 business days and providing a substantive response within 15 business days.

9. Policy changes

This policy itself is versioned. Changes follow these rules:

• Editorial clarifications (wording, typos, examples) may be made without notice; the patch version bumps (0.9 → 0.9.1).
• Substantive changes that affect consumer obligations or rights require:

- Beta tier: Minimum 30 days advance notice via the changelog, with a minor version bump (0.9 → 0.10). - Production tier: Minimum 90 days advance notice, with a minor version bump.

• Major changes require a major version bump and follow the §6 process for the policy document itself.

Significantly, 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.

The previous version of this policy remains available at /v1/deprecation-policy/history/.

10. Graduating MATURITY from beta to production

The transition from MATURITY = "beta" to MATURITY = "production" is itself a Strategic Decision and triggers the following commitment upgrades:

Graduation criteria (all must be met before MATURITY = "production"):

1. At least 12 months of stable Open Beta operation.
2. At least 3 external Founding Partners integrated and operational against the API.
3. The Pre-Open-Beta Checklist (docs/PRE-OPEN-BETA-CHECKLIST.md) is fully resolved with no remaining blockers.
4. A documented incident-response procedure has been tested at least once.
5. A Strategic Decision recording the graduation is signed by all current Maintainers.
6. A public announcement at least 30 days in advance of the transition.

These 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.

11. Maintainers and governance

PTPGE Maintainers are the named individuals responsible for the operational integrity of this API and the commitments in this policy. The current Maintainers are:

• Patrik Knutsson (Tangerin AS) — lead Maintainer, taxonomy and API operations

Additional 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).

A 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.

The 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.