brushline.model.schema

The compiled dataset contract, the manifest models, the checksum helper, and the validator. The validator is the oracle for the dataset boundary: a malformed dataset fails with a named error.

Compiled corridor dataset contract and validator.

The dataset is the boundary between ingestion and execution. A dataset directory contains a manifest.json and one file per table. The manifest names the schema version, the CRS, the units, the tables, their column contracts, their checksums, and the provenance. The validator checks the manifest, the table files, the schemas, the keys, the row counts, the checksums, and the content digest.

The contract is deliberately small in P1.1. The full segment, state, treatment, observation, plan, run, archive, and timeline tables are added by P1.2 to P1.4.

brushline.model.schema.file_sha256(path: Path) → str[source]

Return the SHA-256 digest of a file.

Parameters:

path (Path) – File to hash.

Returns:

str – Lowercase hexadecimal SHA-256 digest.

class brushline.model.schema.DatasetValidation(dataset: Path, errors: tuple[str, ...], warnings: tuple[str, ...], tables: dict[str, int])[source]

Bases: object

The outcome of validating one compiled dataset.

Parameters:
  • dataset (Path) – Resolved dataset directory.

  • errors (tuple of str) – Named errors. An empty tuple means the dataset is valid.

  • warnings (tuple of str) – Non-fatal findings.

  • tables (dict of str to int) – Row count per table that could be read.

property is_valid: bool

Return whether the dataset passed every check.

Returns:

bool – True when there are no errors.

to_dict() → dict[str, object][source]

Return a JSON-ready report.

Returns:

dict of str to object – The dataset path, validity, errors, warnings, and table row counts.

class brushline.model.schema.ColumnSpec(*, name: Annotated[str, MinLen(min_length=1)], dtype: Literal['string', 'int64', 'float64', 'bool', 'datetime', 'date'], required: bool = True, unit: str | None = None, description: str = '')[source]

Bases: BaseModel

One column in a dataset table.

Parameters:
  • name (str) – Column name.

  • dtype ({"string", "int64", "float64", "bool", "datetime", "date"}) – Logical column type.

  • required (bool, optional) – Whether the column must be present. Defaults to True.

  • unit (str or None, optional) – Physical unit, when the column has one.

  • description (str, optional) – Short human description.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.model.schema.TableSpec(*, name: Annotated[str, MinLen(min_length=1)], path: Annotated[str, MinLen(min_length=1)], format: Literal['parquet', 'csv'], primary_key: Annotated[list[str], MinLen(min_length=1)], columns: Annotated[list[ColumnSpec], MinLen(min_length=1)], row_count: Annotated[int, Ge(ge=0)], sha256: Annotated[str, _PydanticGeneralMetadata(pattern='^[0-9a-f]{64}$')])[source]

Bases: BaseModel

One table in a compiled dataset.

Parameters:
  • name (str) – Logical table name.

  • path (str) – Dataset-relative file path.

  • format ({"parquet", "csv"}) – File format.

  • primary_key (list of str) – Columns that form the primary key.

  • columns (list of ColumnSpec) – Column contracts.

  • row_count (int) – Expected row count.

  • sha256 (str) – Expected SHA-256 of the table file.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.model.schema.Provenance(*, source: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], source_version: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], licence: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], created_by: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], configuration: dict[str, object] = <factory>, model_cards: list[str] = <factory>)[source]

Bases: BaseModel

The provenance of a compiled dataset.

Parameters:
  • source (str) – Source name.

  • source_version (str) – Source version or vintage.

  • licence (str) – Licence identifier.

  • created_by (str) – Person, process, or agent that built the dataset.

  • configuration (dict of str to object, optional) – Build configuration values.

  • model_cards (list of str, optional) – Model-card identifiers used to derive attributes.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.model.schema.DatasetManifest(*, schema_version: Literal['brushline.dataset.v1'] = 'brushline.dataset.v1', dataset_id: Annotated[str, MinLen(min_length=1)], name: Annotated[str, MinLen(min_length=1)], description: str = '', created_utc: datetime, crs: Annotated[str, MinLen(min_length=1)], units: Annotated[dict[str, str], MinLen(min_length=1)], tables: Annotated[list[TableSpec], MinLen(min_length=1)], provenance: Provenance, content_digest: Annotated[str, _PydanticGeneralMetadata(pattern='^[0-9a-f]{64}$')])[source]

Bases: BaseModel

The manifest of a compiled corridor dataset.

Parameters:
  • dataset_id (str) – Stable dataset identifier.

  • name (str) – Human-readable dataset name.

  • description (str) – Short description.

  • created_utc (datetime) – Timezone-aware creation time.

  • crs (str) – Coordinate reference system.

  • units (dict of str to str) – Named units, such as length and area.

  • tables (list of TableSpec) – Table contracts. The segments table is required.

  • provenance (Provenance) – Source and build provenance.

  • content_digest (str) – SHA-256 of the canonical content fields.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

table(name: str) → TableSpec[source]

Return one table spec by name.

Parameters:

name (str) – Table name.

Returns:

TableSpec – The matching table spec.

Raises:

KeyError – When the table is not in the manifest.

compute_content_digest() → str[source]

Return the canonical content digest of the manifest.

The digest covers the schema version, dataset id, CRS, and the table contracts. It does not cover created_utc or the human-readable name and description, so a rebuild with the same content keeps the same digest.

Returns:

str – Lowercase hexadecimal SHA-256 digest.

brushline.model.schema.load_manifest(root: Path) → DatasetManifest[source]

Load and validate a dataset manifest.

Parameters:

root (Path) – Dataset directory.

Returns:

DatasetManifest – The parsed manifest.

Raises:
  • FileNotFoundError – When the manifest file does not exist.

  • pydantic.ValidationError – When the manifest does not satisfy the contract.

brushline.model.schema.write_manifest(root: Path, manifest: DatasetManifest) → Path[source]

Write a dataset manifest as sorted, indented JSON.

Parameters:
  • root (Path) – Dataset directory.

  • manifest (DatasetManifest) – Manifest to write.

Returns:

Path – Path of the written manifest.

brushline.model.schema.validate_dataset(root: Path) → DatasetValidation[source]

Validate a compiled dataset against its manifest.

Parameters:

root (Path) – Dataset directory.

Returns:

DatasetValidation – Errors, warnings, and table row counts. The dataset is valid when errors is empty.