Voting types

Each question in a process shapes its own ballot. You pick a named type and tune it with typeSetup, or drop to a raw ballotProtocol override for shapes that do not have a named preset yet. Because the type is per question, one process can mix a single-choice question with a multichoice question.

Named types¶

Set type and, optionally, typeSetup on the question:

// single choice: pick one of the choices
{ "type": "singlechoice",
  "choices": [ { "title": { "default": "Ada Lovelace" }, "value": 0 },
               { "title": { "default": "Alan Turing" }, "value": 1 } ] }

// multichoice: approve up to 2 of the choices
{ "type": "multichoice",
  "typeSetup": { "maxChoices": 2 },
  "choices": [ /* N options */ ] }

// ranked: rank all the choices, each rank used once
{ "type": "ranked",
  "choices": [ /* N options to rank */ ] }

// cumulative: split 100 credits across the choices, quadratic cost
{ "type": "cumulative",
  "typeSetup": { "budget": 100, "costExponent": 2 },
  "choices": [ /* N options to fund */ ] }

typeSetup fields:

Raw ballot override¶

The four named types above are presets over the same on-chain parameters. For a shape none of them expresses - or to reach a knob typeSetup has no field for, such as maxVoteOverwrites or costFromWeight - set ballotProtocol on the question instead. When present it takes priority over type/typeSetup and maps directly onto the on-chain election parameters. Note the field names differ from typeSetup: the raw override uses maxCount/maxValue/uniqueValues (protocol names), where typeSetup uses maxChoices/uniqueChoices.

Each named type is exactly one point in this space, so the table doubles as a map of what they emit over N choices:

So reach for the override when you need something off that map - a vote a voter may change, or a budget taken from each voter's census weight rather than a fixed number:

// budget derived from each voter's census weight, and votes may be changed twice
{ "ballotProtocol": {
    "maxCount": 4, "maxValue": 0,
    "costExponent": 2, "costFromWeight": true,
    "maxVoteOverwrites": 2
  },
  "choices": [ /* 4 options to fund */ ] }

Open-value choices¶

Mark one choice with "openValue": true to make it the question's open option - the classic "Other: ____" answer. A voter who picks it can attach a short free-text memo to their ballot, and organizers read those memos back with the results.

// "Other" collects free text; the other choices do not
{ "type": "singlechoice",
  "choices": [
    { "title": { "default": "Ada Lovelace" }, "value": 0 },
    { "title": { "default": "Alan Turing" }, "value": 1 },
    { "title": { "default": "Other" }, "value": 2, "openValue": true }
  ] }

The flag is only a marker on the choice - it does not change the ballot shape, the tally, or the protocol parameters. It declares where a memo belongs, so that the API can tell which memos answered this question and which came from voters who picked something else.

Rules:

• At most one choice per question may set it. Two is a 400.
• Supported on singlechoice, multichoice and cumulative. Not on ranked, and not on a question shaped only by a raw ballotProtocol that matches no named type - both are a 400. A memo is reported only when the ballot selected the open choice, and a ranked ballot ranks every choice, so there is nothing to select.
• openValue comes back on the public process and question reads, so a voter app can find the open choice and render a text input next to it without authenticating.

Voters attach the memo when they cast - see Casting votes. Organizers read them back from the results, and the results API returns them only to organizers - see Voter memos.

Reading the results¶

Whatever the type, a question's results come back as results[field][value]. Single choice reads discretely; multichoice reads the per-option results[i][1]; ranked reads index-weighted; cumulative sums each option's credits into results[i][0]. See Results for the response shape and the reading each type uses.

For the complete, machine-readable contract, see the OpenAPI specification.