| name | build-target-contract-schema |
| description | Build a KlumAST authoring Schema for an authoritative external contract. Use when an adopter is replacing or simplifying Helm values, another configuration document, or a target-specific API contract while keeping that contract authoritative. |
Build a target-contract Schema
Use the documentation for the KlumAST version being adopted as the authority. This workflow creates a convenient authoring layer for one external target; it does not define a universal import/export format.
- Collect two or more representative target artifacts and name the target, its owning team, supported versions, and the values that are intentionally stable. For Helm, retain the chart name/version and values files. Treat the target contract—not its incidental YAML formatting—as authoritative.
- Identify the repeated concepts, defaults, validity rules, and awkward combinations in those artifacts. Propose a small authoring vocabulary that reduces real repetition. Do not mechanically copy every map, list, or spelling from YAML into classes.
- Decide independently whether the project is direct-schema or Layer 3. Choose direct-schema when the Schema Developer also owns the consumer-facing types and no separate stable Domain API is needed. Choose Layer 3 only when clients must compile against a distinct Domain API; do not introduce it for hypothetical flexibility. Record the rationale in the project README or architecture note.
- Create
@DSL Schema types that express the chosen authoring vocabulary. Add meaningful defaults, validation, and at least one higher-level convenience only where it reduces a demonstrated target-contract burden. Keep generated Builders inside one root construction lifecycle.
- Implement a narrow renderer or adapter that maps completed models to the target contract. The adapter may intentionally expand one authoring concept into several target fields. It must make every non-obvious mapping visible in tests or documentation.
- Add representative configured models and generate target artifacts from them. Compare the generated artifacts semantically with golden target-contract files; keep the golden files human-readable. Do not make byte ordering, YAML formatting, Klum metadata, or a YAML/KlumAST round trip the compatibility promise.
- Keep current capabilities separate from future migration conveniences. Resource-backed defaults remain #79; ordered base/override composition remains #304. If the target cannot be expressed without one, record a focused follow-up rather than broadening this onboarding workflow.
- Run the fixture's normal Gradle test with the chosen Groovy line, then exercise its supported Groovy 4 and 5 variants before handoff. Refresh generated source mirrors only when IntelliJ completion is useful; they are not build inputs.
The executable Helm target-contract fixture demonstrates the direct-schema decision, two service values contracts, defaults, validation, a convenience mapping, and semantic golden-file checks. Follow Target Contract Modeling for the task-oriented explanation, and use the field-test starting artifact when applying this preview to a real project.
