# Open Survey Format

An open JSON-based format for defining surveys (used at [https://YourOpinion.is](https://YourOpinion.is), but free for anyone to implement)

Download as json-schema or markdown (Suitable for large language models):

1. JSON Schema - [https://youropinion.is/json-schema/latest](/json-schema/latest)
2. Markdown in English - [https://youropinion.is/docs/survey-format.md](/docs/survey-format.md)

_Current format version is **0.5**, published on **2025-01-24**._

## Core Concepts

- **Collections (Pages):** Surveys are organized into collections, which act as pages or sections. A survey must have at least one collection.
- **Elements:** Individual components within a collection, such as questions, text blocks, or control flow elements.
- **Assets:** Reusable components, such as predefined option lists or scales, that can be referenced by multiple questions.

## Survey Structure

A survey is represented as a JSON object with the following structure:

```json
{
    "$schema": "https://youropinion.is/json-schema/0.5",
    "$readme": "https://youropinion.is/docs/survey-format.md",
    "collections": {
        [collection-id]: {
            "name": "Collection Name",
            "elements": {
                [element-id]: {
                    "type": "Markdown", // Element type: Markdown, SelectOne, SelectMany etc
                    "data": { ... }
                }
            },
            "displayOrder": [ ... ]     // Element display order
        }
    },
    "displayOrder": [ ... ],            // Collections display order
    "assets": {
        [asset-id]: {
            "type": "options",          // Asset type: options
            "data": { ... }             // Type specific data
        }
    }
}
```

### Collections

The `collections` property is an object where each **key is a unique ID** for a collection, and the value is an object describing that collection:

```json
"collections": {
  "collection-id-1": {
    "name": "Collection Name",
    "elements": { ... },
    "displayOrder": [ ... ]
  },
  "collection-id-2": {
    // ... another collection ...
  }
}
```

- **`name`:** A human-readable name for the collection (e.g., "Personal Information", "Product Feedback"). Not shown to the user.
- **`elements`:** An object containing the individual elements of the collection. Each **key within `elements` is a unique ID** for the element. The value is an object describing the element (see "Element Types" below).
- **`displayOrder`:** An array of element IDs, specifying the order in which they should be displayed.
    > **Note:** The `displayOrder` array acts as a filter and a sequencer. Only elements whose IDs are listed in `displayOrder` will be shown to the user. It is valid to have elements defined in the `elements` object that are _not_ currently included in `displayOrder`; this simply means those elements are not displayed. However, if `displayOrder` contains an ID that does _not_ exist in the `elements` object, this will cause an error.

### displayOrder

An array of collection IDs, specifying the order in which they should be displayed.

> **Note:** The `displayOrder` array acts as a filter and a sequencer. Only collections whose IDs are listed in `displayOrder` will be shown to the user. It is valid to have collections defined in the `collections` object that are _not_ currently included in `displayOrder`; this simply means those elements are not displayed. However, if `displayOrder` contains an ID that does _not_ exist in the `collections` object, this will cause an error.

```json
"displayOrder": ["collection-id-1"]
```

### Assets

The `assets` property (optional) allows you to define reusable components that can be referenced by multiple questions. This is particularly useful for option lists.

```json
"assets": {
  "options-asset-id-1": {
    "type": "options",
    "name": "Colour Options",
    "data": {
      "options": {
        "red": { "label": "Red" },
        "blue": { "label": "Blue" },
        "green": { "label": "Green" },
        "yellow": { "label": "Yellow"}
      },
      "displayOrder": ["red", "blue", "green", "yellow"]
    }
  },
}
```

## Element Types

The `elements` object within each collection contains the individual components of the survey. Each element has a `type` and a `data` property. Remember that the _key_ for each element within the `elements` object is its unique element ID, and the order is determined by the collection's `displayOrder` array.

### General Building Blocks

#### Markdown

Displays formatted text using Markdown syntax.

```json
{
    "type": "Markdown",
    "data": {
        "markdown": "# Welcome to the Survey!\n\nPlease answer the following questions honestly."
    }
}
```

#### FlowControl

Changes the otherwise liner execution flow of the survey.

```json
{
    "type": "FlowControl",
    "data": {
        "condition": {...}, // See conditional statements section
        "action": {
            "type": "survey-finish", // or "survey-cancel", "page-finish", "page-jump"
            "anchor": "collection id" // used with page-jump
        }
    }
}
```

### Questions Types

All question types have basic structure as follows, but some question types add additional data elements that are specific to the questions type.

```json
{
    "type": "...",
    "data": {
        "label": "The question as shown to the end user?"
    }
}
```

#### String

A text input field.

```json
{
    "type": "String",
    "data": {
        // ... see shared options
        "placeholder": "Enter name", // Optional: text shows as placeholder for input element
        "multiline": false // Optional: true for a multi-line text area
    }
}
```

#### Number

A numeric input field.

#### Date

A date input field.

#### Boolean

A yes/no question, represented by checkbox. Required requirement does not apply as by default the value is already set to no.

```json
{
    "type": "Boolean",
    "data": {
        // ... see shared options
        "description": "Yes, I agree" // Optional: Text to be shown next to the checkbox
    }
}
```

#### SelectOne

A multiple-choice question where users can select only _one_ option.

```json
{
    "type": "SelectOne",
    "data": {
        // ... see shared options
        "options": {
            "options": {
                "red": { "label": "Red" },
                "blue": { "label": "Blue" }
            },
            "displayOrder": ["red", "blue"]
        }
    }
}
```

You can also reference an options list using `"options": { "$ref": "#/assets/asset-id/data" }`

#### SelectMany

A multiple-choice question where users can select _multiple_ options.

```json
{
    "type": "SelectMany",
    "data": {
        // ... see shared options
        "options": {
            "options": {
                "win": { "label": "Windows" },
                "mac": { "label": "macOS" }
            },
            "displayOrder": ["win", "mac"]
        },
        "other": true // Optional: Include an "Other" option with a text input
    }
}
```

You can also reference an options list using `"options": { "$ref": "#/assets/asset-id/data" }`

#### NPS (Net Promoter Score)

A standard NPS question, on a scale of 0-10.