openapi: 3.1.0
info:
  title: Worldwide IDs API
  version: 0.1.0
  description: >-
    Generate and validate fake, format- and checksum-valid national and tax ID
    numbers for software testing — never-issued ranges where available,
    otherwise labelled synthetic. Free tier is anonymous and rate limited;
    higher limits require an API key. For testing only.
  license:
    name: For-testing-only
servers:
  - url: https://api.worldids.dev/v1
paths:
  /ids:
    get:
      operationId: listIds
      summary: List supported countries and identifier types
      responses:
        '200':
          description: All identifier specs
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/IdSpec' }
  /generate/{country}/{idType}:
    get:
      operationId: generateId
      summary: Generate fake-but-valid values
      parameters:
        - { name: country, in: path, required: true, schema: { type: string }, description: ISO 3166-1 alpha-2 code }
        - { name: idType, in: path, required: true, schema: { type: string }, description: Identifier slug, e.g. ssn }
        - { name: count, in: query, schema: { type: integer, minimum: 1, maximum: 10000, default: 1 } }
        - { name: format, in: query, schema: { type: string, enum: [dashed, plain], default: dashed } }
        - { name: seed, in: query, schema: { type: integer }, description: Optional seed for reproducible output }
      responses:
        '200':
          description: Generated values
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GenerateResult' }
        '404': { description: Unknown country/idType }
  /validate/{country}/{idType}:
    get:
      operationId: validateId
      summary: Validate a value's format and checksum
      parameters:
        - { name: country, in: path, required: true, schema: { type: string } }
        - { name: idType, in: path, required: true, schema: { type: string } }
        - { name: value, in: query, required: true, schema: { type: string } }
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ValidationResult' }
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    IdSpec:
      type: object
      properties:
        country: { type: string }
        countryName: { type: string }
        idType: { type: string }
        name: { type: string }
        mask: { type: string }
        length: { oneOf: [{ type: integer }, { type: array, items: { type: integer } }] }
        example: { type: string }
        checksumLabel: { type: string }
        strategy: { type: string, enum: [reserved, synthetic] }
        pattern: { type: string }
        verification: { type: string, enum: [verified, best-effort] }
    GenerateResult:
      type: object
      properties:
        country: { type: string }
        idType: { type: string }
        reserved: { type: boolean }
        note: { type: string }
        values: { type: array, items: { type: string } }
    ValidationResult:
      type: object
      properties:
        valid: { type: boolean }
        normalized: { type: string }
        checks: { type: object }