As you may have noticed from using the election site, there is no graphical wizard or anything for creating elections. Instead there is simply a form to upload files, along with a stern warning to check that the file follows the format. So, this document is the instruction manual for writing election specification files that follow the correct format.
The election files use the JSON format, a lightweight way of storing data in way that is both human- and machine-readable. You don't need to fully understand JSON to be able to make election files, but I recommend you at least look into it so that you know what it looks like in general.
I think the easiest way to show you how to make elections is through an example, so here's a demo election file that showcases all the supported features, which I will then go through explaining what everything means:
{
"name": "Demonstration Election",
"desc": "Is this a good demonstration election?",
"options": {
"yes": {
"text": "I think that this demonstration is suitable",
"link": "https://example.com/this-is-a-good-demo"
},
"no": {
"text": "I think that this demo is awful to be perfectly honest",
"link": "https://example.org/down-with-the-demo"
},
"other": {
"text": "I do not have any strong feelings on this matter"
}
},
"order": [
"yes", "other", "no"
],
"times": {
"start": "2018-05-28 10:40:00",
"end": "2018-07-30 10:00:00"
}
}The name field serves as the title of the election. It is displayed in big letters at the top of the election page, so don't make it too long.
As well as being the "desc"ription of the election, this field is also the question that the election is asking. It is displayed in normal-sized letters under the title, so make it as long as you want (within reason).
The options field should be an object, with the keys being the "internal" names of options (these need to be URL-safe, so no spaces or anything), and the values being an option object.
The option object has one required field, text, and one optional field, link.
The text of the option, as displayed to the user.
A URL to an information page about that option, such as a campaign page. Displayed to the user as a More info... link. If not present, no link will be displayed.
Which order the options should be presented in. Must be a list containing every "internal" name of every option, and nothing else.
Contains the start and end datetime strings, in UTC, in the RFC-3339 format, with the T between the date and time replaced by a space (in accordance with the note in RFC-3339 section 5.6). In other words, YYYY-MM-DD HH:MM:SS.