# datacontract/datacontract-cli architecture

> Architecture diagram of the GitHub repository datacontract/datacontract-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/datacontract/datacontract-cli
- Repository: https://github.com/datacontract/datacontract-cli

## Overview

#### Purpose and Entry Points
Python package and CLI for authoring, validating, testing, comparing, importing, and exporting data contracts, with native Open Data Contract Standard (ODCS) support. Primary CLI dispatch is `datacontract/cli.py`; command implementations are split into `datacontract/command_test.py`, `datacontract/command_import.py`, and `datacontract/command_export.py`. The reusable Python API centers on `datacontract/data_contract.py`; an optional HTTP/API runtime is represented by `datacontract/api.py`.

#### Canonical Contract Model and Validation
Contracts are YAML/JSON documents resolved into the internal contract representation and validated against bundled versioned schemas. `datacontract/data_contract.py` is the orchestration boundary for loading and operating on a contract. Schema definitions and initialization templates live in `datacontract/schemas/datacontract-1.2.1.schema.json` and `datacontract/schemas/odcs-3.2.0.schema.json`. Linting resolves references, variables, resources, URLs, and schema constraints before execution through `datacontract/lint/resolve.py` and `datacontract/lint/schema.py`.

#### Test Execution Pipeline
`test` converts contract schema, service-level, and quality declarations into executable checks, runs them against a selected server, and emits a `Run` result. Check construction and shared semantics are concentrated in `datacontract/engines/checks/create_checks.py`, while orchestration is in `datacontract/engines/data_contract_test.py`. Output is deliberately separated from execution, supporting console, CI, JSON, and JUnit consumers via `datacontract/output/ci_output.py` and `datacontract/output/test_results_writer.py`.

#### Data-Source Engine Boundary
Engine adapters isolate contract-level checks from physical systems and type/connection differences. Ibis is the broad execution layer, with connection selection in `datacontract/engines/ibis/connections/connect.py` and query/check execution in `datacontract/engines/ibis/ibis_check_execute.py`. Specialized paths cover SAP HANA (`datacontract/engines/hana/hana_quality_check.py`), JSON Schema validation (`datacontract/engines/fastjsonschema/check_jsonschema.py`), and file/server preconditions under `datacontract/engines/datacontract/`. Supported infrastructure includes SQL warehouses/databases, DuckDB/local files, S3/GCS/Azure object storage, Iceberg, Kafka, and API endpoints; optional Python extras supply connectors.

#### Format Translation Layer
Importers ingest source schemas or artifacts into the canonical contract form, selected through `datacontract/imports/importer_factory.py`; representative adapters include `datacontract/imports/sql_importer.py` and `datacontract/imports/bigquery_importer.py`. Exporters project the canonical model to downstream formats through `datacontract/export/exporter_factory.py`, including SQL (`datacontract/export/sql_exporter.py`), JSON Schema, dbt, Avro, HTML, and Excel. This factory-based boundary is the main extensibility point for formats.

#### Change Governance and Integrations
Contract versions are normalized, diffed, and evaluated for backward compatibility through `datacontract/changelog/changelog.py` and `datacontract/breaking/detector.py`; CLI commands expose changelog and breaking gates for CI. dbt synchronization/test mapping is implemented under `datacontract/integration/dbt_sync.py`. Catalog and publish capabilities are separately surfaced by `datacontract/catalog/catalog.py` and `datacontract/command_publish.py`, keeping remote governance workflows outside core validation.

#### Delivery Runtimes
The package targets Python 3.10–3.12 and is distributable as a CLI/library or Docker image (`Dockerfile`). CI, release automation, and static documentation delivery are GitHub Actions-based (`.github/workflows/ci.yaml`, `.github/workflows/release.yaml`, `.github/workflows/azure-static-web-apps-docs.yml`). Documentation is a separate Docusaurus/Node runtime rooted at `docs/docusaurus.config.ts`, while the packaged local editor UI is static assets under `datacontract/editor_assets/index.html`.

Main entry points: [`datacontract/data_contract.py`](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/data_contract.py) (DataContract API), [`datacontract/command_test.py`](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/command_test.py) (Test/import/export commands), [`datacontract/engines/data_contract_test.py`](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/engines/data_contract_test.py) (Test orchestrator), [`datacontract/engines/ibis/ibis_check_execute.py`](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/engines/ibis/ibis_check_execute.py) (Engine adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI dispatcher<br/>Python CLI<br/>[cli.py]"]
  node_commands["Test/import/export commands<br/>CLI commands<br/>[command_test.py]"]
  node_api["Optional HTTP API<br/>Python API runtime<br/>[api.py]"]
end

subgraph group_core["Contract core"]
  node_contract["DataContract API<br/>contract orchestration<br/>[data_contract.py]"]
  node_documents["Contract documents<br/>YAML / JSON"]
  node_resolver["Lint resolver<br/>reference resolution<br/>[resolve.py]"]
  node_schema_validation["Schema validation<br/>contract validation<br/>[schema.py]"]
  node_schemas["Versioned schemas<br/>bundled JSON Schema"]
end

subgraph group_testing["Test execution"]
  node_test_orchestrator["Test orchestrator<br/>test pipeline"]
  node_check_factory["Check construction<br/>check factory<br/>[create_checks.py]"]
  node_engine_boundary["Engine adapters<br/>execution boundary"]
  node_connections["Ibis connections<br/>connection selection<br/>[connect.py]"]
  node_specialized_engines["Specialized validators"]
  node_data_sources[("Data sources<br/>warehouses, files, streams, APIs")]
  node_test_output["Result outputs"]
end

subgraph group_translation["Translation &amp; governance"]
  node_import_factory["Importer factory<br/>format extension point"]
  node_export_factory["Exporter factory<br/>format extension point"]
  node_governance["Change governance<br/>[changelog.py]"]
  node_catalog_publish["Catalog &amp; publish<br/>remote governance<br/>[catalog.py]"]
  node_dbt["dbt integration<br/>sync and test mapping<br/>[dbt_sync.py]"]
end

subgraph group_delivery["Delivery runtimes"]
  node_package_runtime{{"Python package &amp; Docker<br/>distribution runtime"}}
  node_docs_editor["Docs &amp; local editor"]
end

node_cli -->|"dispatches"| node_commands
node_cli -->|"operates on"| node_contract
node_api -->|"uses"| node_contract
node_commands -->|"test"| node_test_orchestrator
node_commands -->|"import"| node_import_factory
node_commands -->|"export"| node_export_factory
node_commands -->|"changelog / breaking gates"| node_governance
node_documents -->|"loads into"| node_contract
node_contract -->|"lints"| node_resolver
node_resolver -->|"resolved contract"| node_schema_validation
node_schema_validation -->|"validates against"| node_schemas
node_contract -->|"executes tests"| node_test_orchestrator
node_test_orchestrator -->|"builds checks"| node_check_factory
node_check_factory -->|"executable checks"| node_engine_boundary
node_engine_boundary -->|"selects connection"| node_connections
node_connections -->|"connects to"| node_data_sources
node_engine_boundary -->|"queries and checks"| node_data_sources
node_test_orchestrator -->|"routes specialized checks"| node_specialized_engines
node_specialized_engines -->|"validates"| node_data_sources
node_test_orchestrator -->|"emits Run results"| node_test_output
node_import_factory -->|"creates canonical form"| node_contract
node_contract -->|"projects model"| node_export_factory
node_contract -->|"compares versions"| node_governance
node_contract -->|"synchronizes"| node_dbt
node_contract -->|"publishes"| node_catalog_publish
node_package_runtime -->|"ships"| node_cli
node_docs_editor -.->|"documents packaged tooling"| node_package_runtime

click node_cli "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/cli.py"
click node_commands "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/command_test.py"
click node_api "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/api.py"
click node_contract "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/data_contract.py"
click node_resolver "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/lint/resolve.py"
click node_schema_validation "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/lint/schema.py"
click node_schemas "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/schemas/datacontract-1.2.1.schema.json"
click node_test_orchestrator "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/engines/data_contract_test.py"
click node_check_factory "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/engines/checks/create_checks.py"
click node_engine_boundary "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/engines/ibis/ibis_check_execute.py"
click node_connections "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/engines/ibis/connections/connect.py"
click node_specialized_engines "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/engines/hana/hana_quality_check.py"
click node_test_output "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/output/test_results_writer.py"
click node_import_factory "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/imports/importer_factory.py"
click node_export_factory "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/export/exporter_factory.py"
click node_governance "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/changelog/changelog.py"
click node_catalog_publish "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/catalog/catalog.py"
click node_dbt "https://github.com/datacontract/datacontract-cli/blob/main/datacontract/integration/dbt_sync.py"
click node_package_runtime "https://github.com/datacontract/datacontract-cli/blob/main/Dockerfile"
click node_docs_editor "https://github.com/datacontract/datacontract-cli/blob/main/docs/docusaurus.config.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_commands,node_api toneBlue
class node_contract,node_documents,node_resolver,node_schema_validation,node_schemas toneAmber
class node_test_orchestrator,node_check_factory,node_engine_boundary,node_connections,node_specialized_engines,node_data_sources,node_test_output toneMint
class node_import_factory,node_export_factory,node_governance,node_catalog_publish,node_dbt toneRose
class node_package_runtime,node_docs_editor toneIndigo
```

## Components

### Entry points

- [CLI dispatcher](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/cli.py): Python CLI · `datacontract/cli.py`
- [Test/import/export commands](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/command_test.py): CLI commands · `datacontract/command_test.py`
- [Optional HTTP API](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/api.py): Python API runtime · `datacontract/api.py`

### Contract core

- [DataContract API](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/data_contract.py): contract orchestration · Loads and operates on canonical contracts. · `datacontract/data_contract.py`
- **Contract documents**: YAML / JSON · Author-provided data contracts.
- [Lint resolver](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/lint/resolve.py): reference resolution · `datacontract/lint/resolve.py`
- [Schema validation](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/lint/schema.py): contract validation · `datacontract/lint/schema.py`
- [Versioned schemas](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/schemas/datacontract-1.2.1.schema.json): bundled JSON Schema · `datacontract/schemas/datacontract-1.2.1.schema.json`

### Test execution

- [Test orchestrator](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/engines/data_contract_test.py): test pipeline · Produces a Run result from a contract and target. · `datacontract/engines/data_contract_test.py`
- [Check construction](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/engines/checks/create_checks.py): check factory · `datacontract/engines/checks/create_checks.py`
- [Engine adapters](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/engines/ibis/ibis_check_execute.py): execution boundary · Isolates contract checks from source-specific connections and types. · `datacontract/engines/ibis/ibis_check_execute.py`
- [Ibis connections](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/engines/ibis/connections/connect.py): connection selection · `datacontract/engines/ibis/connections/connect.py`
- [Specialized validators](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/engines/hana/hana_quality_check.py): HANA / JSON / preconditions · `datacontract/engines/hana/hana_quality_check.py`
- **Data sources**: warehouses, files, streams, APIs · Connector extras support databases, object stores, Kafka, Iceberg, and endpoints.
- [Result outputs](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/output/test_results_writer.py): console / CI / JSON / JUnit · `datacontract/output/test_results_writer.py`

### Translation & governance

- [Importer factory](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/imports/importer_factory.py): format extension point · `datacontract/imports/importer_factory.py`
- [Exporter factory](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/export/exporter_factory.py): format extension point · `datacontract/export/exporter_factory.py`
- [Change governance](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/changelog/changelog.py): version diff & breaking checks · `datacontract/changelog/changelog.py`
- [Catalog & publish](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/catalog/catalog.py): remote governance · `datacontract/catalog/catalog.py`
- [dbt integration](https://github.com/datacontract/datacontract-cli/blob/main/datacontract/integration/dbt_sync.py): sync and test mapping · `datacontract/integration/dbt_sync.py`

### Delivery runtimes

- [Python package & Docker](https://github.com/datacontract/datacontract-cli/blob/main/Dockerfile): distribution runtime · `Dockerfile`
- [Docs & local editor](https://github.com/datacontract/datacontract-cli/blob/main/docs/docusaurus.config.ts): Node docs and static UI · `docs/docusaurus.config.ts`

## Connections

- CLI dispatcher → Test/import/export commands: dispatches
- CLI dispatcher → DataContract API: operates on
- Optional HTTP API → DataContract API: uses
- Test/import/export commands → Test orchestrator: test
- Test/import/export commands → Importer factory: import
- Test/import/export commands → Exporter factory: export
- Test/import/export commands → Change governance: changelog / breaking gates
- Contract documents → DataContract API: loads into
- DataContract API → Lint resolver: lints
- Lint resolver → Schema validation: resolved contract
- Schema validation → Versioned schemas: validates against
- DataContract API → Test orchestrator: executes tests
- Test orchestrator → Check construction: builds checks
- Check construction → Engine adapters: executable checks
- Engine adapters → Ibis connections: selects connection
- Ibis connections → Data sources: connects to
- Engine adapters → Data sources: queries and checks
- Test orchestrator → Specialized validators: routes specialized checks
- Specialized validators → Data sources: validates
- Test orchestrator → Result outputs: emits Run results
- Importer factory → DataContract API: creates canonical form
- DataContract API → Exporter factory: projects model
- DataContract API → Change governance: compares versions
- DataContract API → dbt integration: synchronizes
- DataContract API → Catalog & publish: publishes
- Python package & Docker → CLI dispatcher: ships
- Docs & local editor → Python package & Docker: documents packaged tooling
