meridian-euid-spec 0.4.2

Specification, shared test vectors, and the Python reference implementation for Meridian Enterprise Unique Identifiers (EUIDs).

meridian-euid

Meridian defines a compact Enterprise Unique Identifier (EUID) format suitable for printed labels and barcodes.

For v0.4.0, Meridian is intentionally strict:

• Canonical: one shape only, DOMAIN-PREFIX-BODYCHECKSUM
• Lookup-first: the string identifies an object but does not explain it
• Sequence-backed: BODY is a PostgreSQL BIGINT-bounded value
• Governed: (DOMAIN, PREFIX) ownership is tracked in checked-in JSON registries
• Python-first: Python is the only supported reference implementation in this repo

Quick Start

Python

cd reference-implementations/python
pip install -e ".[dev]"

# Validate a canonical EUID
meridian-euid validate A1-Z9-3V9

# Encode an integer as a canonical EUID
meridian-euid encode 123 Z9 --domain-code A1

# Parse an EUID into its structural components
meridian-euid parse MAX-MAX-7ZZZZZZZZZZZZB

# Compute the check character for DOMAIN + PREFIX + BODY
meridian-euid compute-check A1Z93V

Documentation

Document	Description
SPEC.md	Normative specification
meridian_clinical_lab_profile.md	Minimal barcode and rendering profile for clinical lab use
checksum_elaboration.md	Why Meridian keeps the checksum inside the same safe alphabet
domain_code_registry.json	Checked-in manual registry of valid domain codes
prefix_ownership_registry.json	Checked-in manual registry of (domain, prefix) ownership
test-vectors/README.md	Shared machine-readable vectors and contract notes
reference-implementations/python/README.md	Python reference implementation and CLI

Repository Structure

meridian-euid/
├── SPEC.md
├── CHANGELOG.md
├── domain_code_registry.json
├── prefix_ownership_registry.json
├── meridian_clinical_lab_profile.md
├── checksum_elaboration.md
├── test-vectors/
│   ├── README.md
│   └── v3.json
└── reference-implementations/
    └── python/

EUID Format

Canonical format:

DOMAIN-PREFIX-BODYCHECKSUM

Example:

A1-Z9-3V9

Rules:

• DOMAIN: 1-4 uppercase Crockford Base32 characters from 0123456789ABCDEFGHJKMNPQRSTVWXYZ
• PREFIX: 1-4 uppercase Crockford Base32 characters from the same alphabet
• BODY: Crockford Base32 encoding of an integer in 1..9223372036854775807, with no leading 0
• CHECKSUM: 1 Crockford Base32 character
• Forbidden everywhere: I, L, O, U
• Lowercase input MUST be rejected
• Checksum payload is DOMAIN + PREFIX + BODY; hyphens are syntax only

Governance

The repo carries a lightweight manual governance model:

• domain_code_registry.json declares valid domains.
• prefix_ownership_registry.json maps each (DOMAIN, PREFIX) pair to exactly one issuer_app_code.

issuer_app_code is a lowercase ASCII governance token matching:

^[a-z0-9]+(?:[._-][a-z0-9]+)*$

Claims are explicit JSON objects, for example:

{
  "Z9": {
    "issuer_app_code": "meridian.lims"
  }
}

Canonical validation does not require a governance lookup. Issuance and resolver routing typically do.

Breaking Note

v0.4.0 removes the older split shapes and compatibility surfaces:

• no absent-domain form
• no : separator
• no sandbox/production mode split
• no legacy aliases
• no supported TypeScript reference implementation

Contributing

Before proposing changes:

1. Run the Python test suite under reference-implementations/python.
2. Keep the registries human-auditable.
3. Update the shared vectors and docs in the same change when syntax or governance expectations move.
4. Treat syntax, alphabet, checksum, and integer-range changes as major-version work.