{
  "openapi": "3.1.0",
  "info": {
    "title": "Directory Context Specification API",
    "version": "1.0.0",
    "description": "OpenAPI 3.1 schema representation for Local Directory Context (.context.json)"
  },
  "paths": {
    "/api/v1/directorycontext/validate": {
      "post": {
        "summary": "Validate DirectoryContext Payload",
        "description": "Validates an arbitrary payload against the DirectoryContext schema contract.",
        "operationId": "validateDirectoryContext",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DirectoryContext"
              }
            }
          }
        },
        "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": {
      "DirectoryContext": {
        "title": "DirectoryContext",
        "description": "Local Directory Context (.context.json) Ground-Truth Anchor",
        "type": "object",
        "properties": {
          "$schema": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "design": {
            "description": "Design perspective: Why & What to build",
            "type": "object",
            "properties": {
              "capabilities": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "constraints": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "contracts": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "decisions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "intentRationale": {
                "type": "string"
              }
            }
          },
          "implementation": {
            "description": "Implementation perspective: How & Standards",
            "type": "object",
            "properties": {
              "actions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "consultedRefs": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "conventions": {
                "description": "Module coding and architecture conventions",
                "type": "object",
                "properties": {
                  "codingStandard": {
                    "type": "object",
                    "additionalProperties": {}
                  },
                  "designSystem": {
                    "description": "UI Design System and styling conventions",
                    "type": "object",
                    "properties": {
                      "preferredComponents": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "reference": {
                        "type": "string"
                      },
                      "tokenRules": {
                        "type": "string"
                      }
                    }
                  },
                  "errorHandling": {
                    "description": "Error handling and exception conventions",
                    "type": "object",
                    "properties": {
                      "errorBoundary": {
                        "type": "string"
                      },
                      "errorClass": {
                        "type": "string"
                      },
                      "maskSecretsInLogs": {
                        "type": "boolean"
                      },
                      "reference": {
                        "type": "string"
                      },
                      "userMessageRule": {
                        "type": "string"
                      }
                    }
                  },
                  "logging": {
                    "description": "Telemetry and audit logging conventions",
                    "type": "object",
                    "properties": {
                      "reference": {
                        "type": "string"
                      },
                      "requiredEvents": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "requiredFields": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              },
              "events": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "notesForNextWorker": {
                "type": "string"
              },
              "referenceImplementations": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "typeSpecs": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "lastWorker": {
            "type": "string"
          },
          "review": {
            "description": "Review perspective: Compliance & Invariant Verification",
            "type": "object",
            "properties": {
              "contractCompliance": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "invariantsToCheck": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "scope": {
            "description": "Relative path scope of this directory anchor",
            "type": "string",
            "minLength": 1
          },
          "updatedAt": {
            "type": "string"
          }
        },
        "required": [
          "scope"
        ]
      }
    }
  }
}