dtcs 0.2.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
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# 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  
**Reference implementation:** 0.2.0 (Phase 0.2 — Contract Model)  
**Document `dtcsVersion`:** `1.0.0` (accepted by the reference validator for compatible 1.0.x releases)

See [ROADMAP.md](ROADMAP.md) for milestone status and [CHANGELOG.md](CHANGELOG.md) for release notes.

## Overview

[SPEC.md](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](SPEC.md) | Full DTCS 1.0 draft specification (26 chapters) |
| [docs/](docs/) | Documentation index |
| [docs/editorial/](docs/editorial/) | Authoring standards, style guide, and review process |
| [docs/implementation/](docs/implementation/) | Rust reference implementation design and build guides |
| [src/](src/) | Rust crate source (`dtcs`) |
| [python/](python/) | Python package source (`dtcs` on PyPI) |
| [examples/](examples/) | Sample DTCS transformation contracts |
| [tests/](tests/) | Integration tests and fixtures |
| [ROADMAP.md](ROADMAP.md) | Reference implementation milestones |
| [.github/workflows/](.github/workflows/) | CI pipeline |

## Install

Published packages (after tagging `v0.2.0`):

```bash
cargo install dtcs --version 0.2.0
pip install dtcs==0.2.0
```

Both installs provide a `dtcs` CLI on `PATH` (`validate`, `inspect`, `diagnostics`, `version`).

The current PyPI/crates.io release is `0.1.2` until `v0.2.0` is tagged. See [CONTRIBUTING.md](CONTRIBUTING.md#releasing) for the release workflow.

## 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 reference implementation through Phase 0.2 implements:

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

Phase 0.2 adds metadata validation, extended type system checks (conversions, collections, extension types), expression typing, and I/O interface depth (optional inputs, streaming, pre/postconditions).

Execution, backend compilation, and runtime behavior remain out of scope. See [docs/implementation/non-goals.md](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)
├── CHANGELOG.md            # Release notes
├── 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](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](docs/implementation/spec-usage.md).

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).