Jira progress: loading…

USO-CC

USO Code Charter

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_type = uso:<domain>.<origin>.<signal_class>.<method>.<scope>.<detail>@v1

2.1. Segment Rules

USO Types are constructed from controlled ontology levels defined in:

zar.uso_type_level_registry

Each level represents a semantic classification layer:

• domain
• origin
• signal_class
• method
• scope
• detail

USO Types MUST be constructed using only approved level values. Free-text composition is forbidden.

Architecture

Concept	Meaning	Source
CMI	who produced	ZAR
CSI	what signal	SSSR
USO TYPE	why / semantic class	USO registry
USO INSTANCE	runtime lineage	telemetry

uso_name vs uso_code

Field	Meaning
uso_type	semantic classification (ontology)
uso_id	runtime instance (ULID)

In DB:

uso_type_id       bigint FK
uso_type_string   text (generated)

Runtime:

uso_id = ULID

---

2.2. Production-grade taxonomy (ESRS/IPCC aligned)

Level structure

Level	Name	Controlled
0	domain	YES
1	origin	YES
2	signal_class	YES
3	method	YES
4	scope	YES
5	detail	YES

---

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.

10. Related Documents

• 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

---