Forgeplane template input schemas

A published Forgeplane template version can carry a JSON Schema input contract. Forgeplane validates run inputs against that versioned snapshot at run admission, before worker preparation. This keeps required fields, defaults, constraints, and secret markers explicit instead of hiding them in worker-specific code.

Root contract

The root schema must be an object. Use properties for named inputs and required for fields that must be present when a run is admitted.

{
  "type": "object",
  "properties": {
    "region": {
      "type": "string",
      "description": "Deployment region",
      "default": "eu-central-1",
      "pattern": "^[a-z]{2}-[a-z]+-[0-9]+$"
    },
    "replicas": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "default": 2
    },
    "labels": {
      "type": "object",
      "additionalProperties": { "type": "string" }
    },
    "deploy_token": {
      "type": "string",
      "x-forgeplane-secret": true
    }
  },
  "required": ["region"]
}

Guided or raw authoring

Use the guided editor for an object root and common top-level fields:

• string, number, integer, boolean, object, and array;
• default values and required fields;
• x-forgeplane-secret catalog-bound secret slots;
• pattern, minLength, and maxLength;
• minimum and maximum; and
• minItems and maxItems.

Use the raw JSON editor for nested objects, conditional schemas, composition keywords, or other advanced JSON Schema. If the guided editor finds keywords it cannot represent, it asks before simplifying the schema. Do not replace an advanced schema with a simplified form unless that loss is intentional.

Defaults and validation

default is a suggestion for forms and API clients, not server-side input hydration. Some UI forms prefill it; direct API callers must send required values or supply them through environment inputs. In the example above, omitting region is rejected despite its default, and omitting replicas does not insert 2.

The coordinator merges environment inputs with run inputs (run values take precedence) and validates that context at admission, before pre-run resolvers execute. Required fields and numeric, string, array, and pattern constraints are checked at this boundary.

The schema belongs to the published template version. Later edits to a draft or a newer version do not rewrite the input contract or historical run context of an existing run.

Sensitive fields

Set x-forgeplane-secret: true on a direct top-level input property that must be supplied through the secret catalog. The guided editor’s Bind through secret catalog option emits this marker. Slot declarations at the root, in nested objects, array items, or conditional branches are rejected; ordinary nested input schemas remain valid.

Sensitivity and secret binding are separate. The boolean flags sensitive, secret, writeOnly, x-sensitive, x-secret, and x-forgeplane-secret control redaction. Only x-forgeplane-secret: true declares a slot and rejects inline values. writeOnly and x-secret are redaction-only annotations. Non-boolean flags are rejected rather than converted.

Use the raw editor for redaction-only annotations. Guided editing blocks annotations it cannot preserve until you explicitly simplify the schema.

The coordinator validates the binding and materializes the secret payload only for the scheduled run. Do not put plaintext secret values in template defaults or instance inputs.

See Secret management for logical secret sources and binding scopes.

Connections and resolvers

Connections are separate from the input schema. Declare connection-dependent behavior in the template version’s pre-run resolver specification, then bind a saved project connection at the environment or run boundary.

A resolver can derive an input or generate a file during worker preparation, after admission. It does not change the JSON Schema contract and cannot satisfy a required field missing at admission.

Authoring checklist

Before publishing a template version:

1. Keep the root schema an object.
2. Mark operationally required fields in required.
3. Add defaults only where the default is safe for every caller.
4. Use constraints that match the tool’s actual accepted values.
5. Mark catalog-bound credentials with x-forgeplane-secret: true on a top-level input property; do not substitute a redaction-only annotation.
6. Use the raw editor when the guided editor cannot represent the schema without loss.
7. Test the resulting template through the normal run operations flow.