BattINFO Validation Contract#

This document defines the validation behavior that consumers can rely on for the supported BattINFO scope.

Supported Entry Points#

Core validation entry points:

  • battinfo validate

  • battinfo save ... --validate

  • battinfo publish ... --validate

  • battinfo index build --validate

  • battinfo.validate.validate_json(...)

  • battinfo.validate.validate_record(...)

  • battinfo.validate.validate_publication(...)

Policy Names#

BattINFO currently exposes these named validation policies:

  • default

  • strict

  • publisher

  • ingest

Policy semantics:

  • default: schema and references are errors; semantic issues default to warnings.

  • strict: schema, references, and semantic issues are errors.

  • publisher: publisher-oriented validation with semantic and publication checks as errors.

  • ingest: schema remains strict while semantic and reference issues can remain warnings during staged cleanup.

Issue Model#

Structured validation issues expose these fields:

  • code

  • severity

  • path

  • message

  • hint

  • validator

  • resource_type

  • profile

Severity values:

  • error

  • warning

Representative issue codes:

  • schema.required

  • schema.format.uri

  • schema.format.date_time

  • schema.profile_unknown

  • reference.missing

  • reference.type_mismatch

  • semantic.short_id_mismatch

  • semantic.temporal_order_invalid

  • semantic.electrode_holders_mixed (with semantic.electrode_role_expected / semantic.electrode_polarity_expected: the electrode holders disagree with the cell configuration — see Electrodes)

  • publication.distribution_url_invalid

  • publication.jsonld_parse_error

CLI Contract#

battinfo validate supports:

  • --format text

  • --format json

Text mode:

  • emits a human-readable pass/fail summary

  • includes warnings when validation succeeds with non-fatal issues

JSON mode emits a machine-readable payload with:

  • ok

  • mode

  • policy

  • profile

  • source_root

  • issue_count

  • error_count

  • warning_count

  • errors

  • issues

Example issue object:

{
  "code": "schema.format.uri",
  "severity": "error",
  "path": "dataset.url",
  "message": "'not-a-uri' is not a 'uri'",
  "hint": null,
  "validator": "format",
  "resource_type": "dataset",
  "profile": null
}

Exit codes:

  • 0 when no error-severity issues are present

  • 1 when one or more error-severity issues are present

Current Boundary#

Reference validation is supported against repository-style source trees through source_root.

Every *_id field on a record body resolves to a record of one expected type, and a reference that resolves to the wrong type is reference.type_mismatch rather than a pass. The distinctions the checks enforce are meaningful ones: cell_instance.cell_spec_id must be a cell-spec, while cell_instance.working_electrode_id / counter_electrode_id must be electrode records — the built batch, not the electrode-spec design, which the cell spec already links.

This is sufficient for the core scope, but it is not yet the long-term scalability model for larger external registries or snapshots.