Metadata-Version: 2.4
Name: meridian-euid-spec
Version: 0.4.2
Summary: Specification, shared test vectors, and the Python reference implementation for Meridian Enterprise Unique Identifiers (EUIDs).
Author: Meridian contributors
License-Expression: CC-BY-4.0
Project-URL: Homepage, https://github.com/lsmc-bio/meridian-euid
Project-URL: Repository, https://github.com/lsmc-bio/meridian-euid
Project-URL: Documentation, https://github.com/lsmc-bio/meridian-euid/blob/main/README.md
Project-URL: Specification, https://github.com/lsmc-bio/meridian-euid/blob/main/SPEC.md
Project-URL: Issues, https://github.com/lsmc-bio/meridian-euid/issues
Keywords: euid,identifier,specification,test-vectors,crockford-base32,barcode,label
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE-SPEC
Dynamic: license-file

# meridian-euid

[![Python CI](https://github.com/lsmc-bio/meridian-euid/actions/workflows/python-ci.yml/badge.svg)](https://github.com/lsmc-bio/meridian-euid/actions/workflows/python-ci.yml)
[![Tag](https://img.shields.io/badge/tag-0.4.1-blue?style=flat-square)](https://github.com/lsmc-bio/meridian-euid/tags)
[![Spec](https://img.shields.io/badge/spec-0.4.0-blue?style=flat-square)](SPEC.md)
[![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg)](LICENSE-SPEC)

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

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

## Repository Structure

```text
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:

```json
{
  "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](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.
 
