8768c27f30
- Introduced `ReachabilityState`, `RuntimeHit`, `ExploitabilitySignal`, `ReachabilitySignal`, `SignalEnvelope`, `SignalType`, `TrustSignal`, and `UnknownSymbolSignal` records to define various signal types and their properties. - Implemented JSON serialization attributes for proper data interchange. - Created project files for the new signal contracts library and corresponding test projects. - Added deterministic test fixtures for micro-interaction testing. - Included cryptographic keys for secure operations with cosign.
629 lines
18 KiB
JSON
629 lines
18 KiB
JSON
{
|
|
"$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" }
|
|
]
|
|
}
|
|
]
|
|
}
|