Jon Chery
38b51f3e6d
regression/ policies (3): cap-013-adapter-dedup, cap-023-metrics-collector, cap-024-deck-structure — declarative mirrors of core/regression_verify.py over capability-inventory JSON. The imperative regression_verify.py is kept (drives CI gate); the policies are the declarative mirror (IDEATE I1 quality improvement). tests: test_regression_policies.py + clean/drifted fixtures. Skip-without-kj. docs: adapters/README.md (new kyverno-json row + PolicyEngine Protocol section with how-to-add-OpaEngine), adapters/kyverno-json/README.md (engine, install, policy directory layout, 4 categories, severity convention), schemas/README.md (D-116 engine enum reuse note), modules/STANDARDS.md §10 Policy Authoring Standard, docs/METRICS.md (swappable engine narrative). ---ci--- project: acdl phase: 4 milestone: v1.25 status: execute phase_role: execution requirements: covered: [REQ-304, REQ-305, REQ-306, REQ-307] partial: [] ---/ci---
66 lines
4.9 KiB
Markdown
66 lines
4.9 KiB
Markdown
# Nova Schemas
|
|
|
|
## Overview
|
|
|
|
Nova 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 |
|
|
| --- | --- | --- | --- |
|
|
| Nova Consumer Contract | `contract.schema.json` | Consumer contract validation (id, name, environment, infrastructure map with module versions + inputs) | `core/contract_resolver.py`, `scripts/run_platform.sh` Step 1, CI `schema-validation` job |
|
|
| Nova Target Stack | `stack.schema.json` | Target Stack instance validation (resources, relationships, composition tree, NFRs) | `core/contract_resolver.py` (post-resolution), `tests/conftest.py` |
|
|
| Nova Central Pipeline Contract | `pipeline.schema.json` | Central CI pipeline contract (stages, commands, triggers, runner) | `tests/test_pipeline_contract.py` |
|
|
| Nova 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` |
|
|
| Nova 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 |
|
|
| Nova Tagging Standard | `tagging-standard.json` | Required tag set for all taggable AWS resources | `adapters/terraform/policy/custom_rules/nova_tagging.py` |
|
|
|
|
> **v1.25 note (D-116):** the `engine` enum value `"kyverno"` is shared
|
|
> by the K8s-only Kyverno adapter (`adapters/kyverno/`) and the
|
|
> kyverno-json engine (`adapters/kyverno-json/`). The two are
|
|
> distinguished by `ruleId` prefix (`KYVERNO_` for the K8s adapter,
|
|
> `KJ_` for kyverno-json) and `evidence` payload shape. No new enum
|
|
> value was added — the `engine` field records the policy-engine
|
|
> family, not the specific binary.
|
|
|
|
## How to Write a Schema
|
|
|
|
1. Use JSON Schema draft 2020-12: `"$schema": "https://json-schema.org/draft/2020-12/schema"`.
|
|
2. Set `$id` to `https://nova.cloudinit.dev/schemas/<name>.schema.json`.
|
|
3. Include `title` and `description` at the document root.
|
|
4. Set `type: object` at the document root.
|
|
5. Declare a `required` array listing the mandatory top-level property names.
|
|
6. Define `properties` with explicit `type`, `pattern`, `enum`, and `description` for every field.
|
|
7. 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.yml` and `pipelines/contract.yml`.
|
|
- **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 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
|
|
|
|
1. Create `schemas/<name>.schema.json` using the draft 2020-12 conventions above.
|
|
2. Add it to the CI validation glob in `.github/workflows/platform-test.yml` (`schema-validation` job).
|
|
3. Write a test in `tests/test_<name>.py` that loads the schema and validates representative valid/invalid documents.
|
|
4. Wire it into the consuming code path (resolver, script, or test) so it is enforced at runtime. |