GuardrailSpec YAML reference#
简体中文 | English
A GuardrailSpec describes the checks and evidence required for one kind of operation. It is a YAML policy document, not an executable rule language. An external Agent or integration observes the real system, submits a verdict and evidence for every Check, and the OpenGuardrail service validates the submission against the frozen Spec. The service does not independently attest that an observation is true. The execution tool must verify the authoritative decision, accepted evidence and current operation before acting. See core concepts and Runs and submissions.
This reference describes guardrail.open/v1alpha1. The OpenAPI
contract and Spec validator
define the accepted fields and constraints for this checkout.
A complete example#
This example is valid as written and can be copied into file-cleanup.yaml:
apiVersion: guardrail.open/v1alpha1
kind: GuardrailSpec
metadata:
name: file-cleanup
spec:
description: Check a proposed cleanup of temporary files
instructions: Inspect the exact files and submit current observations for every check.
validForSeconds: 60
checks:
- id: temporary-only
displayName: Temporary files only
description: Protect business files from deletion
instructions: Confirm that every target is an existing temporary file in the intended workspace.
criteria:
pass: Every target is an existing temporary file in the intended workspace
block: At least one target is a protected business file
unknown: Target identity or current file state cannot be verified
evidenceRequirements:
- id: files
description: Workspace identity, exact targets and observed file metadata
appliesToVerdicts: [PASS, BLOCKED, UNKNOWN]
The policy text alone does not inspect files or delete them. The file cleanup demo supplies those integrations and a two-Check Spec. The smaller Recovery Spec is another complete example.
Fields#
All fields below are case-sensitive. Fields marked required must be present. Text fields must contain a non-whitespace character; lengths count Unicode characters. Unknown fields are rejected.
| Path | Required | Meaning and constraints |
|---|---|---|
apiVersion |
Yes | Exactly guardrail.open/v1alpha1. |
kind |
Yes | Exactly GuardrailSpec. |
metadata.name |
Yes | Spec identifier. Use 1–63 lowercase letters, digits or hyphens; start with a letter and end with a letter or digit. |
spec.description |
Yes | Purpose of the Spec; at most 1,024 characters. |
spec.instructions |
Yes | Instructions for the evaluator; at most 8,000 characters. |
spec.validForSeconds |
No | Lifetime in seconds of a terminal Decision. It starts when the Run finishes (FINISHED) or at the logical deadline if the Run expires (EXPIRED). Positive base-10 integer from 1 to 9007199254740991; default 3600. Write it without quotes or leading zeros. |
spec.checks |
Yes | Array of 1–20 Checks. Check IDs must be unique within the Spec. |
spec.checks[].id |
Yes | Check identifier, following the same format as metadata.name. |
spec.checks[].displayName |
Yes | Human-readable Check name; at most 128 characters. |
spec.checks[].description |
Yes | What the Check covers; at most 1,024 characters. |
spec.checks[].instructions |
Yes | How the evaluator should investigate this Check; at most 8,000 characters. |
spec.checks[].criteria.pass |
Yes | When this Check can report PASS; at most 2,048 characters. |
spec.checks[].criteria.block |
Yes | When this Check must report BLOCKED; at most 2,048 characters. |
spec.checks[].criteria.unknown |
Yes | When this Check cannot be verified and must report UNKNOWN; at most 2,048 characters. |
spec.checks[].evidenceRequirements |
Yes | Array of 1–20 requirements. Requirement IDs must be unique within their Check. |
spec.checks[].evidenceRequirements[].id |
Yes | Requirement identifier, following the same format as metadata.name. |
spec.checks[].evidenceRequirements[].description |
Yes | What observation this requirement expects; at most 1,024 characters. |
spec.checks[].evidenceRequirements[].appliesToVerdicts |
Yes | Nonempty, unique subset of [PASS, BLOCKED, UNKNOWN]. Evidence for this requirement is accepted only for the listed Check verdicts and required when one of those verdicts is submitted. |
The identifier pattern is ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$.
criteria describes how an evaluator should classify observations; it is not
code evaluated by the service. A final Submission includes every Check and its
applicable evidence. The service aggregates Check verdicts: all PASS means
PASS / ALLOW; any BLOCKED means BLOCKED / DENY; otherwise an UNKNOWN
means UNKNOWN / DENY. See Run evaluation for the submission format.
YAML and Scene boundaries#
- The file must contain one UTF-8 YAML document of at most 64 KiB, 4,096 nodes
and nesting depth 16. Duplicate keys, anchors, aliases, custom tags, unknown
fields and implicit scalar coercions are rejected. Except for
spec.validForSeconds, scalar values must be YAML strings. Quote values that YAML could interpret as a boolean or number. sceneKey,runTtlSeconds, Project keys and the operation'schangeSetare not GuardrailSpec fields. A Scene has its own stable key and Run TTL;spec.validForSecondsinstead controls how long a terminal Decision remains valid. The caller supplieschangeSetwhen creating each Run.- A published Revision is immutable. Publication validates and canonicalizes the YAML, assigning a content digest. A Run freezes the selected Revision and digest. Comments and formatting are not policy checks.
Publish and use it#
With a running service and an administrator CLI session, publish the file from the checkout root:
guardrailctl scene apply --key file-cleanup --name 'File cleanup' \
--spec ./file-cleanup.yaml --publish
The first application creates the Scene, its default Policy and an active Revision. Repeating an unchanged publication reuses that Revision. Publishing changes service state; use an isolated service while experimenting. An orchestrator Project key can create and read Runs but cannot publish the Spec. See Scenes and Specs for Draft review, activation and credentials, and Getting started for a complete local flow.
Common mistakes#
| Input | Why it fails or misleads | Correct approach |
|---|---|---|
sceneKey or runTtlSeconds inside the YAML |
They are Scene settings, not Spec fields. | Select the Scene with scene apply --key; configure its Run TTL separately. |
requirement: SQL must have WHERE as a Check field |
requirement is not in the schema. |
Supply description, instructions, all three criteria values and evidenceRequirements. |
criteria says PASS without evidence |
Criteria text does not run checks or prove observations. | Collect evidence in an external integration and submit it for the applicable verdict. |
validForSeconds: "300" or validForSeconds: 0300 |
The only numeric field must be an unquoted positive base-10 integer without leading zeros. | Use validForSeconds: 300. |
Treating ALLOW as permission to execute any later action |
Decisions are tied to a Run, frozen context and validity window. | Re-read the authoritative Run and accepted Submission; verify identity, evidence and current state at the execution boundary. |