Your
Opinion.is

Offenes Umfrageformat

Ein offenes JSON-basiertes Format zur Definition von Umfragen (verwendet auf https://YourOpinion.is, aber frei für jedermann zur Implementierung)

Download als JSON-Schema oder Markdown (Geeignet für große Sprachmodelle):

  1. JSON Schema - https://youropinion.is/json-schema/latest
  2. Markdown auf Englisch - https://youropinion.is/docs/survey-format.md

Die aktuelle Formatversion ist 0.5, veröffentlicht am 2025-01-24.

Kernkonzepte

  • Sammlungen (Seiten): Umfragen sind in Sammlungen organisiert, die als Seiten oder Abschnitte fungieren. Eine Umfrage muss mindestens eine Sammlung enthalten.
  • Elemente: Einzelne Komponenten innerhalb einer Sammlung, wie Fragen, Textblöcke oder Elemente zur Ablaufsteuerung.
  • Assets: Wiederverwendbare Komponenten, wie vordefinierte Optionslisten oder Skalen, auf die von mehreren Fragen verwiesen werden kann.

Umfragestruktur

Eine Umfrage wird als JSON-Objekt mit der folgenden Struktur dargestellt:

{
    "$schema": "https://youropinion.is/json-schema/0.5",
    "$readme": "https://youropinion.is/docs/survey-format.md",
    "collections": {
        [collection-id]: {
            "name": "Sammlungsname",
            "elements": {
                [element-id]: {
                    "type": "Markdown", // Elementtyp: Markdown, SelectOne, SelectMany etc
                    "data": { ... }
                }
            },
            "displayOrder": [ ... ]     // Anzeigereihenfolge der Elemente
        }
    },
    "displayOrder": [ ... ],            // Anzeigereihenfolge der Sammlungen
    "assets": {
        [asset-id]: {
            "type": "options",          // Asset-Typ: options
            "data": { ... }             // Typspezifische Daten
        }
    }
}

Sammlungen

Die Eigenschaft collections ist ein Objekt, bei dem jeder Schlüssel eine eindeutige ID für eine Sammlung ist und der Wert ein Objekt ist, das diese Sammlung beschreibt:

"collections": {
  "collection-id-1": {
    "name": "Sammlungsname",
    "elements": { ... },
    "displayOrder": [ ... ]
  },
  "collection-id-2": {
    // ... eine weitere Sammlung ...
  }
}
  • name: Ein für Menschen lesbarer Name für die Sammlung (z. B. „Persönliche Informationen“, „Produktfeedback“). Wird dem Benutzer nicht angezeigt.
  • elements: Ein Objekt, das die einzelnen Elemente der Sammlung enthält. Jeder Schlüssel innerhalb von elements ist eine eindeutige ID für das Element. Der Wert ist ein Objekt, das das Element beschreibt (siehe „Elementtypen“ unten).
  • displayOrder: Ein Array von Element-IDs, das die Reihenfolge angibt, in der sie angezeigt werden sollen.

    Hinweis: Das displayOrder-Array fungiert als Filter und Sequenzer. Nur Elemente, deren IDs in displayOrder aufgeführt sind, werden dem Benutzer angezeigt. Es ist zulässig, Elemente im elements-Objekt definiert zu haben, die derzeit nicht in displayOrder enthalten sind; dies bedeutet lediglich, dass diese Elemente nicht angezeigt werden. Wenn displayOrder jedoch eine ID enthält, die im elements-Objekt nicht existiert, führt dies zu einem Fehler.

displayOrder

Ein Array von Sammlungs-IDs, das die Reihenfolge angibt, in der sie angezeigt werden sollen.

Hinweis: Das displayOrder-Array fungiert als Filter und Sequenzer. Nur Sammlungen, deren IDs in displayOrder aufgeführt sind, werden dem Benutzer angezeigt. Es ist zulässig, Sammlungen im collections-Objekt definiert zu haben, die derzeit nicht in displayOrder enthalten sind; dies bedeutet lediglich, dass diese Sammlungen nicht angezeigt werden. Wenn displayOrder jedoch eine ID enthält, die im collections-Objekt nicht existiert, führt dies zu einem Fehler.

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

Assets

Die Eigenschaft assets (optional) ermöglicht es Ihnen, wiederverwendbare Komponenten zu definieren, auf die von mehreren Fragen verwiesen werden kann. Dies ist besonders nützlich für Optionslisten.

"assets": {
  "options-asset-id-1": {
    "type": "options",
    "name": "Farboptionen",
    "data": {
      "options": {
        "red": { "label": "Rot" },
        "blue": { "label": "Blau" },
        "green": { "label": "Grün" },
        "yellow": { "label": "Gelb"}
      },
      "displayOrder": ["red", "blue", "green", "yellow"]
    }
  },
}

Elementtypen

Das elements-Objekt innerhalb jeder Sammlung enthält die einzelnen Komponenten der Umfrage. Jedes Element hat eine type- und eine data-Eigenschaft. Denken Sie daran, dass der Schlüssel für jedes Element innerhalb des elements-Objekts seine eindeutige Element-ID ist und die Reihenfolge durch das displayOrder-Array der Sammlung bestimmt wird.

Allgemeine Bausteine

Markdown

Zeigt formatierten Text unter Verwendung der Markdown-Syntax an.

{
    "type": "Markdown",
    "data": {
        "markdown": "# Willkommen zur Umfrage!\n\nBitte beantworten Sie die folgenden Fragen ehrlich."
    }
}

FlowControl

Ändert den ansonsten linearen Ausführungsablauf der Umfrage.

{
    "type": "FlowControl",
    "data": {
        "condition": {...}, // Siehe Abschnitt Bedingte Anweisungen
        "action": {
            "type": "survey-finish", // oder "survey-cancel", "page-finish", "page-jump"
            "anchor": "collection id" // wird mit page-jump verwendet
        }
    }
}

Fragetypen

Alle Fragetypen haben die folgende Grundstruktur, aber einige Fragetypen fügen zusätzliche Datenelemente hinzu, die spezifisch für den Fragetyp sind.

{
    "type": "...",
    "data": {
        "label": "Die Frage, wie sie dem Endbenutzer angezeigt wird?"
    }
}

String

Ein Texteingabefeld.

{
    "type": "String",
    "data": {
        // ... siehe gemeinsame Optionen
        "placeholder": "Namen eingeben", // Optional: Text wird als Platzhalter für das Eingabeelement angezeigt
        "multiline": false // Optional: true für einen mehrzeiligen Textbereich
    }
}

Number

Ein numerisches Eingabefeld.

Date

Ein Datumseingabefeld.

Boolean

Eine Ja/Nein-Frage, dargestellt durch ein Kontrollkästchen. Die Anforderung „erforderlich“ gilt nicht, da der Wert standardmäßig bereits auf „Nein“ gesetzt ist.

{
    "type": "Boolean",
    "data": {
        // ... siehe gemeinsame Optionen
        "description": "Ja, ich stimme zu" // Optional: Text, der neben dem Kontrollkästchen angezeigt wird
    }
}

SelectOne

Eine Multiple-Choice-Frage, bei der Benutzer nur eine Option auswählen können.

{
    "type": "SelectOne",
    "data": {
        // ... siehe gemeinsame Optionen
        "options": {
            "options": {
                "red": { "label": "Rot" },
                "blue": { "label": "Blau" }
            },
            "displayOrder": ["red", "blue"]
        }
    }
}

Sie können auch auf eine Optionsliste verweisen, indem Sie "options": { "$ref": "#/assets/asset-id/data" } verwenden.

SelectMany

Eine Multiple-Choice-Frage, bei der Benutzer mehrere Optionen auswählen können.

{
    "type": "SelectMany",
    "data": {
        // ... siehe gemeinsame Optionen
        "options": {
            "options": {
                "win": { "label": "Windows" },
                "mac": { "label": "macOS" }
            },
            "displayOrder": ["win", "mac"]
        },
        "other": true // Optional: Fügt eine "Andere"-Option mit Texteingabe hinzu
    }
}

Sie können auch auf eine Optionsliste verweisen, indem Sie "options": { "$ref": "#/assets/asset-id/data" } verwenden.

NPS (Net Promoter Score)

Eine Standard-NPS-Frage auf einer Skala von 0-10.