PyCharter — Canonical Terminology¶

Status: accepted · Created: 2026-05-28 · Audience: every contributor

This document is the authoritative dictionary for pycharter. If a term you want to use is not in the Approved Vocabulary table below, either pick one that is, or open a PR to extend this doc — do not coin synonyms. Code, docs, OpenAPI descriptions, route paths, file names, template names, BACKLOG entries, commit messages, and PR descriptions all use this vocabulary.

This decision is not subject to backward compatibility. There are no soft aliases, no deprecation warnings, no transitional shims. The old names are gone. Renames land atomically with their call sites.

The Three Pillars¶

PyCharter has exactly three pillars. Every public surface, every package, every doc section is in service of one of them:

Pipeline — how data moves. Extract, transform, load, validate, observe.
Contract — what data should look like. JSON Schema + coercion rules + validation rules + governance metadata.
Vocabulary — what data means. The governed set of named concepts a contract field (or any other resource) can bind to.

These are co-equal. A pycharter user understands the product by understanding these three words. Do not invent a fourth.

Approved Vocabulary¶

These are the only names allowed for these ideas. Every row lists the canonical term, what it refers to, and the retired synonyms that must not appear in new code or docs.

Vocabulary layer¶

Canonical	Definition	Retired synonyms (do not use)
Vocabulary	The third pillar. The system in pycharter that owns governed meaning.	"Ontology layer", "Knowledge base layer", "KB layer", "Semantic layer (as pillar)"
Concept	One governed entry in a vocabulary. Has a `concept_key`, `name`, `tier` (`free` / `domain` / `core`), `concept_type`, optional description, and zero-or-more typed relationships to other concepts.	"Term", "Ontology entry", "KB node", "Semantic tag"
Concept scheme	A named, versioned collection of concepts. Every concept belongs to exactly one scheme.	"Ontology", "KB", "Vocabulary instance", "Domain ontology"
Concept relationship	A typed edge between two concepts (`is_a`, `has`, `equivalent_to`, `same_as`, …).	"Semantic relationship", "Ontology relation"
Binding	The link from a resource (a contract field, a CRM record id, a document chunk, any external_ref) to a concept in the vocabulary. Driven through the DG-1 `ResourceBinding` lifecycle.	"Mapping", "Annotation" (in the binding sense), "Concept attachment"
Field binding	The specialisation of binding where `source="contract_field"`. The link from a contract field path to a concept.	"Field mapping", "Field annotation", "FieldConceptBinding"
Concept annotation	The runtime sidecar a pipeline emits on a record (`record["_concept_annotations"]`) listing which concepts each field was bound to during validation. Distinct from a binding (authoring artifact) — this is the runtime output.	"KB annotation", "`_kb_annotations`", "Semantic annotation (on a record)"
Extraction	The process of producing concept suggestions from non-schema sources (records, code, docs). The output goes into the suggestion queue, never directly into the concept registry.	"KB extraction", "Concept ingestion (no — that's a different thing)"
Suggestion	An unaccepted candidate concept (or relationship) in the governance queue. Lives in the `semantic_suggestions` table. Moves to `accepted` → `materialized` (which creates the concept row) or `rejected`.	"Proposal" (mostly retired), "KB candidate"
Extraction policy	The per-contract / per-step governance policy that gates concept extraction: `trigger` (`automatic` / `manual` / `off`), `tier_ceiling`, `extractors` whitelist, `sampling`, `drift_thresholds`, `target_scheme_id`.	"KB policy", "`KBPolicy`", "Annotation policy"
Extraction sink	The runtime object that wraps a pipeline step's record stream when `extraction_policy.trigger == "automatic"`, captures samples, and feeds the extractor on finalisation.	"KB sink", "`AutoExtractionSink`" (the class name can stay but the docstring no longer uses "KB")

Shape layer (LinkML)¶

Canonical	Definition	Retired synonyms
LinkML schema	An external LinkML YAML file declaring classes, slots, ranges, cardinality. The shape language. Independent of vocabulary.	"Ontology" (when used to mean a LinkML schema), "Domain ontology file"
LinkML schema registry	The filesystem-backed registry of immutable, versioned LinkML schemas. Resolves `name:version` refs.	"Ontology version registry", "`OntologyVersionRegistry`"
Domain schema reference	A contract's optional pointer to a LinkML schema, written `name:version` (e.g. `trading-domain:1.0.0`). Field name on a contract: `domain_schema`.	"Source ontology" (when on the contract), "Schema ref"
LinkML binding	A field binding whose target is a LinkML class/slot pair (instead of, or in addition to, a concept). Carries `linkml_slot: {class, slot}` + `linkml_schema_ref: "name:version"`.	"Source ontology" (when on a binding), "Slot binding"

Pillar terms¶

Canonical	Definition	Retired synonyms
Pipeline	An ETL run definition. Steps (extract / transform / load) plus settings.	"ETL job", "Flow"
Pipeline run	A single execution of a pipeline. Has a `run_id` and a lifecycle row in `pipeline_runs`.	"Pipeline invocation"
Contract	A data-contract artifact: identity + `json_schema` + coercion rules + validation rules + metadata + (optional) `field_bindings` + (optional) `domain_schema`.	"Data contract spec", "Schema contract"
Contract field	A single named field declared in a contract's JSON schema. Addressed by JSONPath (`$.order_id`).	"Property"

Things that look similar but are different¶

These pairs read alike. Mixing them is the source of most historical confusion. Always disambiguate.

A	B	The distinction
Concept scheme	LinkML schema	Both are "schemas" in casual speech. A concept scheme is a collection of governed terms (meaning). A LinkML schema is a collection of class/slot declarations (shape). They are orthogonal: a contract can use either, both, or neither.
Binding	Concept annotation	A binding is an authoring artifact (in a contract YAML, or a row in `resource_bindings`). A concept annotation is the runtime sidecar on a record that records which bindings fired during validation.
Suggestion	Concept	A suggestion is unaccepted candidate vocabulary; it lives in the governance queue. A concept is an accepted entry; it lives in the registry. Suggestions never get extraction-stamped into the registry directly.
Extraction	Ingestion	Extraction takes unstructured sources (records, code, docs) and emits concept suggestions. Ingestion takes structured artifacts (DDL, OpenAPI, an existing concept-scheme YAML) and emits concepts or bindings into the registry. Different IRs, different code paths, different tables.
Vocabulary	Document knowledge base	The vocabulary is pycharter's pillar (governed concepts + bindings). A document knowledge base (chunks + embeddings + index) is the RAG/synthesis layer that lives in pyintake. Do not call the vocabulary a "knowledge base".

Forbidden words¶

These words exist in the language but must not appear in pycharter code or new docs because they are exhausted. If you reach for one, pick a canonical name above instead.

"Ontology" — historically meant four different things in pycharter (the concept registry, a LinkML schema, the directory grouping, and a deprecated alias for field_bindings). In new code: deleted. The only place "linkml_schema" appears is in inert prose where the term is unavoidable (e.g. literature references). It is not a package name, model name, field name, file name, route tag, or template name.
"Knowledge base" / "KB" — historically conflated pycharter's governed-vocabulary layer with a RAG / document-search layer. The latter is now document_kb (and is bound for pyintake per CR-2). The former is vocabulary. The bare term "KB" is reserved for the document-kb sense only.
"Field mapping" — replaced by field binding everywhere. The DB file db/models/field_mapping.py is renamed to field_bindings.py. The rule-dict helper to_field_mapping (which never had anything to do with bindings) is renamed to to_rules_dict.
"Semantic" (as a noun / pillar) — too vague. The semantic/ package directory stays as a code-organisation neutral, but it is not a pillar name in product-facing language.

Package layout (post-rename)¶

The runtime layout reflects the vocabulary:

src/pycharter/
├── pipeline_generator/        # Pillar 1
├── contract_parser/           # Pillar 2
├── contract_builder/          # Pillar 2
├── contract_store/            # Pillar 2
├── semantic/                  # Code home for Pillar 3 internals
│   ├── concepts/              # Concept registry, scheme, relationships, search, graph
│   │                          # (← merges semantic/ontology + knowledge + concept_graph)
│   ├── bindings/              # Generic ResourceBinding (DG-1) + field-binding specialisation
│   ├── linkml/                # LinkML schema loader + registry (shape, not meaning)
│   ├── contracts/             # Contract-side wiring (validate_linkml_bindings, etc.)
│   ├── extraction/            # Records / code / docs → suggestions
│   ├── ingestion/             # Structured artifacts → concepts / bindings
│   ├── governance/            # SHACL governance
│   ├── document_kb/           # Vector / RAG / chunks. Bound for pyintake hand-off (CR-2).
│   │                          # (← renamed from semantic/knowledge_base)
│   └── …
└── …

Public API surface uses the pillar names directly:

pycharter.Pipeline, pycharter.run, pycharter.preflight (Pillar 1)
pycharter.Contract, pycharter.parse_contract, pycharter.build_contract (Pillar 2)
pycharter.Concept, pycharter.ConceptScheme, pycharter.Binding, pycharter.FieldBinding (Pillar 3)

There is no pycharter.ontology, no pycharter.kb, no pycharter.knowledge_base.

Filesystem layout (data/)¶

src/pycharter/data/
├── samples/
│   └── linkml/                # LinkML schema samples (was templates/ontology/trading_domain.yaml)
│       └── trading_domain.yaml
├── seed/
│   ├── concept_schemes.yaml          (← ontologies.yaml)
│   ├── concept_relationships.yaml    (unchanged)
│   ├── vocabulary_metaschema.yaml    (← vocabulary_metaschema.yaml)
│   ├── demo_field_bindings.yaml      (← ontology_mappings.yaml)
│   └── …
├── templates/
│   ├── contract/                     (unchanged — covers all 6 contract template files)
│   ├── concept_schemes/              (← templates/ontology/, minus trading_domain.yaml)
│   │   ├── ecommerce.yaml
│   │   ├── healthcare.yaml
│   │   └── …
│   └── pipeline/                     (unchanged)
└── vocabulary/                       (← vocabulary_shapes/; SHACL shapes removed SEM-1)
    └── versions/                     (LinkML schema registry)

Field / symbol renames¶

The breaking renames shipped as T1–T11 (see the git history of BACKLOG.md). The most consequential:

Old	New
`KBPolicy` (class)	`ExtractionPolicy`
`kb_policy` (field on contracts/steps)	`extraction_policy`
`kb_sink` (param, var)	`extraction_sink`
`KBSinkFactory` (type alias)	`ExtractionSinkFactory`
`kb_scheme` (CLI flag, API body)	`concept_scheme`
`_kb_annotations` (record sidecar key)	`_concept_annotations`
`OntologyImporter`	`ConceptSchemeImporter`
`OntologyVersionRegistry`	`LinkMLSchemaRegistry`
`source_ontology` (field on PrimaryBinding)	`concept_scheme` when binding to a concept; `linkml_schema_ref` when binding to a LinkML slot
`target_ontology` (binding-projection column)	`concept_scheme` / `linkml_schema_ref` (matching the binding target)
`to_field_mapping` (rule-dict converter)	`to_rules_dict`

The accepted contract YAML still uses field_bindings: as the top-level key; field_mapping: and ontology: as deprecated input keys are deleted, and the parser raises on them.

Code review checklist (terminology gate)¶

Before merging any PR, scan the diff for:

No new use of "linkml_schema", "knowledge base", "KB", "field mapping", "semantic layer (as pillar)" outside the forbidden-words allowlist (inert prose only).
No new symbol named kb_*, KB*, or *_kb_*.
Field bindings in YAML use concept_scheme: (for concept targets) or linkml_schema_ref: (for LinkML targets), not source_ontology:.
Record sidecars use the key _concept_annotations, never _kb_annotations.
New docs reference the three pillars (Pipeline / Contract / Vocabulary) when introducing the product.

What this doc does not do¶

It does not change the contract YAML structure beyond the field/key renames above. JSON Schema stays JSON Schema. Coercion / validation rules are unchanged.
It does not change DG-1's ResourceBinding state machine.
It does not move concept extraction or vector ingestion across the pyintake boundary. That's CR-2 / CR-3 territory.
It does not introduce a new file format for any artifact.

Glossary cheat sheet (for skim-readers)¶

Pipeline moves data. Contract declares what data looks like. Vocabulary declares what data means.

A Concept is one entry in a Concept Scheme. A Field Binding links a contract field to a concept. A LinkML Schema declares shape; a Concept Scheme declares meaning. They are independent. A Concept Annotation is the runtime sidecar a pipeline writes on a record. An Extraction Policy governs whether and how a pipeline emits concept suggestions. A Suggestion is an unaccepted candidate concept in the governance queue.