Scenes, Policies and GuardrailSpecs#
A field-by-field YAML guide, complete example and common validation mistakes are in the GuardrailSpec YAML reference.
A Scene has a stable key, a configurable Run TTL and an optional default Policy.
A Scene can contain multiple Policies. Each Policy has at most one mutable Draft
Revision, immutable published Revisions and one active Revision. Revisions are identified across
services by policyRevisionId; the number is only for display. See
core concepts for the shared terminology.
Initialize a Scene#
Use the management page or an administrator CLI session. Run commands from the checkout or archive root; see Getting started for login and credential setup.
guardrailctl scene apply --key recovery --name Recovery \
--spec ./examples/policies/recovery.yaml --publish
The first application validates the YAML and atomically creates the Scene,
default Policy, Revision 1 and activation. A new Scene requires --publish.
A repeat with the same content reuses the active Revision. An existing Scene can
have its default Policy Draft saved without --publish.
Administrators can also call POST /api/v1alpha1/scenes/{key}:initialize with
name, defaultPolicyName, yaml and Idempotency-Key. The same key and request
return the original resources; a changed request or a separately initialized
Scene returns a conflict.
Edit and publish#
For the default Policy, the management page saves Draft YAML with last-write-wins
semantics. Publishing requires the exact YAML the caller reviewed. The application
first validates and canonicalizes that YAML before acquiring database write locks.
The storage transaction then compares the reviewed YAML with the current Draft
under the Policy lock, assigns the next number and marks that same Draft Revision
as PUBLISHED with its audit record. Repeated saves update one DRAFT row; drafts
have no revision number or publication metadata. After publication, saving again
creates a new Draft with a new business ID. Published content is immutable.
When no Draft exists, the console shows the active policy read-only with a No draft yet notice. Edit a copy of this version opens an editable local copy; Save draft persists it without changing the active version. An existing Draft, including an intentionally empty one, opens directly for editing. If the active policy cannot be read, the console offers a reload action before allowing a copy to be edited.
Invalid reviewed YAML fails validation with 422 SPEC_VALIDATION_FAILED before
the Draft-state comparison. For a valid new publication, a Draft replaced by
another session returns 409 RESOURCE_STATE_CONFLICT without creating or
activating a Revision. Reload and review the new content before publishing again.
An exact idempotent retry returns its original Revision as described below.
Activation remains a separate request. The management page offers publication and
activation in one flow, while the API keeps them independent. Direct publication
with POST /api/v1alpha1/policies/{policyId}/revisions is for a trusted producer
and does not modify the human Draft. It creates a published Revision directly.
Policy responses contain metadata and the active Revision pointer. Read the
editable Revision with GET /api/v1alpha1/policies/{policyId}/draft; no draft
returns 404 NOT_FOUND. Saving returns that DRAFT Revision, including its
identity, YAML and edit metadata. Publication-only fields are absent until it is
published. Policy responses do not contain rule content or draft fields.
Revision history and Run selection include only published Revisions; a direct
management lookup by Revision ID can read either state. See the
persistence model for the schema.
GET /api/v1alpha1/policies/{policyId}/draft: read the current Draft Revision.PUT /api/v1alpha1/policies/{policyId}/draft: save YAML, including an incomplete Draft, and return the Draft Revision.POST /api/v1alpha1/policies/{policyId}/draft:publish: send{"yaml":"<reviewed Draft YAML>"}withIdempotency-Keyto validate and publish that exact Draft. An exact retry returns its original Revision even if the Draft has since changed; reusing the key with different YAML conflicts.POST /api/v1alpha1/policies/{policyId}/revisions: publish complete YAML directly withIdempotency-Key.PUT /api/v1alpha1/policies/{policyId}/active-revision: activate a Revision usingexpectedActiveRevisionIdfor compare-and-swap.PUT /api/v1alpha1/scenes/{key}/default-policy: select an active Policy withexpectedDefaultPolicyId.PATCH /api/v1alpha1/scenes/{key}: changerunTtlSecondsfor future Runs only.
A Policy can be archived and restored, but the default Policy must be changed before archiving it. Published Revisions and existing Runs remain intact. Archived Policies cannot be edited, published, activated or used to create Runs. An existing Draft remains readable while its Policy is archived. Archiving does not delete or publish the Draft; restoring the Policy allows editing and publication of that same Draft again.
GuardrailSpec YAML uses apiVersion: guardrail.open/v1alpha1 and
kind: GuardrailSpec. The parser rejects duplicate keys, anchors, aliases, unknown
fields and invalid constraints. The file limit is 64 KiB.
spec.validForSeconds controls the final Decision's validity; the Scene's
runTtlSeconds controls the Run deadline. See the
OpenAPI contract and
Run lifecycle.
Read published history#
GET /api/v1alpha1/policies/{policyId}/revisions?pageSize=20 returns
{"items": [...], "nextBefore": 123}. Items contain revision identity, number,
digest and publication metadata, without YAML. The default page size is 20 and
the maximum is 100. For the next page, pass before=<nextBefore>; this exclusive
revision-number cursor keeps older pages stable when new revisions are published.
When nextBefore is absent, there are no more older items. The console offers
newer/older page controls and fetches YAML only for the selected version using
GET /api/v1alpha1/policy-revisions/{revisionId}.
Validity range and canonical identity#
spec.validForSeconds accepts a base-10 integer from 1 through 9007199254740991
(2^53 - 1), inclusive. Omitting the field still supplies 3600 before computing
the canonical JSON and SHA-256 digest. This is an interoperability bound, not a
configurable business-duration cap: existing values such as 7200 remain valid.
This fixed schema has only one numeric field. Restricting it to IEEE 754 safe integers preserves the same exact number and decimal JSON spelling in Go and ECMAScript implementations of RFC 8785. Larger integers are rejected rather than rounded; strings, fractions, exponents and non-decimal YAML spellings are rejected as well. Canonical bytes and digests for already supported in-range Specs do not change. The same bound applies when resolving validity from a stored canonical Spec. An existing out-of-range Revision is not rewritten; publish a corrected Revision before creating new Runs from it.
Reference: RFC 8785 Sections 3.1 and 3.2.2.3.