Configuration Handover with Site-Specific Values: Validate Templates Without Shipping Secrets
Deliver a versioned parameter contract with safe example values, and require a separate deployment validation step before site-specific configuration becomes active. The receiver should know who supplies every value, which omissions are allowed, how unresolved placeholders are rejected and where secrets are provisioned through an approved separate process.
This article concerns handover responsibilities and template validation. It does not describe a storage transaction, credential-provisioning implementation or complete security architecture. No real site values or secrets appear here. The JSON example and proposed checks were not executed.
1. Classify settings by ownership and readiness
| Setting class | Delivery treatment | Deployment responsibility |
|---|---|---|
| Product-owned invariant | Controlled value or derived read-only identity | Verify applicability; do not invent a local override |
| Optional setting with approved default | Document default and omission behavior | Confirm whether the site needs an override |
| Required site-owned value | Clearly incomplete template entry | Named site role supplies and approves it |
| Secret material | Provisioning requirement or permitted reference only | Authorized secure workflow supplies the material |
A default is a product decision, not an arbitrary example that happens to work in a lab. If a setting can redirect data, change a physical operating limit or identify a customer installation, review whether any automatic default is appropriate.
NASA’s transition-preparation guidance, section 5.5.1.2, treats receiving-site needs as part of handover. The ownership matrix here makes one such dependency explicit without assigning contractual obligations to an unnamed party.
2. Separate a template from an activatable instance
A template may deliberately contain missing or null values to show where input is needed. Mark it incomplete and ensure the deployment process does not mistake it for an approved operational configuration.
For example, a fictional template might contain:
{
"schema_revision": "handover-example-1",
"site_id": null,
"display_language": "en",
"credential_reference": null
}The language value is an illustrative default, not a recommendation for every product. The null entries express unresolved inputs in this proposed template format. Whether the credential reference is required depends on the selected feature and the approved provisioning design.
Do not ship a working development password as a placeholder. A secret reference is also not automatically public information: use a non-sensitive logical label in examples and apply the project’s access policy to actual locators.
3. Define more than field presence
With JSON Schema Draft 2020-12, required checks that a property exists. It does not by itself reject null, an empty string or a placeholder. Type and value constraints must express those additional requirements.
For a deployment field that must be a nonempty string, specify its type and minimum length as well as presence. If whitespace-only text or reserved placeholder tokens are invalid, enforce that policy explicitly. A generic nonempty-string check cannot know that “REPLACE_ME” is unresolved.
The same specification places default in its metadata vocabulary. Do not assume a validator inserts missing values. If the application performs default expansion, version and test that separate behavior, including its precedence over supplied settings.
4. Add cross-field and site-semantic checks
Structural validity is only one gate. A syntactically valid site identifier may belong to another installation. A supported mode may require a parameter omitted because an optional feature was disabled in the example.
Document conditional requirements, relationships and authority checks separately. Identify which checks can run offline and which require authorized site context. A validation report should state what was checked rather than calling every schema-valid file ready to operate.
Keep secret-resolution checks separate from logging the resolved value. A report can state that an approved reference was resolved through the intended mechanism without copying credentials into the release archive or diagnostic output.
5. Exercise incomplete-template cases deliberately
| Proposed case | Expected deployment classification |
|---|---|
| Required property absent | Incomplete; identify the missing field and owner |
| Required string is null | Invalid type for the deployment contract |
| Empty or prohibited whitespace-only string | Invalid value under the stated rule |
| Reserved placeholder token | Unresolved input, even if structurally a valid string |
| Unknown schema revision | Unsupported contract; do not guess interpretation |
| Structurally valid but wrong site identity | Site-semantic rejection or review hold |
Include a positive control containing artificial, explicitly permitted test values. A validator that rejects every candidate has not demonstrated useful acceptance behavior. Retain actual results only after running the selected implementation; this table is a proposed fixture set.
6. Preserve the responsibility boundary at handover
For each site-owned field, record its definition, allowed domain, owner, source of truth, validation stage and change procedure. State whether the supplier can verify the value or only verify its shape.
For example, a fictional integration team can confirm that a site identifier follows the approved syntax while the site owner confirms that it names the intended installation. Those are different checks. Neither should silently inherit the other’s authority.
When a required value is unavailable, leave the deployment gate open and name the missing input. Do not fill it with a convenient production-looking value to make a demonstration proceed.
7. Deliver the evidence needed to finish safely
The handover packet should contain the parameter contract, incomplete template, artificial valid example, proposed rejection cases, validator identity and documented activation boundary. Include the approved provisioning procedure reference without embedding its secret material.
After site completion, retain a permitted configuration identity and validation receipt under the applicable access policy. Keep a successful static validation distinct from actual activation and operational verification. The result is a usable division of responsibility without confusing a distributable template, a completed configuration and a fully working installation.
