API Governance · Schema

Governance Rule

A machine-enforceable governance rule applied to an API artifact (OpenAPI, AsyncAPI, JSON Schema, traffic, configuration) by a linter, registry, gateway, or runtime.

GovernancePoliciesRulesSpectralLintingLifecycleComplianceStandardsOpenAPIAsyncAPI

Properties

Name	Type	Description
id	string	Unique, stable identifier for the rule (kebab-case).
name	string	Short human-readable name for the rule.
description	string	Full description of what the rule checks and why.
message	string	Message shown when the rule is violated.
rationale	string	Business or engineering reason the rule exists.
severity	string	Severity level emitted on violation.
target	string	Artifact type the rule targets.
scope	string	Governance scope the rule belongs to.
lifecycle	string	Lifecycle stage at which the rule is enforced.
given	string	JSONPath, JMESPath, or selector locating the value the rule applies to.
then	object	Action taken when the rule matches.
function	string	Name of the function the rule invokes (e.g. truthy, falsy, pattern, length).
functionOptions	object	Parameters passed to the function.
conformance	string	RFC 2119 requirement level the rule expresses.
engine	string	Engine that evaluates the rule.
tags	array	Domain tags for grouping and discovery.
guidanceUrl	string	Link to longer-form guidance backing the rule.
owner	string	Person or governance body accountable for the rule.
created	string	ISO 8601 creation date.
modified	string	ISO 8601 last-modified date.
version	string	Semantic version of the rule.
status	string	Lifecycle status of the rule itself.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/governance/main/json-schema/governance-rule-schema.json",
  "title": "Governance Rule",
  "description": "A machine-enforceable governance rule applied to an API artifact (OpenAPI, AsyncAPI, JSON Schema, traffic, configuration) by a linter, registry, gateway, or runtime.",
  "type": "object",
  "required": ["id", "name", "severity", "target", "scope", "message"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique, stable identifier for the rule (kebab-case)."
    },
    "name": {
      "type": "string",
      "description": "Short human-readable name for the rule."
    },
    "description": {
      "type": "string",
      "description": "Full description of what the rule checks and why."
    },
    "message": {
      "type": "string",
      "description": "Message shown when the rule is violated."
    },
    "rationale": {
      "type": "string",
      "description": "Business or engineering reason the rule exists."
    },
    "severity": {
      "type": "string",
      "enum": ["error", "warn", "warning", "info", "hint"],
      "description": "Severity level emitted on violation."
    },
    "target": {
      "type": "string",
      "enum": [
        "openapi",
        "asyncapi",
        "json-schema",
        "graphql",
        "grpc",
        "avro",
        "protobuf",
        "traffic",
        "policy",
        "configuration",
        "apis-yml"
      ],
      "description": "Artifact type the rule targets."
    },
    "scope": {
      "type": "string",
      "enum": [
        "spec",
        "design",
        "security",
        "lifecycle",
        "experience",
        "compliance",
        "performance"
      ],
      "description": "Governance scope the rule belongs to."
    },
    "lifecycle": {
      "type": "string",
      "enum": [
        "design",
        "build",
        "test",
        "release",
        "deprecation",
        "retirement",
        "runtime"
      ],
      "description": "Lifecycle stage at which the rule is enforced."
    },
    "given": {
      "type": "string",
      "description": "JSONPath, JMESPath, or selector locating the value the rule applies to."
    },
    "then": {
      "type": "object",
      "description": "Action taken when the rule matches.",
      "additionalProperties": true
    },
    "function": {
      "type": "string",
      "description": "Name of the function the rule invokes (e.g. truthy, falsy, pattern, length)."
    },
    "functionOptions": {
      "type": "object",
      "description": "Parameters passed to the function.",
      "additionalProperties": true
    },
    "conformance": {
      "type": "string",
      "enum": ["MUST", "SHOULD", "MAY", "MUST NOT", "SHOULD NOT"],
      "description": "RFC 2119 requirement level the rule expresses."
    },
    "engine": {
      "type": "string",
      "enum": ["spectral", "vacuum", "redocly", "speakeasy", "postman", "custom"],
      "description": "Engine that evaluates the rule."
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Domain tags for grouping and discovery."
    },
    "guidanceUrl": {
      "type": "string",
      "format": "uri",
      "description": "Link to longer-form guidance backing the rule."
    },
    "owner": {
      "type": "string",
      "description": "Person or governance body accountable for the rule."
    },
    "created": {
      "type": "string",
      "format": "date",
      "description": "ISO 8601 creation date."
    },
    "modified": {
      "type": "string",
      "format": "date",
      "description": "ISO 8601 last-modified date."
    },
    "version": {
      "type": "string",
      "description": "Semantic version of the rule."
    },
    "status": {
      "type": "string",
      "enum": ["draft", "active", "deprecated", "retired"],
      "description": "Lifecycle status of the rule itself."
    }
  },
  "additionalProperties": false
}