Skip to main content
Jira progress: loading…

USO-CC

USO Code Charter (v1.0)

1. Purpose​

The USO Code Charter defines the mandatory rules for constructing and validating Universal Signal Ontology (USO) identifiers across the ZAYAZ platform.

USO names are the semantic spine of ZAYAZ.
They must be globally stable, compact, machine-joinable, and audit-safe across:

  • ZAR (ZAYAZ Artifact Registry)
  • SSSR (Smart Searchable Signal Registry)
  • Telemetry & Audit (ALTD / DAL)
  • Policy Routing (TRPG / ZADIF)
  • Reporting, Verification, and Explainability (ZARA)

This charter is platform law.

2. Canonical USO Name Format​

USO_NAME = CODE0-CODE1-CODE2-CODE3-CODE4-CODE5-column_id

2.1. Segment Rules​

2.1.1. CODE0 … CODE5​

Each CODE* segment MUST:

  • Be sourced from ZAR-REGISTRY-COMPONENTS
  • Use the canonical uso_code value
  • Be uppercase alphanumeric
  • Be 3–5 characters long
  • Contain no hyphens
  • Be globally unique within the registry

Hyphenated component IDs (e.g. AAE-MIB, MEID-CALC)
MUST NEVER appear inside a USO name.
They must be normalized via the registry mapping:

component_id → uso_code

2.1.2 column_id​

The final segment MUST:

  • Be lowercase_snake_case
  • Start with a letter
  • Contain only a–z, 0–9, _
  • Have no trailing underscore
  • Max length: 64 characters

3. Source of Truth​

  • The only authoritative source for USO codes is: ZAR-REGISTRY-COMPONENTS-v1
  • Human-facing fields (title, href, labels) are non-contract metadata
  • USO never consumes raw component IDs — only their uso_code

4. Stability & Governance Rules​

  • Once published, a uso_code is immutable
  • Renaming a component:
    • Allowed to change title / href
    • Must not change uso_code
  • Replacing a component:
    • Mark old entry as deprecated
    • Set replaced_by
    • Old uso_code is reserved forever (never reused)

4.1. Collision Policy​

  • uso_code values must be globally unique
  • Any collision must be resolved explicitly in the registry
  • Runtime or heuristic disambiguation is forbidden

5. No Version or Instance Encoding​

USO identifiers MUST NOT encode:

  • Versions (v1, 1.2.0)
  • Instance numbers
  • Deployment regions
  • Runtime variants

These belong in execution metadata, not ontology identifiers.

6. Runtime Enforcement​

  • Any API, engine, or module emitting USO identifiers MUST:
    1. Resolve component_id
    2. Normalize to uso_code
    3. Emit USO using only registry-approved codes
  • Missing or unknown mappings are a hard error
  • Silent fallback or string substitution is not permitted

7. CI / Linting Requirements​

Validate uso_code​

^[A-Z0-9]{3,5}$

CI MUST enforce:

  • Regex compliance
  • Global uniqueness
  • Immutability after release

8. Validate Full USO_NAME​

^[A-Z0-9]{3,5}(?:-[A-Z0-9]{3,5}){5}-[a-z][a-z0-9_]{0,62}[a-z0-9]$

This enforces:

  • Exactly 6 USO codes
  • Correct casing and length
  • A valid snake_case column identifier

9. Design Principle​

USO is not documentation. USO is executable meaning.

If a value is ambiguous, mutable, or human-dependent, it does not belong in a USO identifier.

  • Universal Signal Ontology (USO) — Semantic Framework
  • ZAR — ZAYAZ Artifact Registry
  • Canonical Identifier Architecture (CIA)
  • Engine Alias Map
  • SSSR — Smart Searchable Signal Registry

Version: 1.0 Status: Stable Governance: ZAR / USO Council

GitHub RepoRequest for Change (RFC)