{
  "openapi": "3.1.0",
  "info": {
    "title": "DateKit Data API",
    "summary": "Read-only UK date maths and bank-holiday data.",
    "description": "Machine-readable UK calendar and time tools: an age calculator, a date-difference calculator (with Monday-to-Friday working days), statutory UK holiday entitlement (the 5.6 weeks rule and the 12.07% method), the long-weekend maximiser, and the 2026 UK bank holidays. Every number is computed from first principles or drawn from the official source (gov.uk Bank Holidays, the Working Time Regulations 1998). Read-only, no authentication, no PII, CC BY 4.0. Also exposed as an MCP server at /mcp (see /.well-known/mcp.json).",
    "version": "2026-06-12",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "contact": {
      "name": "DateKit",
      "url": "https://example.datekit.placeholder/api/"
    }
  },
  "servers": [
    { "url": "https://example.datekit.placeholder", "description": "Production (placeholder until launch)" }
  ],
  "externalDocs": {
    "description": "Human-readable API documentation",
    "url": "https://example.datekit.placeholder/api/"
  },
  "paths": {
    "/api/age": {
      "get": {
        "operationId": "getAge",
        "summary": "Exact age from a date of birth",
        "description": "Returns the exact age in years, months and days plus total days lived, computed against today.",
        "parameters": [
          {
            "name": "dob",
            "in": "query",
            "required": true,
            "description": "Date of birth as YYYY-MM-DD.",
            "schema": { "type": "string", "format": "date" },
            "example": "1990-05-04"
          }
        ],
        "responses": {
          "200": {
            "description": "The computed age.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Age" } } }
          },
          "400": {
            "description": "Missing or invalid dob.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/api/date-difference": {
      "get": {
        "operationId": "getDateDifference",
        "summary": "Difference between two dates",
        "description": "Days, weeks, years, months and Monday-to-Friday working days between two dates. Weekends are excluded from working days; UK bank holidays are not deducted.",
        "parameters": [
          { "name": "from", "in": "query", "required": true, "description": "Start date as YYYY-MM-DD.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" },
          { "name": "to", "in": "query", "required": true, "description": "End date as YYYY-MM-DD.", "schema": { "type": "string", "format": "date" }, "example": "2026-12-31" }
        ],
        "responses": {
          "200": {
            "description": "The date difference.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DateDifference" } } }
          },
          "400": {
            "description": "Missing or invalid dates.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/api/holiday-entitlement": {
      "get": {
        "operationId": "getHolidayEntitlement",
        "summary": "UK statutory holiday entitlement",
        "description": "Provide daysPerWeek (with optional fullTimeEntitlement) for set-day workers, or hours for irregular and casual workers (the 12.07% method). Source: GOV.UK holiday entitlement and the Working Time Regulations 1998. General information, not employment advice.",
        "parameters": [
          { "name": "daysPerWeek", "in": "query", "required": false, "description": "Days worked per week, 1 to 7.", "schema": { "type": "number" }, "example": 3 },
          { "name": "fullTimeEntitlement", "in": "query", "required": false, "description": "Full-time scheme entitlement in days per year (default 28).", "schema": { "type": "number" }, "example": 28 },
          { "name": "hours", "in": "query", "required": false, "description": "Hours worked, for irregular or casual workers.", "schema": { "type": "number" }, "example": 120 }
        ],
        "responses": {
          "200": {
            "description": "The statutory entitlement.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entitlement" } } }
          },
          "400": {
            "description": "Missing or invalid parameters.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/api/long-weekend": {
      "get": {
        "operationId": "getLongWeekend",
        "summary": "Best leave dates around the 2026 UK bank holidays",
        "description": "Suggests the most efficient annual-leave dates to book around the 2026 UK bank holidays for a given leave budget and nation, so a few days off become a long run of consecutive days off. Source: gov.uk Bank Holidays.",
        "parameters": [
          { "name": "leaveDays", "in": "query", "required": true, "description": "Annual leave days to spend, 1 to 40.", "schema": { "type": "number" }, "example": 5 },
          { "name": "nation", "in": "query", "required": false, "description": "England and Wales (ew), Scotland (sct), or Northern Ireland (ni). Defaults to ew.", "schema": { "type": "string", "enum": ["ew", "sct", "ni"] }, "example": "ew" }
        ],
        "responses": {
          "200": {
            "description": "The suggested leave plan.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LongWeekend" } } }
          },
          "400": {
            "description": "Missing or invalid parameters.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/api/bank-holidays": {
      "get": {
        "operationId": "getBankHolidays",
        "summary": "2026 UK bank holidays",
        "description": "Returns the 2026 UK bank holidays. With no nation, returns all three nations; with nation = ew | sct | ni, returns just that nation's list. Source: gov.uk Bank Holidays.",
        "parameters": [
          { "name": "nation", "in": "query", "required": false, "description": "England and Wales (ew), Scotland (sct), or Northern Ireland (ni). Omit for all nations.", "schema": { "type": "string", "enum": ["ew", "sct", "ni"] }, "example": "sct" }
        ],
        "responses": {
          "200": {
            "description": "The bank-holiday list.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankHolidays" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Age": {
        "type": "object",
        "properties": {
          "schema_version": { "type": "string" },
          "source": { "type": "string", "format": "uri" },
          "license": { "type": "string", "format": "uri" },
          "years": { "type": "integer" },
          "months": { "type": "integer" },
          "days": { "type": "integer" },
          "totalDays": { "type": "integer" },
          "dob": { "type": "string", "format": "date" },
          "as_of": { "type": "string", "format": "date" }
        }
      },
      "DateDifference": {
        "type": "object",
        "properties": {
          "schema_version": { "type": "string" },
          "source": { "type": "string", "format": "uri" },
          "license": { "type": "string", "format": "uri" },
          "from": { "type": "string", "format": "date" },
          "to": { "type": "string", "format": "date" },
          "days": { "type": "integer" },
          "weeks": { "type": "number" },
          "years": { "type": "integer" },
          "months": { "type": "integer" },
          "workingDays": { "type": "integer" },
          "note": { "type": "string" }
        }
      },
      "Entitlement": {
        "type": "object",
        "properties": {
          "schema_version": { "type": "string" },
          "source": { "type": "string", "format": "uri" },
          "license": { "type": "string", "format": "uri" },
          "region": { "type": "string" },
          "basis": { "type": "string" },
          "mode": { "type": "string", "enum": ["days", "hours"] },
          "statutoryMinimumDays": { "type": "number" },
          "schemeProRataDays": { "type": "number" },
          "entitlementDays": { "type": "number" },
          "daysPerWeek": { "type": "number" },
          "fullTimeEntitlement": { "type": "number" },
          "hoursWorked": { "type": "number" },
          "accrualRate": { "type": "string" },
          "accruedHours": { "type": "number" },
          "accruedDaysApprox": { "type": "number" },
          "note": { "type": "string" }
        }
      },
      "LongWeekend": {
        "type": "object",
        "properties": {
          "schema_version": { "type": "string" },
          "source": { "type": "string", "format": "uri" },
          "license": { "type": "string", "format": "uri" },
          "bank_holidays_source": { "type": "string", "format": "uri" },
          "nation": { "type": "string", "enum": ["ew", "sct", "ni"] },
          "nationLabel": { "type": "string" },
          "leaveDaysGiven": { "type": "integer" },
          "leaveDaysUsed": { "type": "integer" },
          "leaveDaysRemaining": { "type": "integer" },
          "totalDaysOff": { "type": "integer" },
          "picks": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "bankHoliday": { "type": "string" },
                "bookLeave": { "type": "array", "items": { "type": "string" } },
                "daysOff": { "type": "integer" },
                "off_from": { "type": "string", "format": "date" },
                "off_to": { "type": "string", "format": "date" }
              }
            }
          },
          "note": { "type": "string" }
        }
      },
      "BankHolidays": {
        "type": "object",
        "properties": {
          "schema_version": { "type": "string" },
          "source": { "type": "string", "format": "uri" },
          "api": { "type": "string", "format": "uri" },
          "license": { "type": "string", "format": "uri" },
          "as_of": { "type": "string", "format": "date" },
          "year": { "type": "integer" },
          "single": { "type": "boolean" },
          "nations": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/NationHolidays" }
          },
          "events": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/BankHoliday" }
          }
        }
      },
      "NationHolidays": {
        "type": "object",
        "properties": {
          "nation": { "type": "string", "enum": ["ew", "sct", "ni"] },
          "nation_label": { "type": "string" },
          "year": { "type": "integer" },
          "count": { "type": "integer" },
          "events": { "type": "array", "items": { "$ref": "#/components/schemas/BankHoliday" } }
        }
      },
      "BankHoliday": {
        "type": "object",
        "properties": {
          "date": { "type": "string", "format": "date" },
          "title": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "detail": { "type": "string" }
        }
      }
    }
  }
}