Files

T

Jon Chery 3562f6f771 docs(P36): schemas/adapters/pipelines READMEs (REQ-97, REQ-98, REQ-99)

---ci---
project: acdl
phase: 36
milestone: v1.8
status: execute
---/ci---

- schemas/README.md: how to write schemas, wire into platform, test in
  CI, dependencies, existing catalog, adding a new schema.
- pipelines/README.md: how to write pipeline contracts, wire into
  workflows, test, dependencies, existing catalog, adding a new pipeline.
- adapters/README.md: how to write adapters (Terraform + policy patterns),
  wire into platform, test, dependencies, existing catalog, adding a new
  adapter.
- tests/test_docs_coverage.py: 6 tests validating all 3 READMEs exist
  with required sections.

Tests: +6 (344 -> 350). All pass.

2026-07-22 22:22:18 +00:00

.gitkeep

phase: 6, status: plan-as-execute, persona: lead-developer, task: T-6.1..T-6.4

2026-07-21 18:27:21 +00:00

contract.schema.json

feat(P32): deletion-protection-by-default + L2 feature flag (REQ-86, REQ-87)

2026-07-22 22:12:42 +00:00

deploy-pipeline.schema.json

review(v1.5): READY TO SHIP — multi-persona code review

2026-07-22 17:24:28 +00:00

pipeline.schema.json

feat(P19): central pipeline contract + shell reproducibility + output streaming (v1.4.1)

2026-07-22 15:10:54 +00:00

policy_check_result.schema.json

feat(P23): tagging standard + Wiz adapter + Kyverno adapter

2026-07-22 20:00:46 +00:00

README.md

docs(P36): schemas/adapters/pipelines READMEs (REQ-97, REQ-98, REQ-99)

2026-07-22 22:22:18 +00:00

stack.schema.json

feat(P32): deletion-protection-by-default + L2 feature flag (REQ-86, REQ-87)

2026-07-22 22:12:42 +00:00

tagging-standard.json

verify(P22-27): code review — 1 P0 auto-fixed, 2 P1 security fixes, 2 P2 nits

2026-07-22 21:09:52 +00:00

README.md

ACDL Schemas

Overview

ACDL uses JSON Schema draft 2020-12 for all declarative contracts. Schemas are the single source of truth for validation. Every contract, stack instance, pipeline, and policy result in the platform is validated against a schema in this directory before it is consumed by any downstream code path. The resolver, the pipeline runner, the CI workflows, and the test suite all load these schemas directly.

Existing Schemas

Schema	File	Purpose	Where Validated
ACDL Consumer Contract	`contract.schema.json`	Consumer contract validation (module, environment, inputs, `uses` reference)	`core/contract_resolver.py`, `scripts/run_platform.sh` Step 1, CI `schema-validation` job
ACDL Target Stack	`stack.schema.json`	Target Stack instance validation (resources, relationships, composition tree, NFRs)	`core/contract_resolver.py` (post-resolution), `tests/conftest.py`
ACDL Central Pipeline Contract	`pipeline.schema.json`	Central CI pipeline contract (stages, commands, triggers, runner)	`tests/test_pipeline_contract.py`
ACDL Central Deployment Pipeline Contract	`deploy-pipeline.schema.json`	Central deploy pipeline contract (validate → resolve → plan → checkov → confidence → apply → publish → uptime → comment)	`tests/test_pipeline_contract.py`
ACDL PolicyCheckResult	`policy_check_result.schema.json`	Normalized policy check result schema (the contract between policy engines and the confidence signal)	`tests/conftest.py`, all adapter tests
ACDL Tagging Standard	`tagging-standard.json`	Required tag set for all taggable AWS resources	`adapters/terraform/policy/custom_rules/acdl_tagging.py`

How to Write a Schema

Use JSON Schema draft 2020-12: "$schema": "https://json-schema.org/draft/2020-12/schema".
Set $id to https://acdl.cloudinit.dev/schemas/<name>.schema.json.
Include title and description at the document root.
Set type: object at the document root.
Declare a required array listing the mandatory top-level property names.
Define properties with explicit type, pattern, enum, and description for every field.
Use $defs for reusable sub-schemas (e.g. resource definitions, input maps) and $ref them from the main document.

How to Wire a Schema into the Platform

Contract validation — load the schema in core/contract_resolver.py and in scripts/run_platform.sh Step 1 (validate-contract).
Stack validation — load the schema in core/contract_resolver.py after the contract is resolved to a stack instance.
Pipeline validation — load the schema in tests/test_pipeline_contract.py, which validates pipelines/ci.yaml and pipelines/deploy.yaml.
Module interface validation — structural checks in .github/workflows/platform-test.yml (schema-validation job) that validate each module's interface.json / composition.json.
Policy result validation — the schema is loaded as a fixture in tests/conftest.py and reused by every adapter test to validate emitted PolicyCheckResult records.

Dependencies

jsonschema (Python) — installed via requirements-test.txt.
pyyaml — for YAML contract loading (core/contract_resolver.py, scripts/run_platform.sh, tests).

How to Test Schemas in CI

tests/test_pipeline_contract.py — validates the pipeline schemas and asserts workflow conformance (byte-identical Gitea/GitHub workflows, same stages/commands/triggers).
tests/conftest.py — provides stack_schema and policy_check_result_schema fixtures for reuse across the test suite.
.github/workflows/platform-test.yml schema-validation job — self-validates every schema in schemas/ (each schema is loaded and meta-validated), validates module interfaces, and validates example contracts.

Where to Write Tests

tests/test_<schema_name>.py for schema-specific tests (e.g. tests/test_contract_schema.py).
Extend tests/test_pipeline_contract.py for pipeline-schema changes.
Module interface validation lives in the CI workflow (.github/workflows/platform-test.yml).

Adding a New Schema

Create schemas/<name>.schema.json using the draft 2020-12 conventions above.
Add it to the CI validation glob in .github/workflows/platform-test.yml (schema-validation job).
Write a test in tests/test_<name>.py that loads the schema and validates representative valid/invalid documents.
Wire it into the consuming code path (resolver, script, or test) so it is enforced at runtime.