meridian-euid (Python)

Python reference implementation of the Meridian EUID specification.

The v0.4.0 line is strict and canonical:

• one syntax: DOMAIN-PREFIX-BODYCHECKSUM
• one validation mode
• no sandbox aliases
• no absent-domain form
• no tolerant normalization

Requirements

• Python 3.10+

Installation

From source (development)

git clone https://github.com/lsmc-bio/meridian-euid.git
cd meridian-euid/reference-implementations/python

pip install -e .
pip install -e ".[dev]"

CLI Usage

The meridian-euid command provides four subcommands.

validate

Validate a canonical EUID.

meridian-euid validate A1-Z9-3V9

encode

Encode an integer as a canonical EUID.

meridian-euid encode 123 Z9 --domain-code A1

Argument/Option	Required	Description
integer	Yes	Integer in 1..9223372036854775807
prefix	Yes	Prefix token (1-4 uppercase Crockford Base32 characters)
--domain-code	Yes	Domain token (1-4 uppercase Crockford Base32 characters)

parse

Parse a validated EUID into its components.

meridian-euid parse A1-Z9-3V9

compute-check

Compute the check character for a payload.

# Payload is DOMAIN + PREFIX + BODY, with no hyphens
meridian-euid compute-check A1Z93V

Programmatic API

Canonical functions

from meridian_euid import (
    BIGINT_MAX,
    compute_check_character,
    encode,
    is_valid,
    parse,
    validate,
)

assert validate("A1-Z9-3V9") == "A1-Z9-3V9"
assert is_valid("A1-Z9-3V9") is True
assert encode(123, "Z9", domain_code="A1") == "A1-Z9-3V9"
assert parse("A1-Z9-3V9") == {
    "domain_code": "A1",
    "prefix": "Z9",
    "body": "3V",
    "checksum": "9",
    "integer": 123,
}
assert compute_check_character("A1Z93V") == "9"
assert BIGINT_MAX == 9223372036854775807

Governance helpers

from meridian_euid import (
    MERIDIAN_REGISTRY_INDEX_URL,
    check_domain_availability,
    assert_prefix_issuer_app_code,
    assert_registered_domain,
    load_domain_registry,
    load_prefix_ownership_registry,
    resolve_prefix_issuer_app_code,
    validate_issuer_app_code,
    validate_registries_consistent,
)

domains = load_domain_registry()
ownership = load_prefix_ownership_registry()

assert_registered_domain("A1", registry=domains)
assert_registered_domain(
    "M",
    reserved_for="LSMC",
    deployment_environment="production",
)
assert_registered_domain(
    "M",
    reserved_for="LSMC",
    deployment_environment="staging",
    approval_tokens=["approval-a", "approval-b", "approval-c"],
)
assert validate_issuer_app_code("meridian.lims") == "meridian.lims"
assert resolve_prefix_issuer_app_code("A1", "Z9", registry=ownership) == "meridian.lims"
assert_prefix_issuer_app_code("A1", "Z9", "meridian.lims", registry=ownership)
validate_registries_consistent()

The public domain-code authority is lsmc-bio/meridian-registry. The current pinned generated index URL is available as MERIDIAN_REGISTRY_INDEX_URL, but the library does not fetch it at runtime. Pass an explicit local path:

result = check_domain_availability(
    "N",
    registry_index_path="/path/to/registry/generated/domains.json",
)
assert result["available"] is False

The CLI exposes the same explicit check:

meridian-euid domain-check N --registry-index /path/to/registry/generated/domains.json

When called without path=..., the legacy helper functions load bundled JSON fixtures shipped inside the wheel. Pass path= to point at an alternate local registry file. These fixtures are not the public domain-code authority.

issuer_app_code values are governance tokens, not part of the canonical EUID grammar. They MUST match:

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

Exceptions

from meridian_euid import (
    EUIDChecksumError,
    EUIDDomainCodeError,
    EUIDError,
    EUIDFormatError,
    EUIDGovernanceError,
    EUIDIssuerAppCodeError,
    EUIDPrefixOwnershipError,
)

Exception	Raised when
EUIDFormatError	Canonical syntax, prefix, BODY, or checksum-token validation fails
EUIDChecksumError	The checksum does not match
EUIDDomainCodeError	The domain token is syntactically invalid
EUIDGovernanceError	Registry-backed governance checks fail
EUIDIssuerAppCodeError	An issuer_app_code fails grammar validation
EUIDPrefixOwnershipError	A prefix is unclaimed or claimed by a different issuer_app_code

Running Tests

pytest --cov --cov-report=term-missing
ruff check meridian_euid tests
mypy meridian_euid --ignore-missing-imports

Tests use shared vectors from test-vectors/v3.json.

Related Documentation

• SPEC.md — Normative specification
• meridian-registry
• domain_code_registry.json — legacy local fixture
• prefix_ownership_registry.json — local prefix fixture
• checksum_elaboration.md