Jon Chery
bee9d02f01
---ci---
project: acdl
phase: 40
milestone: v1.9
status: execute
---/ci---
Phase 40 — contract-interpolation (REQ-103, REQ-104, D-081):
Interpolation:
- core/contract_resolver.py: _expand_vars(value, context) recursively
expands ${env.<field>} + ${contract.<field>} tokens (dotted paths
supported, e.g. ${env.state_backend.bucket}). Unknown tokens raise
ValueError (fail loud). Expansion is post-schema-validation,
pre-IR-resolution.
- resolve() accepts environment_override (D-088) — overrides the
contract's environment field BEFORE schema validation so interpolation
context is consistent.
- env context loaded via _load_env (self-contained, works as script +
package import); 'environment' alias for env 'name' so
${env.environment} resolves.
Environment schema + bindings:
- schemas/environment.schema.json (draft 2020-12): name, account_id,
region, state_backend, network, runner_role_arn, autonomy, confidence_threshold.
- core/environments/qa.json, prod.json, dr.json placeholder bindings
(attested, thresholds 0.75/0.90/0.95, placeholder account_id with
stderr warning at load).
- core/environment_check.py: load(env_name) helper + placeholder warning.
Sample contracts:
- contracts/static-assets.yaml + microservice.yaml use
acdl-${env.environment}-${contract.module}-${env.account_id}-${env.region}
naming pattern (region + account id + environment).
Tests: +35 (test_environment_schema.py, test_interpolation.py,
test_sample_contracts_interpolate.py). 406 passed; run_ci.sh green;
run_platform.sh --check-only green. Existing fixture-based tests
preserved (instance.json static fixtures unaffected).
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
$idtohttps://acdl.cloudinit.dev/schemas/<name>.schema.json. - Include
titleanddescriptionat the document root. - Set
type: objectat the document root. - Declare a
requiredarray listing the mandatory top-level property names. - Define
propertieswith explicittype,pattern,enum, anddescriptionfor every field. - Use
$defsfor reusable sub-schemas (e.g. resource definitions, input maps) and$refthem from the main document.
How to Wire a Schema into the Platform
- Contract validation — load the schema in
core/contract_resolver.pyand inscripts/run_platform.shStep 1 (validate-contract). - Stack validation — load the schema in
core/contract_resolver.pyafter the contract is resolved to a stack instance. - Pipeline validation — load the schema in
tests/test_pipeline_contract.py, which validatespipelines/ci.yamlandpipelines/deploy.yaml. - Module interface validation — structural checks in
.github/workflows/platform-test.yml(schema-validationjob) that validate each module'sinterface.json/composition.json. - Policy result validation — the schema is loaded as a fixture in
tests/conftest.pyand reused by every adapter test to validate emittedPolicyCheckResultrecords.
Dependencies
jsonschema(Python) — installed viarequirements-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— providesstack_schemaandpolicy_check_result_schemafixtures for reuse across the test suite..github/workflows/platform-test.ymlschema-validationjob — self-validates every schema inschemas/(each schema is loaded and meta-validated), validates module interfaces, and validates example contracts.
Where to Write Tests
tests/test_<schema_name>.pyfor schema-specific tests (e.g.tests/test_contract_schema.py).- Extend
tests/test_pipeline_contract.pyfor pipeline-schema changes. - Module interface validation lives in the CI workflow (
.github/workflows/platform-test.yml).
Adding a New Schema
- Create
schemas/<name>.schema.jsonusing the draft 2020-12 conventions above. - Add it to the CI validation glob in
.github/workflows/platform-test.yml(schema-validationjob). - Write a test in
tests/test_<name>.pythat 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.