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:

{
  "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:

{
  "role": "WebFrontEnd"
}

The canonical shape for new deployments should be:

{
  "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.

2.5 KiB Raw Blame History