{
  "openapi": "3.1.0",
  "info": {
    "title": "Achmed Esser Public Data API",
    "version": "1.0.0",
    "description": "Read-only static access to immutable covered procurement releases. This API describes covered Find a Tender and Contracts Finder records, not the whole UK procurement market."
  },
  "servers": [
    {
      "url": "https://achmedesser.com"
    }
  ],
  "paths": {
    "/api/v1/benchmarks/index.json": {
      "get": {
        "summary": "List immutable releases",
        "operationId": "listBenchmarkReleases",
        "responses": {
          "200": {
            "description": "Release index",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReleaseIndex"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/benchmarks/latest.json": {
      "get": {
        "summary": "Read the latest immutable release",
        "operationId": "getLatestBenchmarkRelease",
        "responses": {
          "200": {
            "description": "Latest release",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BenchmarkRelease"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/benchmarks/releases/{date}.json": {
      "get": {
        "summary": "Read one immutable closed-day release",
        "operationId": "getBenchmarkRelease",
        "parameters": [
          {
            "name": "date",
            "in": "path",
            "required": true,
            "description": "Closed Europe/London date",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Immutable release",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BenchmarkRelease"
                }
              }
            }
          },
          "404": {
            "description": "No passing release exists for that date"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ReleaseIndex": {
        "type": "object",
        "required": ["version", "series", "status", "items"],
        "properties": {
          "version": { "type": "string" },
          "series": { "const": "uk-public-procurement" },
          "status": { "type": "string" },
          "count": { "type": "integer", "minimum": 0 },
          "latest": { "type": ["object", "null"] },
          "items": { "type": "array", "items": { "type": "object" } }
        }
      },
      "Metric": {
        "type": "object",
        "required": ["id", "label", "value", "unit", "definition"],
        "properties": {
          "id": { "type": "string" },
          "label": { "type": "string" },
          "value": { "type": ["number", "null"] },
          "unit": { "type": "string" },
          "definition": { "type": "string" }
        }
      },
      "BenchmarkRelease": {
        "type": "object",
        "required": ["schema_version", "id", "series", "title", "status", "period", "coverage", "metrics", "sectors", "methodology", "limitations", "licence", "distributions"],
        "properties": {
          "schema_version": { "type": "string" },
          "id": { "type": "string" },
          "series": { "const": "uk-public-procurement" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "status": { "const": "observed-closed-period" },
          "period": { "type": "object" },
          "coverage": { "type": "object" },
          "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/Metric" } },
          "sectors": { "type": "array", "items": { "type": "object" } },
          "methodology": { "type": "object" },
          "limitations": { "type": "array", "items": { "type": "string" } },
          "licence": { "type": "object" },
          "distributions": { "type": "array", "items": { "type": "object" } }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Human-readable release method",
    "url": "https://achmedesser.com/data/method/"
  }
}