{
  "openapi": "3.0.3",
  "info": {
    "title": "iban — IBAN Validator API",
    "description": "Validates an International Bank Account Number (ISO 13616): it normalises the input, checks the character set and the per-country length against the SWIFT IBAN Registry, and verifies the ISO 7064 MOD-97-10 checksum. Pure and offline: no external calls, no state. A malformed or checksum-failing IBAN is returned as a normal 200 result with valid=false and a plain-English reason.",
    "version": "1.0.0"
  },
  "servers": [
    { "url": "https://iban.benjamin-dreier.de", "description": "Production" }
  ],
  "paths": {
    "/v1/validate": {
      "get": {
        "summary": "Validate an IBAN",
        "operationId": "validate",
        "parameters": [
          {
            "name": "iban",
            "in": "query",
            "required": true,
            "description": "The IBAN to validate. Spaces are ignored and letters are case-insensitive.",
            "schema": { "type": "string" },
            "example": "DE89 3704 0044 0532 0130 00"
          }
        ],
        "responses": {
          "200": {
            "description": "Validation result. valid=true for a correct IBAN; valid=false with a reason otherwise.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ValidateResponse" },
                "examples": {
                  "valid": {
                    "summary": "A valid German IBAN",
                    "value": {
                      "iban": "DE89370400440532013000",
                      "valid": true,
                      "country_code": "DE",
                      "check_digits": "89",
                      "bban": "370400440532013000",
                      "formatted": "DE89 3704 0044 0532 0130 00",
                      "length": 22,
                      "expected_length": 22
                    }
                  },
                  "invalid": {
                    "summary": "Wrong check digits",
                    "value": {
                      "iban": "DE90370400440532013000",
                      "valid": false,
                      "reason": "checksum failed: the check digits do not match the account number (MOD-97 check)",
                      "country_code": "DE",
                      "check_digits": "90",
                      "bban": "370400440532013000",
                      "formatted": "DE90 3704 0044 0532 0130 00",
                      "length": 22,
                      "expected_length": 22
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The 'iban' parameter was missing.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "example": { "error": "missing 'iban' parameter" }
              }
            }
          }
        }
      }
    },
    "/healthz": {
      "get": {
        "summary": "Service health and version",
        "operationId": "health",
        "responses": {
          "200": { "description": "Service ready." }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ValidateResponse": {
        "type": "object",
        "required": ["iban", "valid"],
        "properties": {
          "iban": { "type": "string", "description": "The input after normalisation (spaces removed, upper-cased).", "example": "DE89370400440532013000" },
          "valid": { "type": "boolean", "example": true },
          "reason": { "type": "string", "description": "Why an invalid IBAN was rejected. Absent when valid.", "example": "wrong length for DE: expected 22 characters, got 21" },
          "country_code": { "type": "string", "example": "DE" },
          "check_digits": { "type": "string", "example": "89" },
          "bban": { "type": "string", "description": "Basic Bank Account Number: the country-specific remainder after the check digits.", "example": "370400440532013000" },
          "formatted": { "type": "string", "description": "The IBAN grouped into space-separated blocks of four.", "example": "DE89 3704 0044 0532 0130 00" },
          "length": { "type": "integer", "description": "Total length of the normalised input.", "example": 22 },
          "expected_length": { "type": "integer", "description": "Registered length for the country code, when the country is known.", "example": 22 }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "example": "missing 'iban' parameter" }
        }
      }
    }
  }
}