Documentation/Core concepts

Core concepts#

OpenGuardrail records a policy, evaluation context, assessment and decision for one evaluation. The caller defines the scenario; external evaluators investigate it, and the calling system decides how to use the recorded outcome.

Policy and evaluation records#

Term Meaning
Scene A scenario with a stable key, a Run timeout (runTtlSeconds) and an optional default Policy. A Scene may contain multiple Policies.
Policy Strategy identity, ownership, name, lifecycle and the active Revision pointer within a Scene.
GuardrailSpec The YAML policy document defining instructions, Checks, evidence requirements and decision validity. Its document version is guardrail.open/v1alpha1.
Policy Revision Rule content in DRAFT or PUBLISHED state. One editable Draft is allowed per Policy; publication assigns its number and freezes it. Runs select published Revisions. Publication and activation are separate operations.
Run One independent evaluation. It freezes the Scene, Policy Revision reference, Spec digest, caller-supplied context and Run deadline.
Evaluation context The arbitrary JSON object carried in the API field changeSet. The caller defines its business fields; the service normalizes and records it.
Check One assessment required by the frozen Spec, with a PASS, BLOCKED or UNKNOWN verdict and applicable evidence.
Submission One complete Snapshot of all Checks and their applicable evidence. A Run may accept intermediate Snapshots and one final Snapshot.
Evidence Structured observations attached to a Check: a requirement ID, observation time, query summary, result summary and optional reference.
Result The server-validated aggregate Check verdict: PASS, BLOCKED or UNKNOWN.
Decision The stored ALLOW or DENY outcome derived from the Result, with its own validity window.

The server verifies that a Submission matches its frozen Spec and aggregates the Check verdicts. It does not independently attest that the observations are true. Integrations verify the evidence they rely on before applying a decision.

Run state and time#

A new Run is OPEN. Complete intermediate Submissions advance its baseline number. A final Submission moves it to FINISHED and creates its Result and Decision atomically. An unfinished Run observed at or after its deadline becomes EXPIRED with UNKNOWN / DENY.

Time constraint Source Meaning
Run deadline (deadlineAt) Scene runTtlSeconds, frozen when creating the Run Latest time a new Submission may be accepted. Intermediate Submissions and credential rotation do not extend it.
Decision validity (decisionExpiresAt) Frozen Spec spec.validForSeconds Lifetime of the stored Decision after the terminal outcome. Passing this time does not rewrite historical Run state.

PASS maps to ALLOW; BLOCKED and UNKNOWN map to DENY. A stored ALLOW must still be current and associated with the intended evaluation before a caller uses it. See Runs and submissions for concurrency and retry behavior.

Credentials and responsibilities#

Credential Used by Purpose
Administrator session A trusted human or administrator automation Manage Scenes, Policies, Drafts, activation and Project keys; inspect management views. Browser and CLI sessions are separate.
Project machine key An orchestrator or policy publisher Call only the endpoints granted by its effective scopes within one Project. A default orchestrator can create/read Runs and rotate an open Run's Submission Credential.
Run Submission Credential An external evaluator Submit complete Snapshots to exactly one Run. It cannot create/read Runs, read Policy Revisions or manage Project credentials.

Machine roles are issuance templates; effective scopes authorize each request. Final Submission uses the Run credential, not the Project key. Plaintext keys and Run credentials are returned once and must be stored privately. See the administrator guide for issuance, rotation and revocation.

Current scope and future execution control#

Applying a decision belongs to the calling system. The preview's delivery demos wait for a current authoritative decision and verify persisted evidence before continuing. They are synthetic integration examples.

Execution Claims, ActionResults, evaluator attestation and replaceable identity/provider APIs are planned. The target architecture includes that future scope; the getting-started flow shows the implemented evaluation loop. See the roadmap for remaining work.

Return to the documentation index.