Metadata-Version: 2.4
Name: empirical-data-contracts
Version: 0.1.0
Summary: Shared contracts for reproducible empirical data systems
Project-URL: Homepage, https://github.com/matuteiglesias/empirical-data-contracts
Project-URL: Repository, https://github.com/matuteiglesias/empirical-data-contracts
Project-URL: Issues, https://github.com/matuteiglesias/empirical-data-contracts/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic<3,>=2.7
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"

# empirical-data-contracts

Small shared schemas for empirical data pipelines. This package intentionally has no pandas, GeoPandas, DuckDB, raster, or FCV dependencies.

The contracts define identity, provenance, grain, geography, time, coverage, measurement state, QA, and run manifests. Persisted dataset schemas remain source-specific; these contracts form the common envelope around them.

## Installation

Once a release is published on PyPI, downstream repositories can install the package directly:

```bash
python -m pip install empirical-data-contracts
```

For consumers that want the compatible `0.1.x` contract line without automatically crossing a minor-version boundary:

```bash
python -m pip install "empirical-data-contracts>=0.1,<0.2"
```

The import package is `empirical_contracts`.

## Compatibility and versioning

The package follows semantic versioning, and serialized JSON is part of the public contract. Field names, field types, defaults, and serialized enum values should therefore be treated as compatibility-sensitive.

- **Patch releases** may fix implementation defects, tests, or documentation without changing the accepted or serialized contract.
- **Minor releases** may add new models or backward-compatible optional fields with defaults. They should preserve round-tripping of payloads valid under the previous minor release.
- **Major releases** are required for incompatible serialization or validation changes, including renaming or removing fields, changing field meaning or type, changing serialized enum values, or newly rejecting payloads that were previously valid.

Persisted dataset schemas are versioned independently through `DatasetRef.schema_version`. A producing package records its own release in `RunManifest.package_version`; source releases and snapshot identifiers remain separate provenance dimensions.

When compatibility cannot be preserved, prefer an explicit migration path over silent reinterpretation. In particular, row absence must not be reinterpreted as zero unless a coverage contract explicitly declares `zero_within_verified_coverage`.

See [RELEASE.md](RELEASE.md) for the human-controlled release procedure and PyPI Trusted Publishing setup.
