80 lines
2.5 KiB
Markdown
80 lines
2.5 KiB
Markdown
# JSON Document Contract
|
|
|
|
The API stores configuration documents as JSON strings, but treats them as typed contracts.
|
|
Workers can convert those documents to ordered PowerShell hashtables for DSC v2, while future DSC v3 renderers can consume JSON directly.
|
|
|
|
## Template Document
|
|
|
|
Template documents are versioned through `TemplateVersionModel.JsonData`.
|
|
Every stored template version must be a JSON object with this shape:
|
|
|
|
```json
|
|
{
|
|
"schemaVersion": "1.0",
|
|
"templateType": "Service",
|
|
"parameters": {},
|
|
"variables": {},
|
|
"resources": {}
|
|
}
|
|
```
|
|
|
|
Required fields:
|
|
|
|
- `schemaVersion`: Contract version. Currently supported: `1.0`.
|
|
- `templateType`: One of `Environment`, `Domain`, `Landscape`, `Service`, `Stage`, or `Deployment`.
|
|
- `parameters`: Object with user-facing inputs and metadata.
|
|
- `variables`: Object with derived values and expressions.
|
|
- `resources`: Object with configuration blocks that can be merged and rendered.
|
|
|
|
Template documents are normalized and validated before a `TemplateVersion` is persisted.
|
|
The API calculates `JsonHash` from the normalized document and stores the effective `SchemaVersion`.
|
|
|
|
## Deployment Override Document
|
|
|
|
Deployment override documents are stored on deployment executions and queue jobs.
|
|
They are currently intentionally permissive so legacy requests like this remain valid:
|
|
|
|
```json
|
|
{
|
|
"role": "WebFrontEnd"
|
|
}
|
|
```
|
|
|
|
The canonical shape for new deployments should be:
|
|
|
|
```json
|
|
{
|
|
"schemaVersion": "1.0",
|
|
"parameters": {},
|
|
"variables": {},
|
|
"resources": {},
|
|
"targets": []
|
|
}
|
|
```
|
|
|
|
Step 4 will make this stricter when deployments can reference multiple immutable template versions.
|
|
|
|
## Metadata Documents
|
|
|
|
Fields such as `MetadataJson` and `RuleSnapshotJson` are metadata documents.
|
|
They must be valid JSON objects when explicitly validated, but they do not need the full template contract.
|
|
|
|
## Validation Rules
|
|
|
|
- The root value must be a JSON object.
|
|
- Template documents must contain the required fields listed above.
|
|
- Unsupported `schemaVersion` values are rejected.
|
|
- Unsupported `templateType` values are rejected.
|
|
- If a client submits `SchemaVersion` for a template version, it must match the document's `schemaVersion`.
|
|
|
|
## Queryable Fields
|
|
|
|
For now, the API projects these fields into columns:
|
|
|
|
- `TemplateVersion.SchemaVersion`
|
|
- `TemplateVersion.JsonHash`
|
|
- `TemplateVersion.Version`
|
|
- `TemplateVersion.IsPublished`
|
|
|
|
Additional document fields should only become relational columns when the GUI or worker needs filtering, sorting, or joins over that field.
|