dtcs 0.1.0

Reference implementation of the Data Transformation Contract Standard (DTCS)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

# DTCS — Data Transformation Contract Standard

Vendor-neutral specification and reference implementation for expressing the semantics of data transformations.

**Status:** Draft  
**Specification version:** 1.0.0-draft  
**Document `dtcsVersion`:** `1.0.0` (accepted by the reference validator for compatible 1.0.x releases)

## Overview

[SPEC.md](https://github.com/dtcs/dtcs/blob/main/SPEC.md) is the authoritative normative specification for DTCS. It defines transformation contracts, the canonical object model, validation, diagnostics, conformance, and governance — without prescribing execution engines, storage, or orchestration.

This repository contains:

| Path | Purpose |
|------|---------|
| [SPEC.md](https://github.com/dtcs/dtcs/blob/main/SPEC.md) | Full DTCS 1.0 draft specification (26 chapters) |
| [docs/](https://github.com/dtcs/dtcs/tree/main/docs) | Documentation index |
| [docs/editorial/](https://github.com/dtcs/dtcs/tree/main/docs/editorial) | Authoring standards, style guide, and review process |
| [docs/implementation/](https://github.com/dtcs/dtcs/tree/main/docs/implementation) | Rust reference implementation design and build guides |
| [src/](https://github.com/dtcs/dtcs/tree/main/src) | Rust crate source (`dtcs`) |
| [python/](https://github.com/dtcs/dtcs/tree/main/python) | Python package source (`dtcs` on PyPI) |
| [examples/](https://github.com/dtcs/dtcs/tree/main/examples) | Sample DTCS transformation contracts |
| [tests/](https://github.com/dtcs/dtcs/tree/main/tests) | Integration tests and fixtures |
| [.github/workflows/](https://github.com/dtcs/dtcs/tree/main/.github/workflows) | CI pipeline |

## Quick start

### Read the specification

```bash
less SPEC.md
```

### Build the Rust crate

```bash
cargo build
cargo test
cargo run -- validate examples/customer_normalize.dtcs.yaml
cargo run -- inspect examples/customer_normalize.dtcs.yaml
```

### Use the Python package

```bash
pip install maturin
maturin develop --features python
python -m dtcs validate examples/customer_normalize.dtcs.yaml
python -m dtcs inspect examples/customer_normalize.dtcs.yaml
pytest python/tests -v
```

```python
import dtcs

report = dtcs.parse_and_validate(open("examples/customer_normalize.dtcs.yaml", "rb").read())
assert dtcs.is_valid(report)
```

The first implementation milestone is:

```text
DTCS Document → Parser → Canonical Object Model → Validator → Diagnostics
```

Execution, backend compilation, and runtime behavior are out of scope for the initial crate. See [docs/implementation/non-goals.md](https://github.com/dtcs/dtcs/blob/main/docs/implementation/non-goals.md).

## Repository layout

```text
dtcs/
├── SPEC.md                 # Normative specification (source of truth)
├── Cargo.toml              # Rust crate manifest
├── pyproject.toml          # Python package manifest (maturin)
├── Cargo.lock              # Pinned dependencies (binary crate)
├── README.md
├── CONTRIBUTING.md
├── LICENSE
├── .github/workflows/      # CI
├── docs/
│   ├── README.md           # Documentation index
│   ├── editorial/          # Specification authoring process
│   └── implementation/     # Reference implementation guides
├── examples/               # Example transformation contracts
├── python/                 # Python package source
├── src/                    # Rust library, CLI binary, validation
├── tests/                  # Integration tests and fixtures
└── .cursor/prompts/        # Cursor build prompt
```

## Contributing

See [CONTRIBUTING.md](https://github.com/dtcs/dtcs/blob/main/CONTRIBUTING.md) for editorial conventions, implementation guidelines, and the review process.

When implementation guidance conflicts with the specification, **SPEC.md wins**. See [docs/implementation/spec-usage.md](https://github.com/dtcs/dtcs/blob/main/docs/implementation/spec-usage.md).

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/dtcs/dtcs/blob/main/LICENSE).