Registry /
serialization / open-data-contract-standard
Install & Compatibility
Where this runs
tested against v3.1.2 · 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.
OpenDataContractStandard
✓ from open_data_contract_standard.model import OpenDataContractStandard
The main Pydantic model for the data contract.
This quickstart demonstrates how to load an Open Data Contract Standard (ODCS) specification from a string using the `OpenDataContractStandard` Pydantic model and then print it back as a YAML string. It includes comments for how to load from a file, which requires an existing YAML file.
from open_data_contract_standard.model import OpenDataContractStandard
# Example 1: Load a data contract specification from a string
data_contract_str = """
version: 1.0.0
kind: DataContract
id: 53581432-6c55-4ba2-a65f-72344a91553b
status: active
name: my_table
apiVersion: v3.1.0
"""
data_contract_from_string = OpenDataContractStandard.from_string(data_contract_str)
print("--- Data Contract from string ---")
print(data_contract_from_string.to_yaml())
# Example 2: To load from a file, you would use from_file
# Ensure 'data_contract.yaml' exists in the same directory
# with valid ODCS content for this to run without error.
# import os
# file_path = 'data_contract.yaml'
# with open(file_path, 'w') as f:
# f.write(data_contract_str)
# data_contract_from_file = OpenDataContractStandard.from_file(file_path)
# print("\n--- Data Contract from file ---")
# print(data_contract_from_file.to_yaml())
# os.remove(file_path) # Clean up file
datacontract --version
Debug
Known issues
gotchaThe pip module version mirrors the major and minor versions of the Open Data Contract Standard (ODCS) it supports, but specifically does NOT mirror the patch version. For instance, ODCS v3.1.0 might correspond to pip module versions >=3.1.0 but not necessarily 3.1.0 exactly.fixAlways check the PyPI page or GitHub README for the exact version mapping between the pip module and the ODCS specification version it implements.
affects: All versions
breakingMigration from ODCS v2.x to v3.x involved significant breaking changes in the standard's schema, which the `open-data-contract-standard` Python library (v3.x and above) enforces. Key changes include renaming `uuid` to `id`, `columns` to `properties`, and changing the `team` (formerly `stakeholders`) structure from an array to an object.fixReview the ODCS v3.0.0 changelog for a comprehensive list of breaking changes. Update your data contract YAML files to conform to the ODCS v3.x specification.
affects: 3.x.x (when processing v2.x ODCS contracts)
breakingODCS v3.1.0 introduced stricter JSON Schema validation, disallowing additional or undefined properties in certain sections of the contract. While v3.1.0 was declared backward compatible with v3.0.x, contracts that previously contained extra, undefined fields (and were thus valid under a looser schema) will now fail validation.fixEnsure your data contracts strictly adhere to the ODCS v3.1.0 (or later) JSON Schema, removing any properties not explicitly defined in the standard. Review the ODCS v3.1.0 release notes for details on stricter validation.
affects: 3.1.0 and later
deprecatedIn ODCS v3.1.0, `slaDefaultElement` and the top-level `dataProduct` fields were deprecated. While still functional, they will generate warnings and are slated for removal in future major versions (e.g., ODCS v4).fixAvoid using `slaDefaultElement` and the top-level `dataProduct`. Consult the latest ODCS documentation for recommended alternatives or replacements.
affects: 3.1.0 and later
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'open_data_contract_standard'
The Python interpreter cannot find the installed `open-data-contract-standard` library, likely due to it not being installed, an incorrect environment, or a wrong import statement.
fixEnsure the library is installed using `pip install open-data-contract-standard` and that you are importing it correctly, e.g., `from open_data_contract_standard.model import OpenDataContractStandard`.
ValidationError: 1 validation error for OpenDataContractStandard
__root__
Field required [type=missing, input_value={'some_invalid_data':...}, input_type=dict]
The YAML file or data provided to the `OpenDataContractStandard` model is missing one or more required top-level fields (e.g., 'apiVersion', 'kind', 'id', 'name', 'version', 'status') as defined by the Open Data Contract Standard schema and enforced by Pydantic.
fixReview your data contract YAML file to ensure all mandatory fields according to the Open Data Contract Standard (ODCS) specification are present and correctly structured. Refer to the ODCS documentation or examples for the expected schema.
yaml.YAMLError: while parsing a block mapping
in "<string>", line X, column Y
expected <block end>, but found '<scalar>'
The input YAML string or file is malformed, typically due to incorrect indentation, missing colons, or other syntax errors, preventing the `PyYAML` parser (used by the library) from correctly loading the data.
fixCarefully check the YAML file for syntax errors, paying close attention to indentation, colons, and valid YAML structure around the indicated line and column. Use a YAML linter or editor with YAML validation to identify and correct the syntax issues.
ValidationError: 1 validation error for OpenDataContractStandard
__root__ -> schema -> 0 -> properties -> 0 -> logicalType
Input should be a valid string [type=string_type, input_value=123, input_type=int]
A field within the data contract, such as `logicalType` in the schema's properties, has been provided with an incorrect data type (e.g., an integer where a string is expected), violating the Pydantic model's type constraints.
fixCorrect the data type of the problematic field in your YAML contract. For instance, if `logicalType` is expected to be a string like 'string' or 'integer', ensure it is enclosed in quotes and not provided as a number. Review the ODCS schema for the correct types of each field.
Upgrade
Version history
3.1.2latest on PyPI · released Dec 17, 2025
Audit
Dependencies
pydanticrequiredCore library functionality is built upon Pydantic models for data validation and serialization.