{
  "openapi": "3.1.0",
  "info": {
    "title": "YAIBOS public API",
    "version": "1.0.0",
    "summary": "Read-only JSON access to the YAIBOS open specification and implementation scorecard.",
    "description": "Static, read-only API for agents and tools. No authentication, no rate-limited keys, no write operations. Current spec version: 1.1.0-draft. The normative specification is Markdown at https://yaibos.com/SPEC.md.",
    "license": {
      "name": "CC-BY-4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "contact": {
      "name": "Samuel Michelot",
      "url": "https://yaibos.com/about"
    }
  },
  "externalDocs": {
    "description": "YAIBOS open specification (Markdown)",
    "url": "https://yaibos.com/SPEC.md"
  },
  "servers": [
    {
      "url": "https://yaibos.com"
    }
  ],
  "security": [],
  "paths": {
    "/api/v1/spec.json": {
      "get": {
        "operationId": "getSpec",
        "summary": "Get the YAIBOS spec metadata and its six pillars",
        "responses": {
          "200": {
            "description": "Spec metadata and pillars",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Spec"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed: the API is read-only",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/implementations.json": {
      "get": {
        "operationId": "listImplementations",
        "summary": "List the tools scored against the YAIBOS pillars",
        "description": "Qualitative scorecard. Grades are not conformance certification.",
        "responses": {
          "200": {
            "description": "Scoring criteria and scored implementations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Scorecard"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed: the API is read-only",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/SPEC.md": {
      "get": {
        "operationId": "getSpecMarkdown",
        "summary": "Get the full normative specification as Markdown",
        "responses": {
          "200": {
            "description": "Specification text",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pillar": {
        "type": "object",
        "required": [
          "id",
          "number",
          "title",
          "why",
          "core",
          "later"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "number": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "why": {
            "type": "string"
          },
          "core": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "[L1] Base requirements, summarized"
          },
          "later": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "[L2], [L3] and [Opt] requirements, summarized"
          }
        }
      },
      "Spec": {
        "type": "object",
        "required": [
          "name",
          "title",
          "version",
          "license",
          "specMarkdownUrl",
          "pillars"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "license": {
            "type": "string"
          },
          "specMarkdownUrl": {
            "type": "string",
            "format": "uri"
          },
          "specHtmlUrl": {
            "type": "string",
            "format": "uri"
          },
          "pillars": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Pillar"
            }
          }
        }
      },
      "Criterion": {
        "type": "object",
        "required": [
          "key",
          "label",
          "description"
        ],
        "properties": {
          "key": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "Implementation": {
        "type": "object",
        "required": [
          "name",
          "category",
          "harnessStatus",
          "grade",
          "summary",
          "verdict",
          "scores",
          "strengths",
          "gaps"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "harnessStatus": {
            "type": "string"
          },
          "grade": {
            "type": "string",
            "enum": [
              "A+",
              "A",
              "B+",
              "B",
              "B-",
              "C+",
              "C",
              "D+",
              "F"
            ]
          },
          "summary": {
            "type": "string"
          },
          "verdict": {
            "type": "string"
          },
          "scores": {
            "type": "object",
            "description": "Score from 0 to 5 per criterion key",
            "additionalProperties": {
              "type": "integer",
              "minimum": 0,
              "maximum": 5
            }
          },
          "strengths": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "gaps": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "repoUrl": {
            "type": "string",
            "format": "uri"
          },
          "securityAnalysisUrl": {
            "type": "string",
            "format": "uri"
          },
          "screenshots": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "src",
                "alt"
              ],
              "properties": {
                "src": {
                  "type": "string",
                  "format": "uri"
                },
                "alt": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Scorecard": {
        "type": "object",
        "required": [
          "specVersion",
          "criteria",
          "implementations"
        ],
        "properties": {
          "specVersion": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "criteria": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Criterion"
            }
          },
          "implementations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Implementation"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "status",
              "code",
              "message",
              "hint"
            ],
            "properties": {
              "status": {
                "type": "integer"
              },
              "code": {
                "type": "string",
                "enum": [
                  "not_found",
                  "method_not_allowed"
                ]
              },
              "message": {
                "type": "string"
              },
              "hint": {
                "type": "string",
                "description": "How to resolve the error"
              },
              "docs": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}