Specification, shared test vectors, and the Python reference implementation for Meridian Enterprise Unique Identifiers (EUIDs).
Project description
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
Structure / Namespeaces (Domains & Prefixes) / Encoding Compression
Meridian BODY length example table for fixed label Z-TU-<body><checksum>
Assumptions:
- alphabet size = 32
- first BODY character cannot be
0 - BODY encodes an integer in
1..9223372036854775807 - checksum is always exactly 1 character
- full visible label length =
len(body) + 6
Cap:
- max BODY integer:
9223372036854775807 - max BODY encoding:
7ZZZZZZZZZZZZ - max BODY length:
13
| BODY length | Exact valid BODY encodings at this length | Cumulative valid BODY encodings up to this length | Full label length Z-TU-... |
|---|---|---|---|
| 1 | 31 | 31 | 7 |
| 2 | 992 | 1,023 | 8 |
| 3 | 31,744 | 32,767 | 9 |
| 4 | 1,015,808 | 1,048,575 | 10 |
| 5 | 32,505,856 | 33,554,431 | 11 |
| 6 | 1,040,187,392 | 1,073,741,823 | 12 |
| 7 | 33,285,996,544 | 34,359,738,367 | 13 |
| 8 | 1,065,151,889,408 | 1,099,511,627,775 | 14 |
| 9 | 34,084,860,461,056 | 35,184,372,088,831 | 15 |
| 10 | 1,090,715,534,753,792 | 1,125,899,906,842,623 | 16 |
| 11 | 34,902,897,112,121,344 | 36,028,797,018,963,967 | 17 |
| 12 | 1,116,892,707,587,883,008 | 1,152,921,504,606,846,975 | 18 |
| 13 | 8,070,450,532,247,928,832 | 9,223,372,036,854,775,807 | 19 |
Notes
Note the significant compression crocker offers over integer only identifiers. If body was limited to only integers, then if body length == 1, there would be 9 int encodings (excluding 0) vs the 32 crocker encodings for body=1 ... and at body length==6 there are 1M integer possibilities and 1B crocker encoded possibilities.
For BODY lengths 1 through 12:
- exact count =
31 × 32^(n-1)
For BODY length 13:
- the raw syntactic count would be
31 × 32^12 - but the integer cap truncates that to exactly:
7 × 32^12 = 8,070,450,532,247,928,832
The cumulative total through length 13 equals the full allowed BODY integer space:
9,223,372,036,854,775,807
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 from0123456789ABCDEFGHJKMNPQRSTVWXYZPREFIX: 1-4 uppercase Crockford Base32 characters from the same alphabetBODY: Crockford Base32 encoding of an integer in1..9223372036854775807, with no leading0CHECKSUM: 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.jsondeclares valid domains.prefix_ownership_registry.jsonmaps each(DOMAIN, PREFIX)pair to exactly oneissuer_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:
- Run the Python test suite under reference-implementations/python.
- Keep the registries human-auditable.
- Update the shared vectors and docs in the same change when syntax or governance expectations move.
- Treat syntax, alphabet, checksum, and integer-range changes as major-version work.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file meridian_euid_spec-0.4.5.tar.gz.
File metadata
- Download URL: meridian_euid_spec-0.4.5.tar.gz
- Upload date:
- Size: 29.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.14.2
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7fbbc8df0e98b9f20084508f3e9a22d527b4f5872c118b5f31eca03c530d490c
|
|
| MD5 |
759043c85ed72919b2cd150a1799081a
|
|
| BLAKE2b-256 |
dee9ef1c794b93555bb71d6548ce50a9d440218fc7ce605d7f449a50d09364f9
|
File details
Details for the file meridian_euid_spec-0.4.5-py3-none-any.whl.
File metadata
- Download URL: meridian_euid_spec-0.4.5-py3-none-any.whl
- Upload date:
- Size: 4.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.14.2
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3d95f7d14860da1f60b808375003328bcb1b3a0076e95d7c3a1f856bc101a193
|
|
| MD5 |
033b291575b42b2d9a1f3cb51edf6acd
|
|
| BLAKE2b-256 |
934df623e979d52430e052169aab23679605b0f8ca0e5ae01585e1bdb3475ff2
|
