{
  "openapi": "3.1.0",
  "info": {
    "title": "How2Vote static data files",
    "version": "1",
    "license": {
      "name": "CC0-1.0",
      "identifier": "CC0-1.0"
    },
    "description": "Read-only static JSON files of the propositions, recorded party positions and candidate ballots shown on https://how2vote.au, published by National Digital. Each file carries the licence, attribution and source of the data it holds, and states what How2Vote changed. Propositions and positions: Vote data © They Vote For You (OpenAustralia Foundation), ODbL (ODbL-1.0), with National Digital's proposition wording and computed positions under the DbCL-1.0; the party names in positions.json are credited to the Australian Electoral Commission as their source. Candidates: Candidate and electorate data © Commonwealth of Australia (Australian Electoral Commission) (CC-BY-4.0). Full terms: https://github.com/National-Digital/how2vote.au/blob/main/LICENSE-DATA.md. This description itself is CC0-1.0."
  },
  "servers": [
    {
      "url": "https://how2vote.au"
    }
  ],
  "security": [],
  "paths": {
    "/data/index.json": {
      "get": {
        "operationId": "getIndex",
        "summary": "List the published files",
        "description": "Every election and the files published for it.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Index"
                }
              }
            }
          },
          "404": {
            "description": "No such file."
          }
        }
      }
    },
    "/data/{election}/propositions.json": {
      "get": {
        "operationId": "getPropositions",
        "summary": "Propositions for an election",
        "description": "The propositions in the order the site lists them. Open Database Licence v1.0.",
        "parameters": [
          {
            "name": "election",
            "in": "path",
            "required": true,
            "description": "Election id.",
            "schema": {
              "type": "string",
              "enum": [
                "2025",
                "2022",
                "2019"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PropositionsFile"
                }
              }
            }
          },
          "404": {
            "description": "No such file."
          }
        }
      }
    },
    "/data/{election}/positions.json": {
      "get": {
        "operationId": "getPositions",
        "summary": "Recorded party positions for an election",
        "description": "Each party's and independent's recorded position on each proposition, on a 1–5 scale. Open Database Licence v1.0; party names credited to the Australian Electoral Commission.",
        "parameters": [
          {
            "name": "election",
            "in": "path",
            "required": true,
            "description": "Election id.",
            "schema": {
              "type": "string",
              "enum": [
                "2025",
                "2022",
                "2019"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PositionsFile"
                }
              }
            }
          },
          "404": {
            "description": "No such file."
          }
        }
      }
    },
    "/data/{election}/candidates.json": {
      "get": {
        "operationId": "getCandidates",
        "summary": "Candidate ballots for an election",
        "description": "House candidates by electorate and Senate candidates by group, in ballot-paper order, for elections with a ballot. Creative Commons Attribution 4.0 International.",
        "parameters": [
          {
            "name": "election",
            "in": "path",
            "required": true,
            "description": "Election id.",
            "schema": {
              "type": "string",
              "enum": [
                "2025",
                "2022",
                "2019"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CandidatesFile"
                }
              }
            }
          },
          "404": {
            "description": "No such file."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Election": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "label",
          "year"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "year": {
            "type": "integer"
          },
          "date": {
            "type": "string"
          },
          "provisionalStage": {
            "type": "string"
          }
        }
      },
      "Source": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "organisation",
          "url"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "organisation": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        }
      },
      "Publisher": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "url"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        }
      },
      "Licence": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        }
      },
      "VoteProvenance": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "basis",
          "retrievedAt",
          "effectiveAsAt",
          "statement"
        ],
        "properties": {
          "basis": {
            "type": "string"
          },
          "retrievedAt": {
            "type": "string"
          },
          "effectiveAsAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "statement": {
            "type": "string"
          }
        }
      },
      "Index": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "format",
          "openapi",
          "licenseDetails",
          "publisher",
          "attributions",
          "elections"
        ],
        "properties": {
          "format": {
            "type": "integer",
            "const": 1
          },
          "openapi": {
            "type": "string"
          },
          "licenseDetails": {
            "type": "string"
          },
          "publisher": {
            "$ref": "#/components/schemas/Publisher"
          },
          "attributions": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "domain",
                "license",
                "attribution",
                "copyright"
              ],
              "properties": {
                "domain": {
                  "type": "string",
                  "enum": [
                    "vote-positions",
                    "candidate-ballots"
                  ]
                },
                "license": {
                  "$ref": "#/components/schemas/Licence"
                },
                "attribution": {
                  "type": "string"
                },
                "copyright": {
                  "type": "string"
                }
              }
            }
          },
          "elections": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "label",
                "year",
                "files"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "year": {
                  "type": "integer"
                },
                "date": {
                  "type": "string"
                },
                "provisionalStage": {
                  "type": "string"
                },
                "files": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "kind",
                      "url",
                      "dataVersion",
                      "license",
                      "attribution"
                    ],
                    "properties": {
                      "kind": {
                        "type": "string",
                        "enum": [
                          "propositions",
                          "positions",
                          "candidates"
                        ]
                      },
                      "url": {
                        "type": "string"
                      },
                      "dataVersion": {
                        "type": "string"
                      },
                      "license": {
                        "type": "string"
                      },
                      "attribution": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "PropositionsFile": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "format",
          "election",
          "dataVersion",
          "license",
          "attribution",
          "copyright",
          "source",
          "licenseDetails",
          "publisher",
          "modifications",
          "contentsLicense",
          "contentsNote",
          "propositions"
        ],
        "properties": {
          "format": {
            "type": "integer",
            "const": 1
          },
          "election": {
            "$ref": "#/components/schemas/Election"
          },
          "dataVersion": {
            "type": "string",
            "description": "Data version of the domain the file was built from."
          },
          "license": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "url"
            ],
            "properties": {
              "id": {
                "type": "string",
                "const": "ODbL-1.0"
              },
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "const": "https://opendatacommons.org/licenses/odbl/1-0/"
              }
            }
          },
          "attribution": {
            "type": "string",
            "const": "Vote data © They Vote For You (OpenAustralia Foundation), ODbL"
          },
          "copyright": {
            "type": "string"
          },
          "source": {
            "$ref": "#/components/schemas/Source"
          },
          "licenseDetails": {
            "type": "string"
          },
          "publisher": {
            "$ref": "#/components/schemas/Publisher"
          },
          "modifications": {
            "type": "string",
            "const": "Proposition wording adapted by How2Vote from They Vote For You policy descriptions; selection and wording are editorial (see https://how2vote.au/methodology)."
          },
          "contentsLicense": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "url"
            ],
            "properties": {
              "id": {
                "type": "string",
                "const": "DbCL-1.0"
              },
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "const": "https://opendatacommons.org/licenses/dbcl/1-0/"
              }
            }
          },
          "contentsNote": {
            "type": "string",
            "const": "National Digital licenses its contributions to this database (the adaptation of the proposition wording and the computed positions) under the DbCL, to the extent it has rights in them."
          },
          "provenance": {
            "$ref": "#/components/schemas/VoteProvenance"
          },
          "propositions": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "text",
                "url",
                "sourceUrl"
              ],
              "properties": {
                "id": {
                  "type": "integer",
                  "description": "They Vote For You policy id."
                },
                "text": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "sourceUrl": {
                  "type": "string"
                },
                "divisionCount": {
                  "type": "integer"
                },
                "divisionFirst": {
                  "type": "string"
                },
                "divisionLast": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "PositionsFile": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "format",
          "election",
          "dataVersion",
          "license",
          "attribution",
          "copyright",
          "source",
          "licenseDetails",
          "publisher",
          "modifications",
          "contentsLicense",
          "contentsNote",
          "attributions",
          "scale",
          "parties",
          "positions"
        ],
        "properties": {
          "format": {
            "type": "integer",
            "const": 1
          },
          "election": {
            "$ref": "#/components/schemas/Election"
          },
          "dataVersion": {
            "type": "string",
            "description": "Data version of the domain the file was built from."
          },
          "license": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "url"
            ],
            "properties": {
              "id": {
                "type": "string",
                "const": "ODbL-1.0"
              },
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "const": "https://opendatacommons.org/licenses/odbl/1-0/"
              }
            }
          },
          "attribution": {
            "type": "string",
            "const": "Vote data © They Vote For You (OpenAustralia Foundation), ODbL"
          },
          "copyright": {
            "type": "string"
          },
          "source": {
            "$ref": "#/components/schemas/Source"
          },
          "licenseDetails": {
            "type": "string"
          },
          "publisher": {
            "$ref": "#/components/schemas/Publisher"
          },
          "modifications": {
            "type": "string",
            "const": "Party positions computed by How2Vote from They Vote For You member agreement figures (see https://how2vote.au/methodology)."
          },
          "contentsLicense": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "url"
            ],
            "properties": {
              "id": {
                "type": "string",
                "const": "DbCL-1.0"
              },
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "const": "https://opendatacommons.org/licenses/dbcl/1-0/"
              }
            }
          },
          "contentsNote": {
            "type": "string",
            "const": "National Digital licenses its contributions to this database (the adaptation of the proposition wording and the computed positions) under the DbCL, to the extent it has rights in them."
          },
          "provenance": {
            "$ref": "#/components/schemas/VoteProvenance"
          },
          "attributions": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "appliesTo",
                "attribution",
                "source"
              ],
              "properties": {
                "appliesTo": {
                  "type": "string",
                  "const": "parties[].name where independent is false"
                },
                "attribution": {
                  "type": "string",
                  "const": "Registered party names © Commonwealth of Australia (Australian Electoral Commission)"
                },
                "source": {
                  "$ref": "#/components/schemas/Source"
                }
              }
            }
          },
          "scale": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "value",
                "stance"
              ],
              "properties": {
                "value": {
                  "type": "integer"
                },
                "stance": {
                  "type": "string"
                }
              }
            }
          },
          "parties": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "key",
                "name",
                "independent",
                "url"
              ],
              "properties": {
                "key": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "independent": {
                  "type": "boolean"
                },
                "url": {
                  "type": "string"
                }
              }
            }
          },
          "positions": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "propositionId",
                "parties"
              ],
              "properties": {
                "propositionId": {
                  "type": "integer"
                },
                "parties": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "party",
                      "position",
                      "stance"
                    ],
                    "properties": {
                      "party": {
                        "type": "string",
                        "description": "Key into `parties`."
                      },
                      "position": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 5
                      },
                      "stance": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "CandidatesFile": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "format",
          "election",
          "dataVersion",
          "license",
          "attribution",
          "copyright",
          "source",
          "licenseDetails",
          "publisher",
          "modifications",
          "provenance",
          "house",
          "senate"
        ],
        "properties": {
          "format": {
            "type": "integer",
            "const": 1
          },
          "election": {
            "$ref": "#/components/schemas/Election"
          },
          "dataVersion": {
            "type": "string",
            "description": "Data version of the domain the file was built from."
          },
          "license": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "url"
            ],
            "properties": {
              "id": {
                "type": "string",
                "const": "CC-BY-4.0"
              },
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "const": "https://creativecommons.org/licenses/by/4.0/"
              }
            }
          },
          "attribution": {
            "type": "string",
            "const": "Candidate and electorate data © Commonwealth of Australia (Australian Electoral Commission)"
          },
          "copyright": {
            "type": "string"
          },
          "source": {
            "$ref": "#/components/schemas/Source"
          },
          "licenseDetails": {
            "type": "string"
          },
          "publisher": {
            "$ref": "#/components/schemas/Publisher"
          },
          "modifications": {
            "type": "string",
            "const": "Restructured by How2Vote from the AEC candidate downloads: grouped by electorate (House) and by state and group (Senate), sorted by ballot position, the candidate field renamed to name, a trailing comma removed from single-name candidates, and no other fields kept."
          },
          "provenance": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "sources"
            ],
            "properties": {
              "sources": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "id",
                    "title",
                    "url"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    },
                    "publishedAt": {
                      "type": "string"
                    },
                    "retrievedAt": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "house": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "electorate",
                "state",
                "url",
                "candidates"
              ],
              "properties": {
                "electorate": {
                  "type": "string"
                },
                "state": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "candidates": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "position",
                      "name",
                      "party"
                    ],
                    "properties": {
                      "position": {
                        "type": "integer",
                        "description": "Position on the House ballot paper (1-based)."
                      },
                      "name": {
                        "type": "string",
                        "description": "Name as printed on the ballot paper."
                      },
                      "party": {
                        "type": "string",
                        "description": "Party as printed on the ballot paper. Blank means no party is printed; the site shows such a candidate as Independent."
                      }
                    }
                  }
                }
              }
            }
          },
          "senate": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "state",
                "url",
                "groups"
              ],
              "properties": {
                "state": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "groups": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "group",
                      "candidates"
                    ],
                    "properties": {
                      "group": {
                        "type": "string"
                      },
                      "candidates": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "additionalProperties": false,
                          "required": [
                            "position",
                            "name",
                            "party"
                          ],
                          "properties": {
                            "position": {
                              "type": "integer",
                              "description": "Position within the group (1-based)."
                            },
                            "name": {
                              "type": "string",
                              "description": "Name as printed on the ballot paper."
                            },
                            "party": {
                              "type": "string",
                              "description": "Party as printed on the ballot paper. Blank means no party is printed; the site shows such a candidate as Independent."
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}