Glossary

One-line definitions of the terms used throughout the docs, roughly in the order you meet them. Follow the links for the full story.

Term	Meaning
Data contract	A versioned YAML/JSON artifact describing the shape and rules of a dataset: JSON Schema plus optional coercion rules, validation rules, metadata, and field bindings. The unit everything else consumes. See Concepts.
JSON Schema	The json_schema block of a contract — field names, types, and constraints (minimum, minLength, …). Compiled into a Pydantic model at load time.
Coercion	Converting a value to the contract's type before validation — "25" → 25, int → float, "" → null. Declared per field under coercion_rules. See built-in coercions.
Validation	Checking a record against the compiled contract. Fails with structured diagnostics; does not modify data (coercion does that first).
Diagnostic	A structured description of one validation failure: row, column, expected type, offending value, and severity (FieldDiagnostic). Rendered as Row 45, Column 'price': expected float, found string 'N/A'.
Severity	Whether a rule violation invalidates the record. A validation rule with severity: warning is advisory — reported (yellow ⚠, result.warnings) but the record stays valid; the default error fails it. Types and required-ness in json_schema are always hard failures.
Validator	The primary validation class: Validator.from_file(...) / .from_dict(...) / .from_store(...), then .validate(record) or .validate_batch(records). See Validator API.
Quarantine	Failure handling that splits bad rows out (with their violations attached) while good rows continue — validate_dataframe(df, c, on_error="quarantine") in code, on_error: quarantine in pipeline steps.
on_error	The shared failure-behaviour vocabulary: fail (abort/raise), warn (log and continue), skip (drop the record, pipeline steps only), quarantine (route to DLQ / quarantined frame).
DLQ (dead-letter queue)	Where quarantined records land — an append-only store (JSONL file, database table, or queue) holding the failed payload plus its violation details for later replay or triage.
Contract store	The schema registry: stores contracts by name + version. Backends: in-memory, SQLite, PostgreSQL, MongoDB, Redis. See Contract Store.
Pipeline	A configuration-driven ETL run: extract → transform → load steps declared in YAML, executed with pycharter.run("pipeline.yaml"). See Pipelines.
Step contract block	The contract: section on a pipeline step — which contract to enforce there, plus on_error and an optional dlq: target.
Quality check	Post-validation monitoring: completeness, validity rate, quality score, threshold breaches, and recorded violations (check_quality / QualityCheck). Validation gates data; quality monitors it. See Quality API.
Sketch	A starter contract inferred from existing data — sketch_from_dataframe(df), pycharter contract sketch --from-csv. A first draft to edit, not a finished contract.
Contract diff	Version-to-version comparison with a breaking-change flag: pycharter contract diff old.yaml new.yaml --fail-on-breaking. The CI gate for contract evolution.
Contract lint	Advisory findings about a contract's own declarations: pycharter contract lint orders.yaml --fail-on warning. Today's rules reconcile the legacy metadata.governance_rules.pii_fields list with the per-field pii / restricted flags the runtime enforces (governance_pii_mismatch warning, governance_pii_redundant info). Pure lint_contract() under the hood.
ODCS	Open Data Contract Standard — an interchange format. from_odcs / to_odcs convert between ODCS documents and PyCharter contracts.
Semantic store / ontology	The third domain: concept schemes, concepts, and relationships that give fields business meaning via field bindings.
Field binding	A link from a contract field (e.g. $.email) to an ontology concept (e.g. user_email), giving the field semantic context beyond its type.
Job worker	Shared daemon (pycharter worker) polling validation_jobs and pipeline_jobs; runs finite validation or batch pipeline jobs. One pool per deployment — not one process per config.
Stream worker	Long-lived process (pycharter stream run) running one streaming config; all streams[] entries run concurrently inside a single OS process. Validates live sources (Kafka, WebSocket, …) continuously. Started from the Run tab via Start stream worker.
Stream launcher	Long-lived process (pycharter stream launch) that polls streaming_jobs and spawns stream workers. Separate from the job worker (pycharter worker).
API server	HTTP control plane (pycharter api) — config CRUD, batch runs (in-process), read-only stream-worker observability. Separate from job worker and stream worker runtimes.
Preflight	Config-side checks before running a pipeline — contracts resolve, references exist — without moving any data: pycharter.preflight(config).