{
  "$defs": {
    "ApiAudience": {
      "description": "Audience scope.",
      "oneOf": [
        {
          "const": "public",
          "description": "Public — anyone with API key / customer credential.",
          "type": "string"
        },
        {
          "const": "partner",
          "description": "Partner — restricted to integration partners.",
          "type": "string"
        },
        {
          "const": "internal",
          "description": "Internal — within the org / between services.",
          "type": "string"
        },
        {
          "const": "first_party",
          "description": "First-party (Cockpit consumed only).",
          "type": "string"
        }
      ]
    },
    "ApiKind": {
      "description": "API kind / protocol.",
      "oneOf": [
        {
          "const": "rest",
          "description": "REST / HTTP+JSON.",
          "type": "string"
        },
        {
          "const": "graphql",
          "description": "GraphQL.",
          "type": "string"
        },
        {
          "const": "grpc",
          "description": "gRPC.",
          "type": "string"
        },
        {
          "const": "sse",
          "description": "Server-Sent Events.",
          "type": "string"
        },
        {
          "const": "web_socket",
          "description": "WebSocket.",
          "type": "string"
        },
        {
          "const": "webhook",
          "description": "Webhook (callback we deliver).",
          "type": "string"
        },
        {
          "const": "mcp",
          "description": "MCP (Model Context Protocol).",
          "type": "string"
        }
      ]
    },
    "ApiStatus": {
      "description": "Lifecycle.",
      "oneOf": [
        {
          "const": "alpha",
          "description": "Internal-only preview.",
          "type": "string"
        },
        {
          "const": "beta",
          "description": "Public preview (no backwards-compat guarantee).",
          "type": "string"
        },
        {
          "const": "stable",
          "description": "GA / stable.",
          "type": "string"
        },
        {
          "const": "deprecated",
          "description": "Deprecated but still functional.",
          "type": "string"
        },
        {
          "const": "sunset",
          "description": "Sunset — returns errors.",
          "type": "string"
        },
        {
          "const": "removed",
          "description": "Removed from the surface.",
          "type": "string"
        }
      ]
    },
    "AuthKind": {
      "description": "Authentication requirement.",
      "oneOf": [
        {
          "const": "none",
          "description": "No authentication.",
          "type": "string"
        },
        {
          "const": "api_key",
          "description": "API key.",
          "type": "string"
        },
        {
          "const": "o_auth2_bearer",
          "description": "OAuth 2.0 Bearer token.",
          "type": "string"
        },
        {
          "const": "cookie",
          "description": "Cookie-based session.",
          "type": "string"
        },
        {
          "const": "mtls",
          "description": "Mutual TLS.",
          "type": "string"
        },
        {
          "const": "jwt",
          "description": "JWT bearer.",
          "type": "string"
        },
        {
          "const": "webauthn",
          "description": "WebAuthn / passkey.",
          "type": "string"
        },
        {
          "const": "signed_hmac",
          "description": "Signed request (HMAC).",
          "type": "string"
        }
      ]
    },
    "HttpMethod": {
      "description": "HTTP method.",
      "enum": [
        "GET",
        "POST",
        "PUT",
        "PATCH",
        "DELETE",
        "HEAD",
        "OPTIONS"
      ],
      "type": "string"
    },
    "IsoDate": {
      "description": "ISO 8601 date (YYYY-MM-DD).",
      "format": "date",
      "type": "string"
    },
    "PathRef": {
      "description": "Path-based cross-reference relative to .corpospec/ root.\nPattern: `^[a-z0-9_-]+(/[a-z0-9_.-]+)+$`",
      "pattern": "^[a-z0-9_-]+(/[a-z0-9_.-]+)+$",
      "type": "string"
    },
    "PiiClass": {
      "description": "Personal-data classification on every record carrying personal data, per\nBDR 0070 / BDR 0069 / BDR 0078. Used by `corpospec-report` to gate\nrendering and by the privacy pillar's RoPA records to determine\nsafeguards.",
      "oneOf": [
        {
          "const": "none",
          "description": "No personal data.",
          "type": "string"
        },
        {
          "const": "public_personal",
          "description": "Public personal data (already disclosed by the subject, e.g. CEO name).",
          "type": "string"
        },
        {
          "const": "internal",
          "description": "Internal-only personal data (employee directory).",
          "type": "string"
        },
        {
          "const": "personal",
          "description": "Personal data per GDPR Art. 4(1).",
          "type": "string"
        },
        {
          "const": "special_category",
          "description": "Special-category data per GDPR Art. 9 (health, biometric, genetic,\nreligion, ethnicity, sex life, political opinion, trade union).",
          "type": "string"
        },
        {
          "const": "criminal_data",
          "description": "Criminal data per GDPR Art. 10.",
          "type": "string"
        },
        {
          "const": "sensitive",
          "description": "CCPA / CPRA \"sensitive personal information\".",
          "type": "string"
        }
      ]
    }
  },
  "$id": "https://corpospec.com/schemas/v0.16.0/api-endpoint.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "description": "API-endpoint record.",
  "properties": {
    "api_version": {
      "description": "API version (e.g. \"v1\", \"2026-05-01\").",
      "type": "string"
    },
    "audience": {
      "$ref": "#/$defs/ApiAudience"
    },
    "auth_required": {
      "$ref": "#/$defs/AuthKind"
    },
    "deprecated_on": {
      "anyOf": [
        {
          "$ref": "#/$defs/IsoDate"
        },
        {
          "type": "null"
        }
      ],
      "description": "First-deprecated date."
    },
    "docs_ref": {
      "anyOf": [
        {
          "$ref": "#/$defs/PathRef"
        },
        {
          "type": "null"
        }
      ],
      "description": "PathRef to docs / OpenAPI page."
    },
    "id": {
      "$ref": "#/$defs/PathRef"
    },
    "kind": {
      "$ref": "#/$defs/ApiKind"
    },
    "method": {
      "$ref": "#/$defs/HttpMethod"
    },
    "operation_id": {
      "description": "OpenAPI operation_id.",
      "type": "string"
    },
    "owner": {
      "$ref": "#/$defs/PathRef"
    },
    "p99_latency_target_ms": {
      "description": "SLO p99 latency target ms.",
      "format": "double",
      "type": [
        "number",
        "null"
      ]
    },
    "path": {
      "description": "URL path or operation key.",
      "type": "string"
    },
    "pii_class": {
      "$ref": "#/$defs/PiiClass",
      "description": "PII class of data crossed."
    },
    "rate_limit_rpm": {
      "description": "Rate limit (requests per minute; None = unlimited / inherited).",
      "format": "int32",
      "type": [
        "integer",
        "null"
      ]
    },
    "replaced_by": {
      "anyOf": [
        {
          "$ref": "#/$defs/PathRef"
        },
        {
          "type": "null"
        }
      ],
      "description": "PathRef to replacement endpoint (when deprecated)."
    },
    "required_scopes": {
      "description": "Scopes / permissions required.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "schema_ref": {
      "anyOf": [
        {
          "$ref": "#/$defs/PathRef"
        },
        {
          "type": "null"
        }
      ],
      "description": "PathRef to OpenAPI / GraphQL schema fragment."
    },
    "service": {
      "$ref": "#/$defs/PathRef",
      "description": "PathRef to the parent service."
    },
    "status": {
      "$ref": "#/$defs/ApiStatus"
    },
    "sunset_on": {
      "anyOf": [
        {
          "$ref": "#/$defs/IsoDate"
        },
        {
          "type": "null"
        }
      ],
      "description": "Date at which Sunset header begins (RFC 8594)."
    }
  },
  "required": [
    "id",
    "service",
    "kind",
    "method",
    "path",
    "operation_id",
    "api_version",
    "audience",
    "status",
    "auth_required",
    "pii_class",
    "owner"
  ],
  "title": "ApiEndpoint",
  "type": "object",
  "x-corpospec-pillar": "operations"
}