dtcs 0.12.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

# Troubleshooting

Common problems when installing, running, or authoring DTCS contracts.

## Installation

### `pip install dtcs` tries to compile from source

Pre-built wheels are published for common platforms and Python 3.9–3.13. If pip falls back to a source build:

1. Ensure you are on a supported Python version.
2. Install Rust 1.75+ and [maturin](https://www.maturin.rs/).
3. Or pin a released version: `pip install dtcs==0.12.0`.

See [faq.md](faq.md#pip-install-dtcs-fails-to-build-what-do-i-do).

### `dtcs: command not found` after pip install

The `dtcs` CLI should be on your PATH after `pip install dtcs`. If not:

```bash
python -m dtcs version
```

Add your Python scripts directory to `PATH`, or use `python -m dtcs` in scripts and CI.

### `cargo install dtcs` is slow

`cargo install` compiles from source. This is normal on first install. Subsequent updates reuse the cargo cache.

## Path and working directory

### Example commands fail with "file not found"

Most repository examples assume you run commands from the **repository root**:

```bash
dtcs validate examples/minimal.dtcs.yaml
# or: examples/customer_pipeline.dtcs.yaml
```

If you are in the `examples/` directory, adjust paths or return to the repo root. See [examples/README.md](https://github.com/eddiethedean/dtcs/blob/main/examples/README.md).

### `dtcs run --input` file not found

The `--input` path is relative to your current working directory. Clone the repository or provide an absolute path to your input JSON.

Pip-only installs do not include `examples/` or `tests/fixtures/`. Use the curlable sample in [getting-started.md](getting-started.md), clone the repository, or author your own files.

## Validation errors

Run diagnostics for structured output:

```bash
dtcs diagnostics my_contract.yaml
dtcs diagnostics my_contract.yaml --json
```

| Diagnostic | Likely cause | Fix |
|------------|--------------|-----|
| `dtcs:unsupported-version` | `dtcsVersion` not in the supported set | Set `dtcsVersion: "2.0.0"` (preferred) or `"1.0.0"` / `"1.0.0-draft"` (patch variants like `1.0.1` / `2.0.1` are rejected) |
| `dtcs:missing-lineage` | Output without lineage mapping | Add `lineage.mappings` entry for each output |
| `dtcs:unresolved-reference` | Field path does not exist | Use `interface.field` format matching an input/output `id` |
| `dtcs:invalid-type` | Malformed type expression | Use `list<string>`, not bare `list` |
| `dtcs:unknown-registry-entry` | Unrecognized `dtcs:` identifier | Run `dtcs registry list`; use embedded stdlib identifiers |
| `dtcs:invalid-semantic-action` | Dataset action missing `parameters`, or bad target | See [Appendix A](../SPEC.md#appendix-a-standard-library-catalog-normative); supply `fields` / join keys / etc. |
| stdlib semantics errors | Wrong target type, nullability, or rule phase | Run `dtcs registry resolve dtcs:IDENTIFIER --json` |

### Unexpected lineage `operation` / `flow` after round-trip

From 0.11.0, omitted lineage `operation` defaults to `dtcs:derive` and `flow` defaults to `derived`. Plan JSON goldens and `dtcs plan --json` may show these fields even when your YAML omitted them. This is intentional.

### Runtime treats missing fields as null

Missing and null are distinct. Inspect JSON for `{"$dtcs":"missing"}` vs `null`. Use `dtcs:is_missing` / `dtcs:is_null` in expressions. See [faq.md](faq.md#what-are-null-vs-missing-vs-invalid-values) and [expressions.md](expressions.md#null-missing-and-invalid).

See [writing-contracts.md](writing-contracts.md#validate-as-you-write) for more diagnostic fixes. Upgrading tools: [migration-0.12.md](migration-0.12.md). From 0.10.x to 0.11.x (historical): [migration-0.11.md](migration-0.11.md).

## Analysis and planning

### `dtcs analyze` exits non-zero on a valid contract

`analyze` requires a valid contract **and** no error-severity analysis diagnostics. Warnings may still appear. Run with `--json` to inspect `validation` and `analysis` sections separately.

### `dtcs plan` fails after `validate` succeeds

Planning also requires static analysis to pass. Run `dtcs analyze` first and fix expression or semantics errors.

## Python API

### `KeyError` on `runtime_execute` result

`dtcs.runtime_execute` returns an envelope, not a flat output map:

```python
result = dtcs.runtime_execute(execution_plan, inputs)
outputs = result["outputs"]  # not result["customer_clean"]
```

The CLI `dtcs run --json` emits a flat output map. See [json-output.md](json-output.md#run).

### Contract dict keys rejected

Python contract dicts must use **camelCase** keys (`dtcsVersion`, `semanticActions`), matching the Canonical Object Model. See [json-output.md](json-output.md#python-note).

### `is_valid` on wrong object

`dtcs.is_valid` checks a diagnostic report (`{"diagnostics": [...]}`). For `runtime_execute`, pass the full result or check `result["outputs"]` separately.

## CI integration

See [ci-integration.md](ci-integration.md) for validate/analyze/compat gates with JSON parsing.

## Getting help

- [FAQ](faq.md)
- [GitHub issues](https://github.com/eddiethedean/dtcs/issues) — include `dtcs version`, the command run, and `dtcs diagnostics --json` output
- [SPEC.md](../SPEC.md) for normative behavior