Registry /
data / datacontract-specification
Install & Compatibility
Where this runs
tested against v1.2.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DataContractSpecification
✓ from datacontract_specification.model import DataContractSpecification
This quickstart demonstrates how to load a data contract definition from a YAML file using `DataContractSpecification.from_file()` and then access its properties. It creates a temporary YAML file with a basic contract for demonstration purposes.
import os
from datacontract_specification.model import DataContractSpecification
# Create a dummy data contract YAML file for the example
dummy_contract_content = """
dataContractSpecification: 1.2.0
id: urn:datacontract:example:orders-latest
info:
title: Example Orders Latest
version: 1.0.0
description: |
Successful customer orders example.
owner: Example Team
status: active
models:
orders:
type: table
fields:
order_id:
type: string
required: true
description: Unique identifier for the order.
customer_id:
type: string
description: Identifier for the customer.
"""
file_path = "example_datacontract.yaml"
with open(file_path, "w") as f:
f.write(dummy_contract_content)
try:
# Load the data contract from the file
data_contract = DataContractSpecification.from_file(file_path)
print("Data Contract Loaded Successfully:")
print(data_contract.to_yaml())
# Access some properties
print(f"\nContract Title: {data_contract.info.title}")
print(f"Contract Version: {data_contract.info.version}")
except Exception as e:
print(f"An error occurred: {e}")
finally:
# Clean up the dummy file
if os.path.exists(file_path):
os.remove(file_path)
datacontract --version
Debug
Known issues
breakingThe underlying Data Contract Specification, for which this library provides a Pydantic model, is officially deprecated in favor of the Open Data Contract Standard (ODCS) as of ODCS v3.1. Users are recommended to migrate to ODCS.fixMigrate to the Open Data Contract Standard (ODCS). The `datacontract-cli` (the primary consumer of this library) supports ODCS natively. Consider using the `datacontract-cli` for `export --format odcs` functionality if available.
affects: All versions of the library, as it reflects the state of the specification.
gotchaThis `datacontract-specification` library provides only the Pydantic model of the Data Contract Specification. It does *not* include the CLI tools (like `lint`, `test`, `export`, `import`, `breaking`) or direct programmatic interaction with data sources. For command-line functionality and comprehensive data contract enforcement, use the `datacontract-cli` library.fixInstall `datacontract-cli` (`pip install datacontract-cli`) for command-line tools and programmatic interaction with data contracts including schema validation and quality checks against actual data.
affects: All versions
breakingModifying data contract definitions (e.g., changing field types incompatibly, removing required fields, or making optional fields required) is a breaking change that can significantly affect downstream data consumers. Incompatible changes will lead to data pipeline failures and erode trust.fixImplement semantic versioning for data contracts. Prioritize additive, backward-compatible changes. For unavoidable breaking changes, coordinate with consumers, update major versions, and provide clear migration paths. Leverage `datacontract-cli breaking` command to detect such changes in CI/CD pipelines.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'datacontract'
This error occurs when trying to import `datacontract` directly, possibly expecting functionality from the `Data Contract CLI` or trying to access the Pydantic model incorrectly. The core Pydantic model is located in `datacontract_specification.model`, and the CLI features reside in the `datacontract-cli` package.
fixIf you intend to use the Pydantic model for programmatic interaction, import `DataContractSpecification` from `datacontract_specification.model`. If you intend to use the CLI tools or the programmatic interface for testing and linting, you need to install `datacontract-cli` and import from `datacontract.data_contract`.
ValidationError: 'title' is a required property
This is a Pydantic validation error indicating that the YAML data contract file is missing a required field, in this case, the `title` property within the `info` block, which is mandatory according to the Data Contract Specification.
fixEnsure your YAML data contract adheres to the Data Contract Specification. Add the missing `title` property under the `info` block. For example: `info: {title: My Data Contract, version: 1.0.0}`. AttributeError: 'DataContractSpecification' object has no attribute 'test'
This error occurs when you have installed the `datacontract-specification` library (which provides the Pydantic model) and are attempting to call methods like `test()`, `lint()`, or `export()` directly on an instance of `DataContractSpecification`. These methods are part of the `datacontract-cli` library, not `datacontract-specification`.
fixFor CLI functionalities and programmatic interaction with data sources (like testing and linting), you need to install the `datacontract-cli` library (`pip install datacontract-cli`) and use its API, typically by creating a `DataContract` object from `datacontract.data_contract`.
ValidationError: 'str' is not a valid 'type' for field 'my_field'
This Pydantic validation error indicates that an invalid or unrecognized data type string, such as `str`, has been used for a field in the YAML data contract. The Data Contract Specification defines a specific set of supported types.
fixCorrect the data type in your YAML contract to one supported by the Data Contract Specification, such as `string`, `integer`, `decimal`, `timestamp`, or `boolean`. For example, change `type: str` to `type: string`.
Upgrade
Version history
1.2.3latest on PyPI · released Sep 25, 2025
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.
pydanticrequiredThe library is built on Pydantic models for data contract representation.