Skip to navigation
Reference

Policy Schemas

View as Markdown

This page lists every field of every document kind a bundle can contain. For the bundle manifest itself, refer to Bundle Specification. For how to write each kind, refer to Author Policies.

Schema Files

The repository publishes a JSON Schema for each authored kind in contracts/jsonschema/.

KindapiVersionSchema file
PolicyBundlenvidia.agent-policy-fabric.policy/v1alpha1policy-bundle.v1alpha1.schema.json
SandboxPolicynvidia.agent-policy-fabric.sandbox/v1alpha1sandbox-policy.v1alpha1.schema.json
Providernvidia.agent-policy-fabric.policy/v1alpha1provider.v1alpha1.schema.json
PolicyRulenvidia.agent-policy-fabric.policy/v1alpha1policy-rule.v1alpha1.schema.json
PolicyAnnotatornvidia.agent-policy-fabric.policy/v1alpha1policy-annotator.v1alpha1.schema.json
PolicyEffectnvidia.agent-policy-fabric.policy/v1alpha1policy-effect.v1alpha1.schema.json
PolicyFindingnvidia.agent-policy-fabric.policy/v1alpha1policy-finding.v1alpha1.schema.json

APF’s services do not load these schemas. They describe the documents for authors and tooling, and the runtime applies its own checks, which differ in places. Validate against the schemas before you sign, as described in Validate and Test Policies, and read Schema and Runtime Differences.

Common Envelope

Every member document has the same four top-level fields.

FieldTypeRequiredDescription
apiVersionstringYesThe kind’s API group and version from the table above. Not checked at runtime.
kindstringYesThe document kind. The loader uses it to route the member. A member with an unknown kind is hash-checked, must still be valid YAML, and is then ignored.
metadata.namestringYesUnique name within the kind. Rules, effects, and findings are referenced by it. A missing or duplicate name rejects the bundle.
metadata.titlestringNoDisplay name. Projected as a provider profile’s display_name.
metadata.descriptionstringNoDescription.
metadata.versionintegerNoAuthor’s own version number. Not used for rollback protection.
specobjectYesThe kind-specific body. Unknown keys in spec are rejected at compile time. Only metadata allows unknown keys.

The schemas forbid metadata.namespace. The runtime accepts it and ignores it.

SandboxPolicy

The sandbox perimeter. APF projects it into OpenShell’s SandboxPolicy and injects it at admission. The projection is served as openshell.sandbox.v1/<metadata.name>.

FieldTypeDescription
spec.filesystem.include_workdirbooleanInclude the sandbox working directory.
spec.filesystem.read_onlystring listPaths the sandbox can read.
spec.filesystem.read_writestring listPaths the sandbox can read and write.
spec.landlock.compatibilitystringLandlock mode. Passed to OpenShell unchanged. OpenShell 0.1.x accepts only best_effort and hard_requirement. The schema lists best_effort, required, and disabled. Use best_effort.
spec.process.run_as_userstringUser the workload runs as.
spec.process.run_as_groupstringGroup the workload runs as.
spec.network_policies.<key>map of network policyEgress allowlist entries. The key names the entry.
spec.network_middlewares.<key>map of middleware entryMiddleware that OpenShell calls for matching hosts. APF’s entry routes traffic to its content policy.

Network Policy Entry

FieldTypeDescription
namestringEntry name. Defaults to the map key.
endpointslist of endpointsDestinations the entry allows.
binaries[].pathstringExecutables allowed to use the entry.
binaries[].harnessbooleanAccepted by the schema and the parser, but not projected.

Network Middleware Entry

FieldTypeDescription
namestringDisplay name.
middlewarestringRegistered middleware name. APF’s is apf-content-policy.
on_errorstringfail_closed or fail_open. Use fail_closed for APF.
orderintegerPosition among middleware. OpenShell runs them in ascending order.
endpoints.includestring listHosts the middleware applies to.
endpoints.excludestring listHosts excluded from it.

There is no config field, because APF’s middleware takes no configuration. The schema allows up to 10 middleware entries and 32 hosts in each list. OpenShell allows 32 include and exclude patterns combined and requires each entry’s order to be unique. APF checks none of these limits.

Network Endpoint

Endpoints are shared by SandboxPolicy network policy entries and Provider documents. Their semantics are OpenShell’s. Refer to the OpenShell policy schema reference for enforcement details.

FieldTypeDescription
hoststringHost name or pattern. Required on provider endpoints.
portintegerPort, 1 to 65535.
portsinteger listSeveral ports. Takes precedence over port.
pathstringHTTP path glob that scopes the endpoint on a shared host and port. It starts with /, or is **.
protocolstringtcp, rest, websocket, graphql, sql, json-rpc, or mcp.
tlsstringOmit it for automatic TLS termination, or set skip. OpenShell 0.1.x rejects terminate and passthrough, which the schema lists, and the schema rejects skip. OpenShell also refuses a fail-closed middleware entry that selects a skip host. On a SandboxPolicy, an unknown value fails the projection. On a Provider, it fails provider profile reconciliation and snapshots.
enforcementstringenforce or audit. When omitted, OpenShell audits violations without blocking them. OpenShell rejects enforce for protocol: sql.
accessstringAccess preset: read-only, read-write, or full.
rules[].allowobjectLayer 7 allow rule. Refer to Layer 7 Rules.
deny_rules[]objectLayer 7 deny rule, with the same fields as an allow rule.
allowed_ipsstring listAllowed resolved addresses.
allow_encoded_slashbooleanAllow %2F in paths.
websocket_credential_rewritebooleanRewrite credentials in WebSocket traffic.
request_body_credential_rewritebooleanRewrite credential placeholders in request bodies.
persisted_queriesstringdeny or allow_registered, for GraphQL.
graphql_persisted_queriesmapRegistered GraphQL operations: operation_type, operation_name, fields.
graphql_max_body_bytesintegerGraphQL body limit.
json_rpc_max_body_bytesintegerJSON-RPC body limit. Defaults to mcp.max_body_bytes when zero.
mcp.max_body_bytesintegerNot projected as its own field. Used as json_rpc_max_body_bytes when that is zero.
mcp.strict_tool_namesbooleanRequire strict MCP tool names.
mcp.allow_all_known_mcp_methodsbooleanAllow every known MCP method.
credential_binding.providerstringAccepted, but never projected. OpenShell receives no binding.
allow_uninspected_credentialsbooleanAccepted, but OpenShell always receives false. The sandbox projection clears it. On a Provider, the profile YAML keeps it, and APF’s interceptor drops it when it converts the profile for OpenShell.

Layer 7 Rules

FieldTypeDescription
methodstringHTTP method.
pathstringPath pattern.
commandstringSQL command.
querymapQuery parameter matchers. A string is a glob. {any: [...]} matches any listed glob.
paramsmapMCP parameter matchers, with the same form as query. OpenShell supports only params.name for tools/call, and rejects params on plain json-rpc endpoints.
operation_typestringGraphQL query, mutation, or subscription. Required on GraphQL rules. The schema also allows *, which OpenShell rejects.
operation_namestringGraphQL operation name.
fieldsstring listGraphQL fields.

The schemas express some of OpenShell’s cross-field endpoint rules, such as requiring access or rules for rest endpoints and forbidding them for tcp. OpenShell enforces more of them at admission. APF does not check these rules, so validate against the schema or rely on OpenShell to reject an invalid policy at admission.

Provider

A provider profile: the endpoints, binaries, and credentials for one external service. APF projects each Provider into an OpenShell provider profile, served as openshell.provider-profile.v1/<metadata.name>, and reconciles it to the OpenShell gateway.

FieldTypeDescription
metadata.namestringBecomes the profile id. OpenShell accepts only lowercase letters and digits in hyphen-separated parts, such as github or nvidia-inference, and APF does not check this. Provider types created on OpenShell must match a bundle-managed profile id.
metadata.titlestringBecomes the profile’s display_name.
spec.typestringCategory. inference, agent, messaging, data, knowledge, and source-control map to OpenShell categories. Any other value becomes other. inference and agent are marked inference-capable.
spec.endpointslist of endpointsDestinations the provider uses. Each needs a host.
spec.binarieslistExecutables, as path strings or {path: ...} objects.
spec.credentialslistCredentials OpenShell injects.

Credential

FieldTypeDescription
namestringCredential name. Defaults to the provider name, so give each credential a name when a provider has more than one.
envVarsstring listEnvironment variables the credential is read from.
stylestringInjection style. The schema allows bearer, header, query, path, basic, and cookie, but OpenShell rejects cookie. An empty value means bearer.
headerstringHeader name. The schema requires it when style is bearer or header. OpenShell also requires it when style is omitted, because APF projects an empty style as bearer.
queryParamstringQuery parameter. The schema requires it for query.
pathTemplatestringPath template. The schema requires it for path.
discoverablebooleanListed for discovery unless set to false.
requiredbooleanWhether the credential is required.
descriptionstringDescription.
source.kindstringHow the credential is obtained. Refer to the table below.

Credential Sources

source.kindFields
host-envname
oauth2grant (client-credentials or refresh-token), tokenUrl, scopes, refreshBeforeSeconds, maxLifetimeSeconds, parameters, additionalOutputs
externalname, tokenUrl, scopes, refreshBeforeSeconds, maxLifetimeSeconds
google-service-account-jwtrefreshBeforeSeconds, maxLifetimeSeconds, material, additionalOutputs
aws-sts-assume-rolerefreshBeforeSeconds, maxLifetimeSeconds, material, additionalOutputs
token-granttokenEndpoint (required at compile time), audience, jwtSvidAudience, scopes, cacheTtlSeconds, audienceOverrides, clientAssertionType

material entries have name, description, required, and secret. additionalOutputs entries have output and credential. For oauth2, each parameters key is projected as a required material entry, marked secret when its name contains secret, token, or key. The parameter values and the name of host-env and external sources are not projected. Refer to Credential Integration.

ProviderProfile

A ProviderProfile member is an OpenShell provider profile in OpenShell’s own YAML format. APF passes it through unchanged as openshell.provider-profile.v1/<metadata.name>. A member without a kind that has a top-level id and endpoints is also treated as a provider profile. There is no APF schema for this kind. A Provider with the same name replaces it.

PolicyRule

FieldTypeRequiredDescription
spec.descriptionstringNoDescription.
spec.languagestringYescedar. Other languages are rejected at compile time.
spec.definitionstringYesCedar policy text.
spec.schemastringNoCedar schema in human-readable syntax. Policies are validated against it when the evaluator is built.
spec.datamappingNoValues exposed to the rule as context.data.
spec.rolestringNocapability or control. Exactly control makes a control rule. Any other value, or none, makes a capability grant.

Cedar Request

ElementValue
PrincipalAPF::User::"<user subject>". The subject is empty on the OpenShell middleware path.
ActionAPF::Action::"<tool>::<capability>" when both are known, APF::Action::"<tool>" for an MCP tool call from OpenShell, and APF::Action::"invoke" for a request that is not a tool call.
ResourceAPF::Tool::"<tool>", or APF::Tool::"__none__".
context.body_textThe request body as text.
context.has_tool_nametrue for an MCP tool call, and for an EvaluationService request that names a resource.
context.target_host, target_method, target_path, target_schemeThe request target, when known.
context.args.<name>MCP tool arguments, or EvaluationService request arguments. For each string argument, APF adds <name>_len with its length in characters, and <name>_num when it parses as an integer.
context.annotationsAnnotator outputs.
context.dataThe rule’s spec.data.

APF Annotations

AnnotationAllowed onEffect
@id("<label>")Any statementNames the statement in deny reasons as <rule>/<label>, or <label> verbatim when it contains /.
@apf_effect("<name>")permit onlyApplies the named PolicyEffect when the statement fires.
@apf_finding("<name>")permit or forbidRecords the named PolicyFinding with the allow or the deny.

PolicyAnnotator

FieldTypeRequiredDescription
spec.descriptionstringNoDescription.
spec.annotations[].namestringYesKey under context.annotations. Unique across all annotators in the bundle.
spec.annotations[].outputstringYesbool, string, or integer.
spec.annotations[].set_true_ifstringNoany (default) or all. For bool outputs.
spec.annotations[].set_value_fromstringNofirst_match, the only value. For string outputs.
spec.annotations[].rules[].fieldstringYesField selector.
spec.annotations[].rules[].opstringYesOperation.
pattern, value, prefix, suffix, substring, thresholdstring or integerPer operationOperands. A string output also uses value as the output value.

threshold_from is rejected. Every annotation needs at least one rule. For field selectors and operations, refer to Annotators.

PolicyEffect

FieldTypeDescription
spec.descriptionstringDescription.
spec.verdictstringallow (default), warn, or escalate. Advisory.
spec.reasonstringMachine-readable reason for the verdict.
spec.messagestringHuman-readable message for the verdict.
spec.body.replacestringReplacement for the whole body.
spec.body.patches[]listop (replace, add, or remove), path (JSON Pointer), and value or source.
spec.headers[]listname, action (set, add, or remove), and value or source.
spec.findingstring or objectA PolicyFinding name, or an inline finding with type, severity, label, label_source, and confidence.

Set exactly one of body.replace and body.patches. source must have the form context.annotations.<key>. Refer to Effects and Findings.

PolicyFinding

FieldTypeRequiredDescription
spec.descriptionstringNoDescription.
spec.typestringYesFinding category, recorded as kind in audit records.
spec.severitystringYeslow, medium, high, or critical.
spec.labelstringNoStatic label.
spec.label_sourcestringNocontext.annotations.<key>. Its value becomes the label. If the annotation is absent, the request is denied.

Other Kinds

The loader also collects HostTool members, but no component uses them in this release.

Schema and Runtime Differences

The runtime checks some things the schemas do not, and skips some things the schemas require.

TopicSchemaRuntime
apiVersion, kind constantsRequired and fixed.Not checked. kind only routes the member.
metadata.namespaceForbidden.Accepted and ignored.
Unknown kindNot applicable.Hash-checked, then ignored.
PolicyRule.spec.rolecapability or control.control is a control rule. Anything else is a grant.
Annotator rulesOptional.At least one rule is required.
Annotator string outputvalue optional.Every rule needs a value.
Effect bodyreplace and patches both allowed.Exactly one is required.
Effect sourceAny string.Must be context.annotations.<key>.
Header namesAny string.On OpenShell, set and add require the x-openshell-middleware- prefix.
Inline finding confidence0 to 100.0 to 255 is parsed. Audit records clamp it to 100.
landlock.compatibilitybest_effort, required, or disabled.Any string is passed through. OpenShell accepts only best_effort and hard_requirement.
Endpoint tlsterminate or passthrough.skip, terminate, and passthrough are passed to OpenShell, which accepts only skip or an omitted value.
Endpoint cross-field rulesEnforced by allOf conditions.Not checked by APF.
network_middlewares limits10 entries, 32 hosts per list.Not checked by APF.
Provider credentials[].styleEnumerated, with required companion fields.Any string is passed through.
Provider token-grant.tokenEndpointOptional.Required.
Provider endpoint hostRequired.Not checked by APF.

Several checks run only when the policy gateway builds its evaluator, not when the policy service loads the bundle, so a bundle that fails them still loads and consumes its revision: Cedar syntax and schema validation, @apf_effect and @apf_finding placement and references, effect finding references, annotator field selectors, operands, patterns, output types, rule counts, and key uniqueness, effect body and operand combinations, and source and label_source forms. Duplicate document names are caught earlier, when the policy service loads the members.

Next Steps