{
  "$id": "https://stella.ops/schema/api-baseline.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ApiBaseline",
  "description": "APIG0101 API governance baseline contract for OpenAPI spec management, compatibility tracking, and changelog generation",
  "type": "object",
  "oneOf": [
    { "$ref": "#/$defs/BaselineDocument" },
    { "$ref": "#/$defs/CompatibilityReport" },
    { "$ref": "#/$defs/ChangelogEntry" },
    { "$ref": "#/$defs/DiscoveryManifest" }
  ],
  "$defs": {
    "BaselineDocument": {
      "type": "object",
      "required": ["documentType", "schemaVersion", "generatedAt", "specVersion", "services"],
      "properties": {
        "documentType": {
          "type": "string",
          "const": "API_BASELINE"
        },
        "schemaVersion": {
          "type": "integer",
          "const": 1,
          "description": "Baseline schema version"
        },
        "generatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "ISO-8601 timestamp when baseline was generated"
        },
        "specVersion": {
          "type": "string",
          "description": "OpenAPI specification version",
          "examples": ["3.1.0", "3.0.3"]
        },
        "aggregateDigest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$",
          "description": "SHA-256 digest of the composed aggregate spec"
        },
        "services": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ServiceSpec"
          },
          "minItems": 1,
          "description": "Per-service OpenAPI specifications"
        },
        "sharedComponents": {
          "$ref": "#/$defs/SharedComponentsRef",
          "description": "Reference to shared component library"
        },
        "governanceProfile": {
          "$ref": "#/$defs/GovernanceProfile",
          "description": "Governance rules applied to this baseline"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Additional baseline metadata"
        }
      }
    },
    "ServiceSpec": {
      "type": "object",
      "required": ["serviceId", "specPath", "specDigest", "version"],
      "properties": {
        "serviceId": {
          "type": "string",
          "description": "Unique service identifier",
          "examples": ["authority", "scanner", "excititor", "concelier"]
        },
        "displayName": {
          "type": "string",
          "description": "Human-readable service name"
        },
        "specPath": {
          "type": "string",
          "description": "Relative path to service OpenAPI spec",
          "examples": ["authority/openapi.yaml", "scanner/openapi.yaml"]
        },
        "specDigest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$",
          "description": "SHA-256 digest of the service spec"
        },
        "version": {
          "type": "string",
          "description": "Service API version",
          "examples": ["v1", "v2-beta"]
        },
        "operationCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of operations defined"
        },
        "schemaCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of schemas defined"
        },
        "exampleCoverage": {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "Percentage of responses with examples"
        },
        "securitySchemes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Security schemes used by this service",
          "examples": [["bearerAuth", "mTLS", "OAuth2"]]
        },
        "endpoints": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/EndpointSummary"
          },
          "description": "Summary of endpoints in this service"
        }
      }
    },
    "EndpointSummary": {
      "type": "object",
      "required": ["path", "method", "operationId"],
      "properties": {
        "path": {
          "type": "string",
          "description": "API endpoint path"
        },
        "method": {
          "type": "string",
          "enum": ["get", "post", "put", "patch", "delete", "head", "options"],
          "description": "HTTP method"
        },
        "operationId": {
          "type": "string",
          "description": "Unique operation identifier (lowerCamelCase)"
        },
        "summary": {
          "type": "string",
          "description": "Short operation summary"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Operation tags for grouping"
        },
        "deprecated": {
          "type": "boolean",
          "default": false,
          "description": "Whether this endpoint is deprecated"
        },
        "hasRequestBody": {
          "type": "boolean",
          "description": "Whether operation accepts request body"
        },
        "responseStatuses": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "HTTP status codes returned"
        }
      }
    },
    "SharedComponentsRef": {
      "type": "object",
      "properties": {
        "path": {
          "type": "string",
          "description": "Path to shared components directory",
          "examples": ["_shared/"]
        },
        "digest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$",
          "description": "Digest of shared components bundle"
        },
        "schemas": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of shared schema names"
        },
        "securitySchemes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of shared security scheme names"
        },
        "parameters": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of shared parameter names"
        },
        "responses": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of shared response names"
        }
      }
    },
    "GovernanceProfile": {
      "type": "object",
      "properties": {
        "spectralRuleset": {
          "type": "string",
          "description": "Path to Spectral ruleset file",
          "examples": [".spectral.yaml"]
        },
        "rules": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/GovernanceRule"
          },
          "description": "Active governance rules"
        },
        "requiredExampleCoverage": {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "Minimum required example coverage percentage"
        },
        "breakingChangePolicy": {
          "type": "string",
          "enum": ["BLOCK", "WARN", "ALLOW"],
          "description": "Policy for breaking changes"
        }
      }
    },
    "GovernanceRule": {
      "type": "object",
      "required": ["ruleId", "severity"],
      "properties": {
        "ruleId": {
          "type": "string",
          "description": "Spectral rule identifier",
          "examples": ["stella-2xx-response-examples", "stella-pagination-params"]
        },
        "severity": {
          "type": "string",
          "enum": ["error", "warn", "info", "hint", "off"],
          "description": "Rule severity level"
        },
        "description": {
          "type": "string",
          "description": "Rule description"
        }
      }
    },
    "CompatibilityReport": {
      "type": "object",
      "required": ["documentType", "generatedAt", "baselineDigest", "currentDigest", "compatible"],
      "properties": {
        "documentType": {
          "type": "string",
          "const": "COMPATIBILITY_REPORT"
        },
        "generatedAt": {
          "type": "string",
          "format": "date-time"
        },
        "baselineDigest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$",
          "description": "Digest of baseline spec"
        },
        "currentDigest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$",
          "description": "Digest of current spec"
        },
        "compatible": {
          "type": "boolean",
          "description": "Whether current spec is backward compatible"
        },
        "breakingChanges": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BreakingChange"
          },
          "description": "List of breaking changes detected"
        },
        "additiveChanges": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ApiChange"
          },
          "description": "List of additive (non-breaking) changes"
        },
        "deprecations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Deprecation"
          },
          "description": "New deprecations introduced"
        }
      }
    },
    "BreakingChange": {
      "type": "object",
      "required": ["changeType", "path", "description"],
      "properties": {
        "changeType": {
          "type": "string",
          "enum": [
            "ENDPOINT_REMOVED",
            "METHOD_REMOVED",
            "REQUIRED_PARAM_ADDED",
            "PARAM_REMOVED",
            "RESPONSE_REMOVED",
            "SCHEMA_INCOMPATIBLE",
            "TYPE_CHANGED",
            "SECURITY_STRENGTHENED"
          ],
          "description": "Type of breaking change"
        },
        "path": {
          "type": "string",
          "description": "JSON pointer to changed element"
        },
        "description": {
          "type": "string",
          "description": "Human-readable change description"
        },
        "service": {
          "type": "string",
          "description": "Affected service"
        },
        "operationId": {
          "type": "string",
          "description": "Affected operation"
        },
        "before": {
          "type": "string",
          "description": "Previous value (if applicable)"
        },
        "after": {
          "type": "string",
          "description": "New value (if applicable)"
        }
      }
    },
    "ApiChange": {
      "type": "object",
      "required": ["changeType", "path"],
      "properties": {
        "changeType": {
          "type": "string",
          "enum": [
            "ENDPOINT_ADDED",
            "METHOD_ADDED",
            "OPTIONAL_PARAM_ADDED",
            "RESPONSE_ADDED",
            "SCHEMA_EXTENDED",
            "EXAMPLE_ADDED"
          ],
          "description": "Type of additive change"
        },
        "path": {
          "type": "string",
          "description": "JSON pointer to changed element"
        },
        "description": {
          "type": "string",
          "description": "Human-readable change description"
        },
        "service": {
          "type": "string",
          "description": "Affected service"
        }
      }
    },
    "Deprecation": {
      "type": "object",
      "required": ["path", "deprecatedAt"],
      "properties": {
        "path": {
          "type": "string",
          "description": "JSON pointer to deprecated element"
        },
        "deprecatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When deprecation was introduced"
        },
        "removalDate": {
          "type": "string",
          "format": "date",
          "description": "Planned removal date"
        },
        "replacement": {
          "type": "string",
          "description": "Replacement endpoint/schema if available"
        },
        "reason": {
          "type": "string",
          "description": "Reason for deprecation"
        }
      }
    },
    "ChangelogEntry": {
      "type": "object",
      "required": ["documentType", "version", "releaseDate", "changes"],
      "properties": {
        "documentType": {
          "type": "string",
          "const": "CHANGELOG_ENTRY"
        },
        "version": {
          "type": "string",
          "description": "API version for this changelog entry"
        },
        "releaseDate": {
          "type": "string",
          "format": "date",
          "description": "Release date"
        },
        "specDigest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$",
          "description": "Digest of the spec at this version"
        },
        "changes": {
          "type": "object",
          "properties": {
            "added": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "New features/endpoints added"
            },
            "changed": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Changes to existing features"
            },
            "deprecated": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Newly deprecated features"
            },
            "removed": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Removed features"
            },
            "fixed": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Bug fixes"
            },
            "security": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Security-related changes"
            }
          }
        },
        "contributors": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Contributors to this release"
        }
      }
    },
    "DiscoveryManifest": {
      "type": "object",
      "required": ["documentType", "spec", "version", "generatedAt"],
      "description": "OpenAPI discovery endpoint response (/.well-known/openapi)",
      "properties": {
        "documentType": {
          "type": "string",
          "const": "DISCOVERY_MANIFEST"
        },
        "spec": {
          "type": "string",
          "description": "Path to the aggregate OpenAPI spec",
          "examples": ["/stella.yaml"]
        },
        "version": {
          "type": "string",
          "description": "API version identifier",
          "examples": ["v1", "v2"]
        },
        "generatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When the spec was generated"
        },
        "specDigest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$",
          "description": "Digest of the spec file"
        },
        "extensions": {
          "type": "object",
          "properties": {
            "x-stellaops-profile": {
              "type": "string",
              "enum": ["aggregate", "per-service", "minimal"],
              "description": "Spec profile type"
            },
            "x-stellaops-schemaVersion": {
              "type": "string",
              "description": "Schema version for extensions"
            },
            "x-stellaops-services": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Services included in aggregate"
            }
          }
        },
        "alternates": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AlternateSpec"
          },
          "description": "Alternative spec formats/versions"
        }
      }
    },
    "AlternateSpec": {
      "type": "object",
      "required": ["format", "path"],
      "properties": {
        "format": {
          "type": "string",
          "enum": ["yaml", "json", "html"],
          "description": "Spec format"
        },
        "path": {
          "type": "string",
          "description": "Path to alternate spec"
        },
        "version": {
          "type": "string",
          "description": "OpenAPI version if different"
        }
      }
    }
  },
  "examples": [
    {
      "documentType": "API_BASELINE",
      "schemaVersion": 1,
      "generatedAt": "2025-11-21T10:00:00Z",
      "specVersion": "3.1.0",
      "aggregateDigest": "sha256:7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee",
      "services": [
        {
          "serviceId": "authority",
          "displayName": "Authority Service",
          "specPath": "authority/openapi.yaml",
          "specDigest": "sha256:8d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aef",
          "version": "v1",
          "operationCount": 15,
          "schemaCount": 25,
          "exampleCoverage": 95.5,
          "securitySchemes": ["bearerAuth", "OAuth2"]
        }
      ],
      "sharedComponents": {
        "path": "_shared/",
        "schemas": ["ErrorResponse", "PaginatedResponse", "HealthStatus"],
        "securitySchemes": ["bearerAuth", "mTLS"]
      },
      "governanceProfile": {
        "spectralRuleset": ".spectral.yaml",
        "requiredExampleCoverage": 90,
        "breakingChangePolicy": "BLOCK",
        "rules": [
          {
            "ruleId": "stella-2xx-response-examples",
            "severity": "error",
            "description": "Every 2xx response must include at least one example"
          }
        ]
      }
    },
    {
      "documentType": "DISCOVERY_MANIFEST",
      "spec": "/stella.yaml",
      "version": "v1",
      "generatedAt": "2025-11-21T10:00:00Z",
      "specDigest": "sha256:7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee",
      "extensions": {
        "x-stellaops-profile": "aggregate",
        "x-stellaops-schemaVersion": "1.0.0",
        "x-stellaops-services": ["authority", "scanner", "excititor", "concelier"]
      },
      "alternates": [
        { "format": "json", "path": "/stella.json" },
        { "format": "html", "path": "/docs/api" }
      ]
    }
  ]
}