Validate a file from the shell¶

You have a contract and a data file and want a pass/fail answer without writing Python — locally or as a CI gate.

pycharter validate contracts/orders.yaml data/orders.jsonl

Contract: contracts/orders.yaml
Records: 1000  |  Valid: 987  |  Invalid: 13
Data-quality rules:
  ✓ min_rows (row_count): pass

  ✗ Row 4, Column 'price': expected float, found string 'N/A'
  ✗ Row 17, Column 'qty': expected integer, found string 'x'
  ✗ Row 121, Column 'id': required field is missing
  ...

✗ FAIL: the data does not satisfy the contract.

The whole contract is checked: every record against the schema and rules, then the contract's data_quality rules (row_count, null rates, uniqueness, expressions, …) over the records that passed. The exit code says which verdict you got, so the command drops straight into CI:

Exit	Verdict	Meaning
`0`	PASS	Every record and every required data-quality rule passed.
`1`	FAIL	A record or a required (`severity: error`) rule failed.
`2`	INCOMPLETE / error	A required rule could not be evaluated, or the inputs could not be loaded.

# .github/workflows/data-checks.yml (step)
pycharter validate contracts/orders.yaml sample/orders.jsonl --quiet || exit 1

Inputs and formats¶

Data: a .json file (array or single object), a .jsonl file (one object per line), or - for stdin:

curl -s https://api.example.com/orders | pycharter validate contracts/orders.yaml -

--format text (default) — colourised terminal report. Colour auto-disables when piped; force it off with --no-color or the NO_COLOR env var.
--format markdown — a table you can paste into a PR comment.
--format json — machine-readable status, per-rule dataset_checks, and diagnostics (row, field, expected type, offending value) for scripting:

pycharter validate contracts/orders.yaml data.jsonl --format json \
  | jq '.diagnostics[] | {row, field, expected}'

--quiet — suppress the report entirely; use the exit code only.
--strict-warnings — treat warning-severity rule violations (record rules and data-quality rules) as a failure (exit 1). By default warnings are reported (yellow ⚠) but do not fail the run — only hard errors do. Use this when a CI gate should block on advisory rules too. See Severity.

Installing the optional [cli] extra (pip install "pycharter[cli]") upgrades the text report to a column-aligned table; without it the command falls back to the plain output above — no other behaviour changes.