openapi: 3.0.3
info:
  title: FVAP.gov XML API
  description: >-
    The Federal Voting Assistance Program (FVAP) publishes XML feeds providing
    voter information by U.S. state and territory. Each jurisdiction exposes
    four datasets covering important info, deadline dates, ballot rules, and
    election offices, plus a combined electronic Voting Assistance Guide (eVAG).
  version: '1.0.0'
  contact:
    name: FVAP
    url: https://www.fvap.gov/
  license:
    name: Public Domain (U.S. Federal Government)
    url: https://www.usa.gov/government-works
servers:
  - url: https://www.fvap.gov
    description: FVAP production
tags:
  - name: Important Info
    description: General voting information for a jurisdiction.
  - name: Deadline Dates
    description: Election deadlines for a jurisdiction.
  - name: Ballot Rules
    description: State-specific ballot rules (FPCA, FWAB, VBR).
  - name: Election Offices
    description: Local election office contact information.
  - name: eVAG
    description: Combined electronic Voting Assistance Guide.
  - name: Schema
    description: XML schema definition.
paths:
  /xml-api/{state}/important-info.xml:
    get:
      tags:
        - Important Info
      summary: Get important voting information for a state or territory.
      description: Returns the FAQ-style important voting information XML feed for the specified jurisdiction.
      operationId: getImportantInfo
      parameters:
        - $ref: '#/components/parameters/State'
      responses:
        '200':
          description: Important info XML feed.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ImportantInfo'
  /xml-api/{state}/deadline-dates.xml:
    get:
      tags:
        - Deadline Dates
      summary: Get deadline dates for a state or territory.
      description: Returns the election deadlines XML feed for the specified jurisdiction.
      operationId: getDeadlineDates
      parameters:
        - $ref: '#/components/parameters/State'
      responses:
        '200':
          description: Deadline dates XML feed.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/DeadlineDates'
  /xml-api/{state}/ballot-rules.xml:
    get:
      tags:
        - Ballot Rules
      summary: Get ballot rules for a state or territory.
      description: Returns the FPCA, FWAB, and VBR ballot rules XML feed for the specified jurisdiction.
      operationId: getBallotRules
      parameters:
        - $ref: '#/components/parameters/State'
      responses:
        '200':
          description: Ballot rules XML feed.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/BallotRules'
  /xml-api/{state}/election-offices.xml:
    get:
      tags:
        - Election Offices
      summary: Get election offices for a state or territory.
      description: Returns the local election office contact information XML feed for the specified jurisdiction.
      operationId: getElectionOffices
      parameters:
        - $ref: '#/components/parameters/State'
      responses:
        '200':
          description: Election offices XML feed.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ElectionOffices'
  /xml-api/{state}/evag.xml:
    get:
      tags:
        - eVAG
      summary: Get the combined eVAG feed for a state or territory.
      description: >-
        Returns the combined electronic Voting Assistance Guide (eVAG) XML feed
        bundling important info, deadline dates, ballot rules, and election
        offices for the specified jurisdiction.
      operationId: getEvag
      parameters:
        - $ref: '#/components/parameters/State'
      responses:
        '200':
          description: Combined eVAG XML feed.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Evag'
  /xml-api/api-schema.xsd:
    get:
      tags:
        - Schema
      summary: Get the XML schema definition for the FVAP feeds.
      description: Returns the XSD describing the structure of all FVAP XML feeds.
      operationId: getApiSchema
      responses:
        '200':
          description: XSD schema document.
          content:
            application/xml:
              schema:
                type: string
components:
  parameters:
    State:
      name: state
      in: path
      required: true
      description: U.S. state, district, or territory name (PascalCase, e.g. Alabama, NewYork, PuertoRico, DistrictOfColumbia).
      schema:
        type: string
  schemas:
    ImportantInfo:
      type: object
      description: FAQ-style important voting information.
      properties:
        questions:
          type: array
          items:
            type: object
            properties:
              question:
                type: string
              answer:
                type: string
    DeadlineDates:
      type: object
      description: Election deadline dates collection.
      properties:
        deadline-dates:
          type: array
          items:
            $ref: '#/components/schemas/DeadlineDate'
    DeadlineDate:
      type: object
      properties:
        election-type:
          type: string
        voting-request-type:
          type: string
        voter-type:
          type: string
        location:
          type: string
        date:
          type: string
          format: date
          nullable: true
    BallotRules:
      type: object
      description: Ballot rules grouped into FPCA, FWAB, and VBR sections.
      properties:
        fpca:
          type: array
          items:
            $ref: '#/components/schemas/BallotRule'
        fwab:
          type: array
          items:
            $ref: '#/components/schemas/BallotRule'
        vbr:
          type: array
          items:
            $ref: '#/components/schemas/BallotRule'
    BallotRule:
      type: object
      properties:
        label:
          type: string
        instructions:
          type: string
    ElectionOffices:
      type: object
      properties:
        election-offices:
          type: array
          items:
            $ref: '#/components/schemas/ElectionOffice'
    ElectionOffice:
      type: object
      properties:
        jurisdiction:
          type: string
        jurisdiction-type:
          type: string
        fax:
          type: string
        email:
          type: string
        street:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
    Evag:
      type: object
      description: Combined electronic Voting Assistance Guide bundling all four sections.
      properties:
        important-info:
          $ref: '#/components/schemas/ImportantInfo'
        deadline-dates:
          $ref: '#/components/schemas/DeadlineDates'
        ballot-rules:
          $ref: '#/components/schemas/BallotRules'
        election-offices:
          $ref: '#/components/schemas/ElectionOffices'