API docs by Redocly

Kalkulacka.1 schemas (0.0.0)

Schemas of data for voting advice applications.

Answer

https://schema.kalkulacka.one/answer.schema.json

Answer to a question of a calculator

The value of an answer is used solely for the purposes of the voting advice application, and therefore it intentionally doesn't differentiate between all possible real-world situations.

User answers are mapped as follows:

Answer Value
Yes true
No false
Skip undefined

Candidate answers are mapped slightly differently:

Answer Value
Yes true
No false
Neutral null

Vote mappings depend on the actual impact of each option on the outcome.

For example, in ordinary votes in the Parliament of the Czech Republic, abstaining has the same effect as voting against, while being absent reduces the quorum, so it has no direct effect on the result:

Vote Value
Yes true
No false
Abstain false
Absent null
Not member undefined

However, in certain cases, such as votes on constitutional laws, where a qualified majority is required, being absent has the same effect as voting against, so the mapping changes:

Vote Value
Yes true
No false
Abstain false
Absent false
Not member undefined

In the European Parliament, the result is based on votes cast, abstentions and absences are excluded from the count, so the mapping is as follows:

Vote Value
Yes true
No false
Abstain null
Absent null
questionId
required
string <uuid> (Question ID)

Unique identifier of an answered question in the format of UUID

Answer (boolean) or Answer (null) (Answer)

Yes (true), no (false) or neutral (null) answer to a question

isImportant
boolean (Is important?)

Whether a question was marked as important

respondent
string (Responded)
Enum: "user" "candidate" "expert"

Who answered a question

comment
string (Comment)

Respondent's comment to an answer

Array of objects (Sources) non-empty

Ordered list of sources for an answer

{
  • "questionId": "51115be7-246a-4f07-baf7-247ee81fde36",
  • "answer": true,
  • "isImportant": true,
  • "respondent": "user",
  • "comment": "string",
  • "sources": []
}

Answers

https://schema.kalkulacka.one/answers.schema.json

List of one or more answers

Array (non-empty)
questionId
required
string <uuid> (Question ID)

Unique identifier of an answered question in the format of UUID

Answer (boolean) or Answer (null) (Answer)

Yes (true), no (false) or neutral (null) answer to a question

isImportant
boolean (Is important?)

Whether a question was marked as important

respondent
string (Responded)
Enum: "user" "candidate" "expert"

Who answered a question

comment
string (Comment)

Respondent's comment to an answer

Array of objects (Sources) non-empty

Ordered list of sources for an answer

[
  • {
    }
]

Calculator group

https://schema.kalkulacka.one/calculator-group.schema.json

Group of two or more calculators

One of
required
Array of objects (Ordered list of calculators) non-empty
id
required
string <uuid> (calculator-group.schema_$defs-id)

Unique identifier of a calculator group in the format of UUID

key
required
string ($defs-key) ^[a-z0-9]+(-[a-z0-9]+)*$

Human-friendly unique key of a calculator group in the hyphen-separated lowercased format

object ($defs-election)

Reference to an election the calculator belongs to

Array of objects (variants) non-empty
createdAt
required
string <date-time> (createdAt)

Time of the creation of a calculator group in the ISO 8601 format

updatedAt
string <date-time> (updatedAt)

Time of the last update of a calculator group in the ISO 8601 format

publishedAt
string <date-time> (publishedAt)

Time when a calculator group should be published in the ISO 8601 format

title
string (title)

Title of a calculator group

shortTitle
required
string (shortTitle) <= 25 characters

Short title of a calculator group with a maximum of 25 characters

description
string (description)

Description of a calculator group

{
  • "calculators": [
    ],
  • "id": "cbc72c2e-ff2f-4ceb-bb41-a1a5dce7d4da",
  • "key": "prezidentske-2023",
  • "election": {
    },
  • "variants": [
    ],
  • "createdAt": "2021-01-01T00:00:00+01:00",
  • "updatedAt": "2021-01-01T00:00:00+01:00",
  • "publishedAt": "2021-01-01T00:00:00+01:00",
  • "title": "Prezidentské volby 2023",
  • "shortTitle": "Prezidentské 2023",
  • "description": "Volební kalkulačky pro obě kola prezidentských voleb 2023"
}

Calculator groups

https://schema.kalkulacka.one/calculator-groups.schema.json

List of calculator groups

Array
One of
required
Array of objects (Ordered list of calculators) non-empty
id
required
string <uuid> (calculator-group.schema_$defs-id)

Unique identifier of a calculator group in the format of UUID

key
required
string ($defs-key) ^[a-z0-9]+(-[a-z0-9]+)*$

Human-friendly unique key of a calculator group in the hyphen-separated lowercased format

object ($defs-election)

Reference to an election the calculator belongs to

Array of objects (variants) non-empty
createdAt
required
string <date-time> (createdAt)

Time of the creation of a calculator group in the ISO 8601 format

updatedAt
string <date-time> (updatedAt)

Time of the last update of a calculator group in the ISO 8601 format

publishedAt
string <date-time> (publishedAt)

Time when a calculator group should be published in the ISO 8601 format

title
string (title)

Title of a calculator group

shortTitle
required
string (shortTitle) <= 25 characters

Short title of a calculator group with a maximum of 25 characters

description
string (description)

Description of a calculator group

[
  • {
    }
]

Calculator

https://schema.kalkulacka.one/calculator.schema.json

Calculator is a set of questions, candidates and their answers

One of
key
required
string (calculator.schema_$defs-key) ^[a-z0-9]+(-[a-z0-9]+)*$

Human-friendly unique key of a standalone calculator in the hyphen-separated lowercased format

id
required
string <uuid> ($defs-id)

Unique identifier of a calculator in the format of UUID

version
string (version) ^\d+\.\d+\.\d+$

Semantic version of the calculator

createdAt
required
string <date-time> ($defs-createdAt)

Time of the creation of a calculator in the ISO 8601 format

updatedAt
string <date-time> ($defs-updatedAt)

Time of the last update of a calculator in the ISO 8601 format

publishedAt
string <date-time> ($defs-publishedAt)

Time when a calculator should be published in the ISO 8601 format

title
string ($defs-title)

Title of a calculator

shortTitle
required
string ($defs-shortTitle) <= 25 characters

Short title of a calculator with a maximum of 25 characters

description
string ($defs-description)

Description of a calculator

methodology
string (methodology)

Methodology of a calculator

intro
string (intro)

Intro text displayed before starting the calculator

tags
Array of strings (tags.schema) non-empty [ items [ 1 .. 25 ] characters ]

Ordered list of tags

Array of objects (images.schema) non-empty

List of images

object (checksums)

Checksums for calculator data

Array of objects (changes)

Changelog of the calculator data

Example
{
  • "key": "doprava-v-praze",
  • "id": "e2cf4fec-81e0-490c-a056-7f63177dc6a7",
  • "version": "1.2.3",
  • "createdAt": "2021-01-01T00:00:00+01:00",
  • "updatedAt": "2021-01-01T00:00:00+01:00",
  • "publishedAt": "2021-01-01T00:00:00+01:00",
  • "title": "2. kolo prezidentských voleb 2023",
  • "shortTitle": "Prezidentské (2. kolo)",
  • "description": "Volební kalkulačka pro 2. kolo prezidentských voleb 2023",
  • "methodology": "Pokud kandidát neodpověděl na otázku, jeho odpověď se nezapočítává do výsledku kalkulačky.",
  • "intro": "string",
  • "tags": [
    ],
  • "images": [
    ],
  • "checksums": {
    },
  • "changes": [
    ]
}

Calculators

https://schema.kalkulacka.one/calculators.schema.json

List of calculators

Array
One of
key
required
string (calculator.schema_$defs-key) ^[a-z0-9]+(-[a-z0-9]+)*$

Human-friendly unique key of a standalone calculator in the hyphen-separated lowercased format

id
required
string <uuid> ($defs-id)

Unique identifier of a calculator in the format of UUID

version
string (version) ^\d+\.\d+\.\d+$

Semantic version of the calculator

createdAt
required
string <date-time> ($defs-createdAt)

Time of the creation of a calculator in the ISO 8601 format

updatedAt
string <date-time> ($defs-updatedAt)

Time of the last update of a calculator in the ISO 8601 format

publishedAt
string <date-time> ($defs-publishedAt)

Time when a calculator should be published in the ISO 8601 format

title
string ($defs-title)

Title of a calculator

shortTitle
required
string ($defs-shortTitle) <= 25 characters

Short title of a calculator with a maximum of 25 characters

description
string ($defs-description)

Description of a calculator

methodology
string (methodology)

Methodology of a calculator

intro
string (intro)

Intro text displayed before starting the calculator

tags
Array of strings (tags.schema) non-empty [ items [ 1 .. 25 ] characters ]

Ordered list of tags

Array of objects (images.schema) non-empty

List of images

object (checksums)

Checksums for calculator data

Array of objects (changes)

Changelog of the calculator data

[
  • {
    }
]

Candidate

https://schema.kalkulacka.one/candidate.schema.json

Candidate for a calculator

Candidate is the subject which is used to calculate the match with the user's answers. It can be a person or an orgianization (e.g. party), but also any other entity (e.g. candidate list).

Candidate can contain references to persons or organizations, which are then used to present the candidate to the user.

It is also possible to nest the candidates into each other, which allows to present groupped candidates results. For example the top level candidate, e.g. party, can contain other candidates, e.g. members of a parliament. In case the answers are provided just for the nested candidates, the top level candidate answer is calculated as the average answer of the nested candidates. In case separate answers for the top level candidate are provided, top level and nested candidates result is independent.

id
required
string <uuid> (ID)

Unique identifier of a candidate in the format of UUID

required
Array of objects (References)

Ordered list of persons or organizations that are related to the candidate

displayName
string (Display name)

Display name of a candidate

Array of objects (images.schema) non-empty

List of images

motto
string (Motto)

Motto of a candidate

number
integer (Number)

Official candidate list (usually drawn) number assigned by a public authority

Array of objects (Nested candidates)

List of nested candidates, which can be used for aggregated answers if top-level candidate answers are not provided

{
  • "id": "11fee676-1eac-4948-a2fb-38e2b774f4b3",
  • "references": [
    ],
  • "displayName": "Jan Novák",
  • "images": [
    ],
  • "motto": "Za lepší budoucnost",
  • "number": 1,
  • "nestedCandidates": [
    ]
}

Candidates' answers

https://schema.kalkulacka.one/candidates-answers.schema.json

List of candidates' answers

pattern property
Array of objects (Answers) non-empty

List of one or more answers

{
  • "11fee676-1eac-4948-a2fb-38e2b774f4b3": [
    ]
}

Candidates

https://schema.kalkulacka.one/candidates.schema.json

List of one or more candidates

Array (non-empty)
id
required
string <uuid> (ID)

Unique identifier of a candidate in the format of UUID

required
Array of objects (References)

Ordered list of persons or organizations that are related to the candidate

displayName
string (Display name)

Display name of a candidate

Array of objects (images.schema) non-empty

List of images

motto
string (Motto)

Motto of a candidate

number
integer (Number)

Official candidate list (usually drawn) number assigned by a public authority

nestedCandidates
Array of objects (Nested candidates)

List of nested candidates, which can be used for aggregated answers if top-level candidate answers are not provided

[
  • {
    }
]

District

https://schema.kalkulacka.one/district.schema.json

Geographical area of an election

key
required
string (Key) ^[a-z0-9]+(-[a-z0-9]+)*$

Human-friendly unique key of a district in the hyphen-separated lowercased format

code
string (Code)

Official district code assigned by the election authority

{
  • "key": "praha",
  • "code": "554782"
}

Election

https://schema.kalkulacka.one/election.schema.json

Election provides various details about an election such as districts and rounds

id
required
string <uuid> (id)

Unique identifier of an election in the format of UUID

key
required
string (key) ^[a-z0-9]+(-[a-z0-9]+)*$

Human-friendly unique key of an election in the hyphen-separated lowercased format

createdAt
required
string <date-time> (election.schema_$defs-createdAt)

Time of the creation of an election in the ISO 8601 format

updatedAt
string <date-time> (election.schema_$defs-updatedAt)

Time of the last update of an election group in the ISO 8601 format

publishedAt
string <date-time> (election.schema_$defs-publishedAt)

Time when an election group should be published in the ISO 8601 format

title
required
string (election.schema_$defs-title)

Title of an election

shortTitle
required
string (election.schema_$defs-shortTitle) <= 25 characters

Short title of an election with a maximum of 25 characters

description
string (election.schema_$defs-description)

Description of an election

tags
Array of strings (tags.schema) non-empty [ items [ 1 .. 25 ] characters ]

Ordered list of tags

required
object ($defs-calculatorGroup)

Reference to a calculator group with election calculators

Array of objects (Ordered list of election districts) non-empty
Array of objects (Ordered list of election rounds) non-empty
Array of objects (Voting hours) non-empty

One or multiple voting hours for the election

{
  • "id": "ad9b73fc-e578-4b3a-9623-533d76224cbc",
  • "key": "prezidentske-2023",
  • "createdAt": "2021-01-01T00:00:00+01:00",
  • "updatedAt": "2021-01-01T00:00:00+01:00",
  • "publishedAt": "2021-01-01T00:00:00+01:00",
  • "title": "Prezidentské volby 2023",
  • "shortTitle": "Prezidentské 2023",
  • "description": "Volební kalkulačky pro obě kola prezidentských voleb 2023",
  • "tags": [
    ],
  • "calculatorGroup": {
    },
  • "districts": [
    ],
  • "rounds": [
    ],
  • "votingHours": [
    ]
}

Elections

https://schema.kalkulacka.one/elections.schema.json

List of elections

Array
id
required
string <uuid> (id)

Unique identifier of an election in the format of UUID

key
required
string (key) ^[a-z0-9]+(-[a-z0-9]+)*$

Human-friendly unique key of an election in the hyphen-separated lowercased format

createdAt
required
string <date-time> (election.schema_$defs-createdAt)

Time of the creation of an election in the ISO 8601 format

updatedAt
string <date-time> (election.schema_$defs-updatedAt)

Time of the last update of an election group in the ISO 8601 format

publishedAt
string <date-time> (election.schema_$defs-publishedAt)

Time when an election group should be published in the ISO 8601 format

title
required
string (election.schema_$defs-title)

Title of an election

shortTitle
required
string (election.schema_$defs-shortTitle) <= 25 characters

Short title of an election with a maximum of 25 characters

description
string (election.schema_$defs-description)

Description of an election

tags
Array of strings (tags.schema) non-empty [ items [ 1 .. 25 ] characters ]

Ordered list of tags

required
object ($defs-calculatorGroup)

Reference to a calculator group with election calculators

Array of objects (Ordered list of election districts) non-empty
Array of objects (Ordered list of election rounds) non-empty
Array of objects (Voting hours) non-empty

One or multiple voting hours for the election

[
  • {
    }
]

Images

https://schema.kalkulacka.one/images.schema.json

List of images

Array (non-empty)
type
required
string (Image type)
Enum: "avatar" "logo" "portrait" "opengraph" "twitter"

Type of the image

required
object (Image paths)

Relative paths to image files for different sizes

width
integer (Image width) >= 1

Width of the original image in pixels

height
integer (Image height) >= 1

Height of the original image in pixels

alt
string (Alternative text)

Alternative text for the image, used for accessibility

[
  • {
    }
]

Organization

https://schema.kalkulacka.one/organization.schema.json

Organization is a group of people, for example a political party, a movement, etc.

Any of
id
required
string <uuid> (ID)

Unique identifier of an organization in the format of UUID

name
required
string (Name)

Organization's preferred full name

officialName
string (Short name)

Organization's official name with an unlimited length

shortName
required
string (Short name) <= 25 characters

Organization's short name with max. 25 characters

abbreviation
string (Abbreviation) <= 15 characters

Organization's abbreviation with max. 15 characters

sortName
string

A name to use in a lexicographically ordered list

alternateNames
Array of strings

Alternate names to use for example in search

Array of objects (images.schema) non-empty

List of images

Array of Person (object) or Organization (object) (Members) non-empty

List of members of an organization

{
  • "id": "5fb7d561-6e93-45c2-9c75-6a1f2b11deb4",
  • "name": "string",
  • "officialName": "string",
  • "shortName": "string",
  • "abbreviation": "string",
  • "sortName": "string",
  • "alternateNames": [
    ],
  • "images": [
    ],
  • "members": [
    ]
}

Organizations

https://schema.kalkulacka.one/organizations.schema.json

List of organizations

Array
Any of
id
required
string <uuid> (ID)

Unique identifier of an organization in the format of UUID

name
required
string (Name)

Organization's preferred full name

officialName
string (Short name)

Organization's official name with an unlimited length

shortName
required
string (Short name) <= 25 characters

Organization's short name with max. 25 characters

abbreviation
string (Abbreviation) <= 15 characters

Organization's abbreviation with max. 15 characters

sortName
string

A name to use in a lexicographically ordered list

alternateNames
Array of strings

Alternate names to use for example in search

Array of objects (images.schema) non-empty

List of images

Array of Person (object) or Organization (object) (Members) non-empty

List of members of an organization

[
  • {
    }
]

Person

https://schema.kalkulacka.one/person.schema.json

A human being

Any of
id
required
string <uuid> (ID)

Unique identifier of a person in the format of UUID

name
required
string (Name)

Person's preferred full name

familyName
string

Family name (last name)

givenName
string

Given name (first name)

additionalName
string

Additional name (middle name)

honorificPrefix
string

Honorifics preceding a person's name

honorificSuffix
string

Honorifics following a person's name

sortName
string

A name to use in a lexicographically ordered list

alternateNames
Array of strings

Alternate names to use for example in search

Array of objects (images.schema) non-empty

List of images

Array of objects (Member of) non-empty

List of organizations a person is a member of

{
  • "id": "5ee570e9-fdc6-4af1-8af5-a5e5589c44a6",
  • "name": "string",
  • "familyName": "string",
  • "givenName": "string",
  • "additionalName": "string",
  • "honorificPrefix": "string",
  • "honorificSuffix": "string",
  • "sortName": "string",
  • "alternateNames": [
    ],
  • "images": [
    ],
  • "memberOf": [
    ]
}

Persons

https://schema.kalkulacka.one/persons.schema.json

List of persons

Array
Any of
id
required
string <uuid> (ID)

Unique identifier of a person in the format of UUID

name
required
string (Name)

Person's preferred full name

familyName
string

Family name (last name)

givenName
string

Given name (first name)

additionalName
string

Additional name (middle name)

honorificPrefix
string

Honorifics preceding a person's name

honorificSuffix
string

Honorifics following a person's name

sortName
string

A name to use in a lexicographically ordered list

alternateNames
Array of strings

Alternate names to use for example in search

Array of objects (images.schema) non-empty

List of images

Array of objects (Member of) non-empty

List of organizations a person is a member of

[
  • {
    }
]

Question

https://schema.kalkulacka.one/question.schema.json

Question for a calculator

id
required
string <uuid> (ID)

Unique identifier of a question in the format of UUID

title
required
string (Title)

Title of a question

statement
required
string (Statement)

A statement to agree or disagree with, should not be phrased as a question with question mark

detail
string (Detail)

A detailed description or an explanation of a question

tags
Array of strings (tags.schema) non-empty [ items [ 1 .. 25 ] characters ]

Ordered list of tags

{
  • "id": "51115be7-246a-4f07-baf7-247ee81fde36",
  • "title": "Zrušení Senátu",
  • "statement": "Senát by se měl zrušit",
  • "detail": "Senát by se měl zrušit, protože je zbytečný a jeho činnost je nákladná.",
  • "tags": [
    ]
}

Questions

https://schema.kalkulacka.one/questions.schema.json

List of one or more questions

Array (non-empty)
id
required
string <uuid> (ID)

Unique identifier of a question in the format of UUID

title
required
string (Title)

Title of a question

statement
required
string (Statement)

A statement to agree or disagree with, should not be phrased as a question with question mark

detail
string (Detail)

A detailed description or an explanation of a question

tags
Array of strings (tags.schema) non-empty [ items [ 1 .. 25 ] characters ]

Ordered list of tags

[
  • {
    }
]

Round

https://schema.kalkulacka.one/round.schema.json

Round of an election

number
required
integer (Number) >= 0

Round ordinal number from 0

Array of objects (Voting hours) non-empty

One or multiple voting hours for the round

{
  • "number": 0,
  • "votingHours": [
    ]
}

Tags

https://schema.kalkulacka.one/tags.schema.json

Ordered list of tags

Array (non-empty)
string (Tag) [ 1 .. 25 ] characters

Tag with max. 25 characters

[
  • "prezidentské"
]

Time period

https://schema.kalkulacka.one/time-period.schema.json

Time period from–to

required
Start time (string) or Start time (string) (Start time)

Start date (or time) of a voting period in the ISO 8601 format

required
End time (string) or End time (string) (End time)

End date (or time) of a voting period in the ISO 8601 format

{
  • "start": "2023-01-13",
  • "end": "2023-01-13"
}

Variant

https://schema.kalkulacka.one/variant.schema.json

Variant of a calculator

key
required
string (Key) ^[a-z0-9]+(-[a-z0-9]+)*$

Human-friendly unique key of a variant in the hyphen-separated lowercased format

{
  • "key": "pro-fajnsmekry"
}