Spec / open-values-position
Open Values Position v0.2
One person's position on a question: where they stand, how sure they are, the strongest case against it in its holders' own words, and what would change their mind. The Socratic Hearth page makes it in the browser and the person keeps it; the Work Party can read it.
- Files people or tools write
- Status: draft
- Version: 0.2
- Format name in the file:
open-values-position
Draft. It may still change before it is called stable. A file someone writes by hand or with a tool, and keeps.
Who writes it and who reads it
Written by Futurism Institute sites: sites/futurism-institute/public/js/hearth.js. Read by Futurism Institute sites: sites/futurism-institute/public/js/work-party.js.
Fields
| Field | What it means | Type |
|---|---|---|
format required | Always "open-values-position". Tells a reader that this file is one person's position on a question. | always "open-values-position" |
version required | The version of the position format this file follows: 0.2, or 0.1 for files written before 26 Oct 2026. A reader of 0.2 also reads 0.1 files, which lack only optional fields. | string |
recorded required | The date the browser saved the file, YYYY-MM-DD. | string |
question | The question the position answers, as the person wrote it. | string |
position required | Where the person stands, in one or two sentences: the claim, not the argument for it. | string |
confidence | How firmly the position is held, as the page's slider set it. | number |
confidence_after_case_against | How firmly it is held after writing the strongest case against it. Present only if the second slider was moved. | number |
strongest_case_against | The strongest case against the position, written in words the people who hold that view would accept. | string |
would_change_my_mind | What would change the person's mind: something a person could go and check. | string |
about_line | The rule or line the question is about, copied in by the person. Present only when filled in. | string |
what_i_know | What the person knows about the question, including from their own experience. Present only when filled in. | string |
case_against_called_fair_by | The name or role of someone who disagrees and has said the case against is a fair statement of their view. Present only when filled in; nobody is contacted by the page. | string |
proposed_wording | The person's own rewording of the rule or line in about_line. Present only when filled in. | string |
look_again_on | A date to look at the position again, as YYYY-MM-DD. Present only when filled in. | string |
answering | Present only on a card written in answer to one that arrived by link: the question, position and recorded date of the card it answers. | object |
their_case_for_you | On an answering card: whether the other card's version of this writer's side was fair to them. Present only when answered. | one of "fair", "not fair" |
how_you_would_put_it | On an answering card: how this writer would put their own side, when the other card's version misses it. Present only when filled in. | string |
reasons | What the writer knew about the question, listed before choosing a side, each sorted for, against or unsure. Present only when filled in. Added in 0.2. | list of object |
A reader MUST ignore fields it does not know, so a file can carry more than this list and still be read. A writer MUST NOT change what a listed field means.
A file that passes
A 0.2 position may list the reasons its writer knew, each marked for, against or unsure.
{
"format": "open-values-position",
"version": "0.2",
"recorded": "2026-10-26",
"question": "Should the town library open on Sundays?",
"position": "Yes, for four hours in the afternoon.",
"confidence": 0.7,
"reasons": [
{
"text": "Students have nowhere quiet to work on weekends.",
"side": "for"
},
{
"text": "Sunday staffing costs time and a half.",
"side": "against"
}
]
}
A file that must be rejected
A reason's side must be for, against or unsure.
{
"format": "open-values-position",
"version": "0.2",
"recorded": "2026-10-26",
"question": "Should the town library open on Sundays?",
"position": "Yes, for four hours in the afternoon.",
"confidence": 0.7,
"reasons": [
{
"text": "It depends on the budget.",
"side": "maybe"
}
]
}
The schema
Its address is https://openvaluesstandard.org/schema/position-v0.2.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/position.schema.json.
The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are used as described in RFC 2119 and RFC 8174 when, and only when, they appear in capitals.
Whether this format fits your app is your call. The spec says what a file MUST hold. Which formats you read and write, and what your app does with them, is yours to decide.