OpenAPI contract
The payments API description and its ruleset bound to each other - entities reference schemas, operations carry x-rule-cascade, and baseline rules are derived from schema constraints.
Files: examples/contracts/payments.openapi.yaml,
examples/contracts/payments-transfer.ruleset.yaml,
examples/derived/.
The full explanation is OpenAPI and Rule Cascade.
The API names its ruleset and tags each operation
# Root binding: which ruleset governs this API.
x-rule-cascade:
ruleset: acme.payments.transfer
version: ^1.0.0
paths:
/transfers:
post:
operationId: createTransfer
summary: Create a transfer
x-rule-cascade: { entity: Transfer, operation: create }
# ...
responses:
"201":
description: Created. Non-blocking findings are returned alongside the resource.
"422": { $ref: "#/components/responses/RuleViolation" }Every operation the rules can deny declares a 422 response: RFC 9457 problem details extended
with the evaluation result.
The ruleset references the schema and binds the operations
entities:
Transfer:
schema: { $ref: "./payments.openapi.yaml#/components/schemas/Transfer" }
bindings:
openapi:
- document: ./payments.openapi.yaml
entity: Transfer
operations:
create: createTransfer
read: getTransfer
update: updateTransfer
delete: deleteTransfer
approve: approveTransferBecause the entity references a component schema, a rule that reads a field the API does not have
fails to load with PATH_UNKNOWN. Because both sides name each other, check reports
BINDING_MISMATCH when they disagree, for example after a major version of the ruleset that the
API still binds as ^1.0.0.
Baseline rules derived from the schema
required, enum, minLength, pattern, minimum, format and similar constraints become rules
with codes, messages and field pointers:
python tools/rulecheck.py derive examples/catalog/onboarding.openapi.yaml \
--schema Customer --id acme.generated.customer -o customer.ruleset.yamlThe generated rulesets and their golden tests are committed in examples/derived and checked in
CI; a unit test fails when they are stale. The commands that produce them are in
OpenAPI and Rule Cascade, section 3.
The evaluation API itself
The rule server's own HTTP API is described in OpenAPI 3.1:
spec/v1/rule-evaluation.openapi.yaml.