Documentation

Everything to model, register, and enforce a contract. Reading the docs is open. Provisioning a workspace and issuing tokens is gated to the design-partner phase — request a ruleset workspace.

Quickstart

The gateway exposes a single base for schema operations at schema.validitycore.net. A design-partner token is required for every call.

1 · Register a ruleset

POST · register

curl -X POST \
  https://schema.validitycore.net/validate/contract/v5j2r9/ruleset/ \
  -H "Authorization: Bearer $VC_TOKEN" \
  -H "Content-Type: application/yaml" \
  --data-binary @ruleset.yaml

2 · Validate a payload (observe mode)

POST · validate

curl -X POST \
  https://schema.validitycore.net/validate/contract/v5j2r9/ruleset/orders-api \
  -H "Authorization: Bearer $VC_TOKEN" \
  -d '{"order":{"id":"ord_9f2k","total":"49.99"}}'

3 · Read the verdict

200 · application/jsonfail

{
  "verdict": "fail",
  "ruleset": "orders-api@v5j2r9",
  "mode": "observe",
  "violations": [
    {
      "path": "$.order.total",
      "rule": "type",
      "code": "VC-2007",
      "expected": "number",
      "received": "string"
    }
  ],
  "latency_ms": 0.4
}

Get an API token. Tokens ($VC_TOKEN) are issued to teams admitted to the Design Partner Program. Apply for a cohort →

Ruleset format

A ruleset is a versioned artifact that binds a source schema to a target route or topic and declares how strictly it's enforced. Rulesets are immutable once registered — a change is a new version.

ruleset.yaml

apiVersion: validitycore.net/v1
kind: Ruleset
metadata:
  name: orders-api
  version: v5j2r9
spec:
  source: openapi          # openapi | jsonschema | protobuf
  schemaRef: ./openapi.yaml#/components/schemas/Order
  target: POST /orders
  mode: observe            # observe | warn | enforce
  onViolation: reject      # reject | annotate
  sampling: 1.0             # 0.0–1.0, observe/warn only

Field	Type	Notes
spec.source	enum	Format of the schema. Compiled to the validation IR.
spec.target	string	HTTP route or topic: the ruleset governs.
spec.mode	enum	observe logs only · warn adds a header · enforce rejects.
spec.onViolation	enum	reject returns 422 · annotate passes through with a report header.

Validation API

All endpoints are under https://schema.validitycore.net/validate/contract/<version>/ and require a Bearer token.

Method	Path	Purpose
POST	…/ruleset/	Register a new ruleset version
POST	…/ruleset/{name}	Validate a payload against a ruleset
POST	…/ruleset/{name}/promote	Change enforcement mode (no deploy)
GET	…/ruleset/{name}	Fetch a compiled ruleset & its mode
GET	…/ledger?ruleset={name}	Query validation decisions

Violation report

Every validation returns a verdict object. On enforce, a failing verdict is returned to the client as HTTP 422 with the same body.

Field	Type	Description
verdict	"pass"\|"fail"	Overall result for the payload.
ruleset	string	Name and version that produced the verdict.
violations[].path	string	JSONPath to the offending field.
violations[].rule	string	Which constraint failed (type, required, enum, format…).
violations[].code	string	Stable error code — see the catalog below.
latency_ms	number	Validation time added to the request.

Error catalog

Codes are stable across versions. VC-1xxx are ruleset/registration errors, VC-2xxx are payload violations, VC-4xxx are auth/limits.

Code	Name	Meaning
VC-1001	unknown-ruleset	No ruleset registered under that name/version.
VC-1002	malformed-ruleset	Ruleset YAML failed to compile to the IR.
VC-2003	required-field-missing	A field marked required was absent.
VC-2007	type-mismatch	Field type differs from the contract.
VC-2011	enum-not-allowed	Value outside the declared enum set.
VC-4010	token-not-authorized	Token missing, expired, or not a design partner.

Limits

·Request rate: 2,000 rps per token (design-partner default). Higher on the Fleet track.
·Max ruleset size: 2 MB compiled IR.
·Ledger retention: 30 days (Observe) · 1 year (Enforce) · custom (Fleet).
·Latency budget: p50 < 1ms, p99 < 5ms added per validated request.

Ready to enforce your contracts?

Workspaces and API tokens are issued to design partners only while ValidityCore is pre-GA.

Apply to the Design Partner Program