{
  "openapi": "3.1.0",
  "info": {
    "title": "Spec Platform Configuration Specification API",
    "version": "1.0.0",
    "description": "OpenAPI 3.1 schema representation for Spec Platform Config (spec-platform.config.json)"
  },
  "paths": {
    "/api/v1/specplatformconfig/validate": {
      "post": {
        "summary": "Validate SpecPlatformConfig Payload",
        "description": "Validates an arbitrary payload against the SpecPlatformConfig schema contract.",
        "operationId": "validateSpecPlatformConfig",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SpecPlatformConfig"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation passed successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "valid": {
                      "type": "boolean",
                      "const": true
                    }
                  },
                  "required": [
                    "valid"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Validation failed with schema constraint errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "valid": {
                      "type": "boolean",
                      "const": false
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "valid",
                    "errors"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SpecPlatformConfig": {
        "title": "SpecPlatformConfig",
        "description": "Root configuration schema for the Specification Management Platform (spec-platform.config.json)",
        "type": "object",
        "properties": {
          "$schema": {
            "type": "string"
          },
          "checkAnchors": {
            "type": "boolean",
            "default": true
          },
          "codeRoots": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "default": [
              "packages"
            ]
          },
          "contractRoots": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "docSnippets": {
            "description": "Verifiable code snippet markers configuration",
            "type": "object",
            "properties": {
              "allowedLanguages": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "markerPattern": {
                "type": "string"
              },
              "requireSnippets": {
                "type": "boolean",
                "default": false
              }
            },
            "additionalProperties": false
          },
          "documentRoots": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "default": [
              "docs"
            ]
          },
          "ignoredDirectories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "includeTests": {
            "type": "boolean",
            "default": false
          },
          "pairedDocs": {
            "description": "Bilingual paired documentation configuration (Context-Action convention)",
            "type": "object",
            "properties": {
              "enforceSymmetricLinks": {
                "type": "boolean",
                "default": true
              },
              "primaryDir": {
                "description": "Primary language directory, e.g. \"docs/en\"",
                "type": "string",
                "minLength": 1
              },
              "secondaryDir": {
                "description": "Secondary language directory, e.g. \"docs/ko\"",
                "type": "string",
                "minLength": 1
              },
              "subdirectories": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "primaryDir",
              "secondaryDir"
            ],
            "additionalProperties": false
          },
          "scopePolicy": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "permissive",
                  "recommended",
                  "strict"
                ]
              },
              {
                "type": "object",
                "properties": {
                  "rules": {
                    "description": "Custom link scope rules",
                    "type": "array",
                    "items": {
                      "type": "object",
                      "additionalProperties": {}
                    }
                  }
                },
                "required": [
                  "rules"
                ],
                "additionalProperties": false
              }
            ],
            "default": "recommended"
          }
        },
        "additionalProperties": false
      }
    }
  }
}