{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://stella-ops.org/schemas/devportal-api.schema.json",
  "title": "StellaOps DevPortal API Schema",
  "description": "Schema for DevPortal API baseline and SDK generator integration. Unblocks APIG0101 chain (62-001 to 63-004).",
  "type": "object",
  "definitions": {
    "ApiEndpoint": {
      "type": "object",
      "description": "API endpoint definition for DevPortal",
      "required": ["path", "method", "operation_id"],
      "properties": {
        "path": {
          "type": "string",
          "pattern": "^/api/v[0-9]+/",
          "description": "API path (e.g., /api/v1/findings)"
        },
        "method": {
          "type": "string",
          "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
        },
        "operation_id": {
          "type": "string",
          "description": "Unique operation identifier for SDK generation"
        },
        "summary": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "deprecated": {
          "type": "boolean",
          "default": false
        },
        "deprecation_info": {
          "$ref": "#/definitions/DeprecationInfo"
        },
        "authentication": {
          "$ref": "#/definitions/AuthenticationRequirement"
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Required OAuth2 scopes"
        },
        "rate_limit": {
          "$ref": "#/definitions/RateLimitConfig"
        },
        "request": {
          "$ref": "#/definitions/RequestSpec"
        },
        "responses": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/definitions/ResponseSpec"
          }
        },
        "examples": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/EndpointExample"
          }
        }
      }
    },
    "DeprecationInfo": {
      "type": "object",
      "description": "Deprecation details for sunset planning",
      "properties": {
        "deprecated_at": {
          "type": "string",
          "format": "date"
        },
        "sunset_at": {
          "type": "string",
          "format": "date"
        },
        "replacement": {
          "type": "string",
          "description": "Replacement endpoint path"
        },
        "migration_guide": {
          "type": "string",
          "format": "uri",
          "description": "Link to migration documentation"
        },
        "reason": {
          "type": "string"
        }
      }
    },
    "AuthenticationRequirement": {
      "type": "object",
      "description": "Authentication requirements for endpoint",
      "properties": {
        "required": {
          "type": "boolean",
          "default": true
        },
        "schemes": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": ["bearer", "api_key", "oauth2", "mtls", "basic"]
          }
        },
        "oauth2_flows": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": ["authorization_code", "client_credentials", "device_code"]
          }
        }
      }
    },
    "RateLimitConfig": {
      "type": "object",
      "description": "Rate limiting configuration",
      "properties": {
        "requests_per_minute": {
          "type": "integer",
          "minimum": 1
        },
        "requests_per_hour": {
          "type": "integer",
          "minimum": 1
        },
        "burst_limit": {
          "type": "integer",
          "minimum": 1
        },
        "tier": {
          "type": "string",
          "enum": ["free", "standard", "premium", "enterprise"],
          "description": "Rate limit tier"
        }
      }
    },
    "RequestSpec": {
      "type": "object",
      "description": "Request specification",
      "properties": {
        "content_types": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": ["application/json"]
        },
        "body_schema": {
          "type": "string",
          "description": "JSON Schema $ref for request body"
        },
        "parameters": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ParameterSpec"
          }
        },
        "headers": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/HeaderSpec"
          }
        }
      }
    },
    "ParameterSpec": {
      "type": "object",
      "description": "Parameter specification",
      "required": ["name", "in"],
      "properties": {
        "name": {
          "type": "string"
        },
        "in": {
          "type": "string",
          "enum": ["path", "query", "header", "cookie"]
        },
        "required": {
          "type": "boolean",
          "default": false
        },
        "description": {
          "type": "string"
        },
        "schema": {
          "type": "object",
          "description": "JSON Schema for parameter"
        },
        "example": {}
      }
    },
    "HeaderSpec": {
      "type": "object",
      "description": "Header specification",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string"
        },
        "required": {
          "type": "boolean",
          "default": false
        },
        "description": {
          "type": "string"
        },
        "example": {
          "type": "string"
        }
      }
    },
    "ResponseSpec": {
      "type": "object",
      "description": "Response specification",
      "properties": {
        "description": {
          "type": "string"
        },
        "content_types": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "body_schema": {
          "type": "string",
          "description": "JSON Schema $ref for response body"
        },
        "headers": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/HeaderSpec"
          }
        }
      }
    },
    "EndpointExample": {
      "type": "object",
      "description": "Example request/response pair",
      "properties": {
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "request": {
          "type": "object",
          "additionalProperties": true
        },
        "response": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "ApiService": {
      "type": "object",
      "description": "API service definition for DevPortal",
      "required": ["service_id", "name", "version", "endpoints"],
      "properties": {
        "service_id": {
          "type": "string",
          "description": "Unique service identifier"
        },
        "name": {
          "type": "string",
          "description": "Human-readable service name"
        },
        "description": {
          "type": "string"
        },
        "version": {
          "type": "string",
          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
        },
        "base_url": {
          "type": "string",
          "format": "uri"
        },
        "openapi_url": {
          "type": "string",
          "format": "uri",
          "description": "URL to OpenAPI spec"
        },
        "documentation_url": {
          "type": "string",
          "format": "uri"
        },
        "status": {
          "type": "string",
          "enum": ["stable", "beta", "alpha", "deprecated", "sunset"]
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "endpoints": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ApiEndpoint"
          }
        },
        "webhooks": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/WebhookDefinition"
          }
        }
      }
    },
    "WebhookDefinition": {
      "type": "object",
      "description": "Webhook event definition",
      "required": ["event_type", "payload_schema"],
      "properties": {
        "event_type": {
          "type": "string",
          "description": "Event type (e.g., finding.created)"
        },
        "description": {
          "type": "string"
        },
        "payload_schema": {
          "type": "string",
          "description": "JSON Schema $ref for webhook payload"
        },
        "example_payload": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "SdkConfig": {
      "type": "object",
      "description": "SDK generator configuration",
      "required": ["language", "package_name"],
      "properties": {
        "language": {
          "type": "string",
          "enum": ["typescript", "python", "go", "java", "csharp", "ruby", "php"]
        },
        "package_name": {
          "type": "string"
        },
        "package_version": {
          "type": "string"
        },
        "output_directory": {
          "type": "string"
        },
        "generator_options": {
          "type": "object",
          "additionalProperties": true,
          "description": "Language-specific generator options"
        },
        "custom_templates": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Custom template paths"
        }
      }
    },
    "SdkGeneratorRequest": {
      "type": "object",
      "description": "Request to generate SDK from API spec",
      "required": ["service_id", "sdk_configs"],
      "properties": {
        "service_id": {
          "type": "string"
        },
        "openapi_spec_url": {
          "type": "string",
          "format": "uri"
        },
        "sdk_configs": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SdkConfig"
          },
          "minItems": 1
        },
        "include_examples": {
          "type": "boolean",
          "default": true
        },
        "include_tests": {
          "type": "boolean",
          "default": true
        }
      }
    },
    "SdkGeneratorResult": {
      "type": "object",
      "description": "Result of SDK generation",
      "required": ["job_id", "status"],
      "properties": {
        "job_id": {
          "type": "string",
          "format": "uuid"
        },
        "status": {
          "type": "string",
          "enum": ["pending", "running", "completed", "failed"]
        },
        "started_at": {
          "type": "string",
          "format": "date-time"
        },
        "completed_at": {
          "type": "string",
          "format": "date-time"
        },
        "artifacts": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SdkArtifact"
          }
        },
        "errors": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "SdkArtifact": {
      "type": "object",
      "description": "Generated SDK artifact",
      "required": ["language", "artifact_url"],
      "properties": {
        "language": {
          "type": "string"
        },
        "package_name": {
          "type": "string"
        },
        "version": {
          "type": "string"
        },
        "artifact_url": {
          "type": "string",
          "format": "uri"
        },
        "checksum": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$"
        },
        "registry_url": {
          "type": "string",
          "format": "uri",
          "description": "Package registry URL (npm, pypi, etc.)"
        }
      }
    },
    "DevPortalCatalog": {
      "type": "object",
      "description": "Full API catalog for DevPortal",
      "required": ["catalog_id", "version", "services"],
      "properties": {
        "catalog_id": {
          "type": "string"
        },
        "version": {
          "type": "string"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "services": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ApiService"
          }
        },
        "global_tags": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TagDefinition"
          }
        },
        "authentication_info": {
          "$ref": "#/definitions/AuthenticationInfo"
        }
      }
    },
    "TagDefinition": {
      "type": "object",
      "description": "Tag definition for categorization",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "external_docs": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "AuthenticationInfo": {
      "type": "object",
      "description": "Global authentication information",
      "properties": {
        "oauth2_authorization_url": {
          "type": "string",
          "format": "uri"
        },
        "oauth2_token_url": {
          "type": "string",
          "format": "uri"
        },
        "api_key_header": {
          "type": "string",
          "default": "X-API-Key"
        },
        "documentation_url": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "ApiCompatibilityReport": {
      "type": "object",
      "description": "API compatibility check report",
      "required": ["report_id", "checked_at", "result"],
      "properties": {
        "report_id": {
          "type": "string",
          "format": "uuid"
        },
        "checked_at": {
          "type": "string",
          "format": "date-time"
        },
        "base_version": {
          "type": "string"
        },
        "target_version": {
          "type": "string"
        },
        "result": {
          "type": "string",
          "enum": ["compatible", "breaking", "minor_changes"]
        },
        "breaking_changes": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ApiChange"
          }
        },
        "non_breaking_changes": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ApiChange"
          }
        }
      }
    },
    "ApiChange": {
      "type": "object",
      "description": "Individual API change",
      "required": ["change_type", "path"],
      "properties": {
        "change_type": {
          "type": "string",
          "enum": [
            "endpoint_added",
            "endpoint_removed",
            "parameter_added",
            "parameter_removed",
            "parameter_type_changed",
            "response_changed",
            "schema_changed",
            "deprecation_added"
          ]
        },
        "path": {
          "type": "string"
        },
        "method": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "severity": {
          "type": "string",
          "enum": ["breaking", "warning", "info"]
        }
      }
    }
  },
  "properties": {
    "catalog": {
      "$ref": "#/definitions/DevPortalCatalog"
    }
  },
  "examples": [
    {
      "catalog": {
        "catalog_id": "stellaops-api-catalog",
        "version": "2025.10.0",
        "updated_at": "2025-12-06T10:00:00Z",
        "services": [
          {
            "service_id": "findings-ledger",
            "name": "Findings Ledger",
            "description": "Vulnerability findings storage and query service",
            "version": "1.0.0",
            "base_url": "https://api.stellaops.io/findings",
            "openapi_url": "https://api.stellaops.io/findings/.well-known/openapi.json",
            "status": "stable",
            "tags": ["findings", "vulnerabilities", "ledger"],
            "endpoints": [
              {
                "path": "/api/v1/findings",
                "method": "GET",
                "operation_id": "listFindings",
                "summary": "List findings with pagination and filtering",
                "tags": ["findings"],
                "authentication": {
                  "required": true,
                  "schemes": ["bearer", "oauth2"]
                },
                "scopes": ["findings:read"],
                "rate_limit": {
                  "requests_per_minute": 100,
                  "tier": "standard"
                },
                "request": {
                  "parameters": [
                    {
                      "name": "page",
                      "in": "query",
                      "required": false,
                      "schema": {
                        "type": "integer",
                        "default": 1
                      }
                    },
                    {
                      "name": "limit",
                      "in": "query",
                      "required": false,
                      "schema": {
                        "type": "integer",
                        "default": 50,
                        "maximum": 200
                      }
                    }
                  ]
                },
                "responses": {
                  "200": {
                    "description": "Paginated list of findings",
                    "content_types": ["application/json"]
                  },
                  "401": {
                    "description": "Unauthorized"
                  }
                }
              }
            ]
          }
        ],
        "authentication_info": {
          "oauth2_authorization_url": "https://auth.stellaops.io/authorize",
          "oauth2_token_url": "https://auth.stellaops.io/token",
          "api_key_header": "X-StellaOps-API-Key"
        }
      }
    }
  ]
}