Data Contracts¶

Data Contracts are formal agreements between data producers and consumers specifying schema, quality expectations, SLA commitments, and evolution rules.

Contract Structure¶

record DataContract(
    String datasetName,
    String owner,
    Object schema,                          // Schema definition
    List<QualityExpectation> qualityExpectations,
    List<SLACommitment> slaCommitments,
    CompatibilityMode evolutionRules,       // BACKWARD, FORWARD, FULL, NONE
    SemanticVersion version
) { }

Capability Contract¶

public interface DataContractContract extends BaseProviderContract {
    DataContract generateContract(Pipeline pipeline, Object outputSchema);
    ValidationResult validateContract(DataContract contract);
    PublishResult publishContract(DataContract contract, SemanticVersion version);
    CompatibilityResult checkCompatibility(DataContract existing, DataContract proposed);
    void deprecateContract(String contractId, SemanticVersion version);
}

Lifecycle¶

graph LR
    A[Generate] --> B[Validate]
    B --> C[Publish]
    C --> D[Active]
    D --> E{Change?}
    E -->|Compatible| F[New Version]
    E -->|Breaking| G[Deprecate + New Contract]
    F --> D

Generating Contracts¶

DataContract contract = contractProvider.generateContract(pipeline, outputSchema);
// Auto-generates quality expectations from pipeline quality stages
// Auto-generates SLA commitments from pipeline timeout configurations

Compatibility Checking¶

Before publishing a new version:

CompatibilityResult result = contractProvider.checkCompatibility(
    existingContract, proposedContract
);
// result: "compatible", "backward-compatible", or "breaking"

Evolution Rules¶

Mode	Allowed Changes
`BACKWARD`	Add optional fields, widen types
`FORWARD`	Remove optional fields, narrow types
`FULL`	Only changes that are both backward and forward compatible
`NONE`	Any change allowed (no compatibility enforcement)

Versioning¶

Contracts use semantic versioning:

record SemanticVersion(int major, int minor, int patch) { }

Major — Breaking changes
Minor — Backward-compatible additions
Patch — Bug fixes, documentation updates

Querying via Echo¶

// Current contract
DataContractVersion current = echo.queryContract("customer-orders");

// Full history
List<DataContractVersion> history = echo.queryContractHistory("customer-orders");

Integration Points¶

Component	Role
Pipeline Definition Model	Declares output schema
Data Quality Capability	Enforces quality expectations
Schema Registry	Manages schema versions
Echo Service	Tracks contract history
Documentation Engine	Generates contract documentation