API Governance · Schema

Governance Policy

A governance policy bundles related rules and applies them with a defined scope, lifecycle stage, ownership, and enforcement engine across the API estate.

GovernancePoliciesRulesSpectralLintingLifecycleComplianceStandardsOpenAPIAsyncAPI

Properties

Name	Type	Description
id	string	Unique, stable identifier for the policy (kebab-case).
name	string	Human-readable policy name.
description	string	What the policy governs and the business intent behind it.
scope	string	Governance scope the policy belongs to.
target	array	Artifact types the policy applies to.
lifecycle	array	Lifecycle stages where the policy is enforced.
enforcement	string	How violations of the policy are handled.
engine	string	Engine that enforces the policy at runtime or in CI.
conformance	string	RFC 2119 requirement level for the policy as a whole.
rules	array	Rule IDs composed into the policy.
owner	string	Person or governance body accountable for the policy.
approvers	array	Stakeholders who must approve changes to the policy.
exceptions	array	Approved exemptions from this policy.
tags	array	Domain tags for grouping and discovery.
guidanceUrl	string	Link to longer-form guidance backing the policy.
status	string	Lifecycle status of the policy itself.
version	string	Semantic version of the policy.
created	string	ISO 8601 creation date.
modified	string	ISO 8601 last-modified date.

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-policy-schema.json",
  "title": "Governance Policy",
  "description": "A governance policy bundles related rules and applies them with a defined scope, lifecycle stage, ownership, and enforcement engine across the API estate.",
  "type": "object",
  "required": ["id", "name", "scope", "rules"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique, stable identifier for the policy (kebab-case)."
    },
    "name": {
      "type": "string",
      "description": "Human-readable policy name."
    },
    "description": {
      "type": "string",
      "description": "What the policy governs and the business intent behind it."
    },
    "scope": {
      "type": "string",
      "enum": [
        "spec",
        "design",
        "security",
        "lifecycle",
        "experience",
        "compliance",
        "performance"
      ],
      "description": "Governance scope the policy belongs to."
    },
    "target": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "openapi",
          "asyncapi",
          "json-schema",
          "graphql",
          "grpc",
          "avro",
          "protobuf",
          "traffic",
          "policy",
          "configuration",
          "apis-yml"
        ]
      },
      "description": "Artifact types the policy applies to."
    },
    "lifecycle": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "design",
          "build",
          "test",
          "release",
          "deprecation",
          "retirement",
          "runtime"
        ]
      },
      "description": "Lifecycle stages where the policy is enforced."
    },
    "enforcement": {
      "type": "string",
      "enum": ["advisory", "blocking", "remediated", "monitored"],
      "description": "How violations of the policy are handled."
    },
    "engine": {
      "type": "string",
      "enum": ["spectral", "vacuum", "redocly", "speakeasy", "postman", "apicurio", "custom"],
      "description": "Engine that enforces the policy at runtime or in CI."
    },
    "conformance": {
      "type": "string",
      "enum": ["MUST", "SHOULD", "MAY", "MUST NOT", "SHOULD NOT"],
      "description": "RFC 2119 requirement level for the policy as a whole."
    },
    "rules": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "ID of a governance rule included in this policy."
      },
      "minItems": 1,
      "description": "Rule IDs composed into the policy."
    },
    "owner": {
      "type": "string",
      "description": "Person or governance body accountable for the policy."
    },
    "approvers": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Stakeholders who must approve changes to the policy."
    },
    "exceptions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "api": { "type": "string" },
          "reason": { "type": "string" },
          "expires": { "type": "string", "format": "date" }
        },
        "required": ["api", "reason"]
      },
      "description": "Approved exemptions from this policy."
    },
    "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 policy."
    },
    "status": {
      "type": "string",
      "enum": ["draft", "active", "deprecated", "retired"],
      "description": "Lifecycle status of the policy itself."
    },
    "version": {
      "type": "string",
      "description": "Semantic version of the policy."
    },
    "created": {
      "type": "string",
      "format": "date",
      "description": "ISO 8601 creation date."
    },
    "modified": {
      "type": "string",
      "format": "date",
      "description": "ISO 8601 last-modified date."
    }
  },
  "additionalProperties": false
}