Your
Opinion.is

Open Survey Format

An open JSON-based format for defining surveys (used at 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
  2. Markdown in English - https://youropinion.is/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:

{
    "$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:

"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.

"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.

"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.

{
    "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.

{
    "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.

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

String

A text input field.

{
    "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.

{
    "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.

{
    "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.

{
    "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.