feedback_iri_terminology_discipline

Adopted Thu 23 April 2026 after Rich’s session question “URI seems close to death, we should embrace IRI.” Decision Q2: adopt all 5 opportunities in full. Codifies the operational rules for how INHERIT v2 + InheritKit treat the IRI vs URI distinction going forward.

The rule

From 2026-04-23 onwards, all new INHERIT v2 + InheritKit writing uses “IRI” (Internationalized Resource Identifier, RFC 3987) as the canonical term in ontology / schema / axiom / spec contexts. Forward-looking only — do NOT bulk-convert existing docs. Mixed register during transition is acceptable; docs normalise naturally as edited. Parallels feedback_international_english_for_inherit_v2 pattern.

Why: RDF 1.1 (W3C REC 2014), OWL 2 (2012), SHACL (2017), JSON-LD 1.1 (2020) all standardise on IRI for semantic-web contexts. ISO 21838-2 (BFO), ISO 21127 (CIDOC CRM) and adjacent upper ontologies in their current editions use IRI. For INHERIT v2’s ISO/OASIS PAS submission target (2028-2030 per brand-architecture.md §6), “URI” reads as out-of-date terminology to standards-body reviewers.

How to apply:

1 — Terminology discipline (forward-looking):

• New spec text (architecture-proposal, scoping docs, amendment bodies) uses “IRI” for ontology-layer / axiom / schema identifiers
• Use “URL” when specifically meaning HTTP-addressable-location (browser URL bar, API endpoint URL)
• Use “URI” when citing older specs / RFC 3986 directly / historical compatibility discussion
• Never bulk-migrate existing “URI” occurrences — natural drift only
• Paired with feedback_international_english_for_inherit_v2 — both are “new writing from 2026-04-20/23 onwards” disciplines with no bulk-migration requirement

2 — ASCII-only Phase-1 canonical identifiers (mandatory):

• All inherit-* namespace class + property identifiers use ASCII characters only
• Unicode content (accented characters, non-Latin scripts, CJK) lives in rdfs:label, skos:definition, skos:prefLabel, skos:altLabel — NOT in the IRI itself
• Matches precedent of FIBO + BFO + CIDOC CRM + DublinCore + FOAF + PROV-O + DOLCE — every major upper ontology
• Rationale: tool-chain safety (editors, diff tools, clipboard, URL-bar copy-paste, grep, debug logs); partner-onboarding friction minimisation; no URL-percent-encoding confusion
• Example CORRECT: inherit-faith-islamic:Wasiyya rdfs:label "وَصِية"@ar, "wasiya"@en-GB, "bequest"@en-US ;
• Example WRONG (Phase 1): inherit-faith-islamic:وَصِية (Unicode identifier — valid IRI but deferred to Phase 2+)

3 — Unicode-IRI door left open for Phase-2+ jurisdiction crates (documented option):

• Phase-2+ @inheritkit/jurisdiction-* or @inheritkit/faith-* crates MAY use Unicode IRIs if partner demand warrants
• Examples where this might apply: Arabic-script for Sharia concepts; Devanagari for Hindu succession law; CJK for East-Asian jurisdictions; extended-Latin (umlauts, accents) for Swiss cantonal / German / French law
• Phase-1 default remains ASCII transliteration in identifier + Unicode in label
• Decision is deferred to per-crate authoring time with partner consultation
• Not a Phase-1 scope commitment — zero build cost now; option preserved architecturally

4 — ISO/OASIS PAS submission text (target 2028-2030):

• PAS submission draft uses “IRI” throughout spec body
• Cites RFC 3987 + W3C RDF 1.1 + OWL 2 as authoritative references
• Cross-refs ISO 21838-2 (BFO) + ISO 21127 (CIDOC CRM) for alignment coherence
• Falls out of discipline 1 naturally — not a separate authoring step

5 — InheritKit SDK branded-string type alias:

• TypeScript SDK exposes: export type IRI = string & { readonly __iri: unique symbol };
• Signals IRI-semantics at the type layer; prevents accidentally passing plain strings where an IRI is expected
• JSDoc annotation: /** An IRI per RFC 3987. Every URI is a valid IRI. ASCII-only identifiers are the Phase-1 convention in INHERIT core namespaces. */
• Non-TypeScript SDKs (Python, Go, Java — if ever built) implement equivalent discipline per language idiom (Python NewType; Go defined type; Java value-class)
• Phase-1 compromise acceptable: plain type IRI = string + JSDoc (80% of value, 20% of discipline friction) — upgrade to full branded-string in Phase-2 when API surface stabilises

Do NOT

• Bulk-migrate existing “URI” → “IRI” in already-committed INHERIT v2 docs. Churn cost > signal benefit.
• Use non-ASCII IRIs in Phase-1 canonical primitives. Tool-chain risk + standards-body precedent says no. Unicode belongs in labels/definitions, not identifiers.
• Declare “URI is deprecated” as a policy. It isn’t. URLs are URIs. HTTP/REST APIs are URI-based. The Apache 2.0 licence URL is a URI. The umbrella continues where it applies.
• Apply this to existing TT brand docs (IW/MFI/LL/OpenInherit brand-architecture/partner-model/memories). British-English + legacy-URI-terminology stays default for those. This discipline applies to NEW INHERIT v2 + InheritKit writing only.
• Confuse this with feedback_iri_verification_before_lock. Verification (the spike discipline) and terminology (this rule) are separate concerns. Verification is rigidly required for any external-ontology alignment axiom; terminology is a style rule.

Cross-references

• feedback_iri_verification_before_lock — the complementary discipline: verify external IRIs before committing alignment axioms
• feedback_international_english_for_inherit_v2 — parallel “forward-looking new-writing” pattern; both adopted as style disciplines
• feedback_v2_apache_deferred_until_public_release — why terminology correctness matters (irrevocable at public release; pre-public window is when to get it right)
• ideas/2026-04-23-iri-not-uri-terminology.md v1.0 — source brainstorm-fragment + opportunities analysis (committed 5e84f2d) — this memory supersedes it operationally; the ideas doc retains historical context
• docs/superpowers/specs/spike-fibo-role-2026-04-23/findings.md v1.0 — the FIBO spike that surfaced IRI as a distinct concept
• brand-architecture.md v1.4 §6 (OpenInherit international ISO-track positioning) — downstream beneficiary of this discipline