Format Ouvert d'Enquête

Un format ouvert basé sur JSON pour définir les enquêtes (utilisé sur https://YourOpinion.is, mais libre d'implémentation pour tous)

Télécharger en tant que schéma JSON ou markdown (Adapté aux grands modèles de langage) :

Schéma JSON - https://youropinion.is/json-schema/latest
Markdown en Anglais - https://youropinion.is/docs/survey-format.md

La version actuelle du format est 0.5, publiée le 2025-01-24.

Concepts Fondamentaux

Collections (Pages) : Les enquêtes sont organisées en collections, qui agissent comme des pages ou des sections. Une enquête doit avoir au moins une collection.
Éléments : Composants individuels au sein d'une collection, tels que des questions, des blocs de texte ou des éléments de contrôle de flux.
Ressources (Assets) : Composants réutilisables, tels que des listes d'options ou des échelles prédéfinies, qui peuvent être référencés par plusieurs questions.

Structure de l'Enquête

Une enquête est représentée comme un objet JSON avec la structure suivante :

{
    "$schema": "https://youropinion.is/json-schema/0.5",
    "$readme": "https://youropinion.is/docs/survey-format.md",
    "collections": {
        [collection-id]: {
            "name": "Nom de la Collection",
            "elements": {
                [element-id]: {
                    "type": "Markdown", // Type d'élément : Markdown, SelectOne, SelectMany etc
                    "data": { ... }
                }
            },
            "displayOrder": [ ... ]     // Ordre d'affichage des éléments
        }
    },
    "displayOrder": [ ... ],            // Ordre d'affichage des collections
    "assets": {
        [asset-id]: {
            "type": "options",          // Type de ressource : options
            "data": { ... }             // Données spécifiques au type
        }
    }
}

Collections

La propriété collections est un objet où chaque clé est un ID unique pour une collection, et la valeur est un objet décrivant cette collection :

"collections": {
  "collection-id-1": {
    "name": "Nom de la Collection",
    "elements": { ... },
    "displayOrder": [ ... ]
  },
  "collection-id-2": {
    // ... autre collection ...
  }
}

name : Un nom lisible par l'homme pour la collection (par ex., "Informations Personnelles", "Retour Produit"). Non montré à l'utilisateur.
elements : Un objet contenant les éléments individuels de la collection. Chaque clé dans elements est un ID unique pour l'élément. La valeur est un objet décrivant l'élément (voir "Types d'Éléments" ci-dessous).
displayOrder : Un tableau d'IDs d'éléments, spécifiant l'ordre dans lequel ils doivent être affichés.

Note : Le tableau displayOrder agit comme un filtre et un séquenceur. Seuls les éléments dont les IDs sont listés dans displayOrder seront montrés à l'utilisateur. Il est valide d'avoir des éléments définis dans l'objet elements qui ne sont pas actuellement inclus dans displayOrder ; cela signifie simplement que ces éléments ne sont pas affichés. Cependant, si displayOrder contient un ID qui n'existe pas dans l'objet elements, cela provoquera une erreur.

displayOrder

Un tableau d'IDs de collections, spécifiant l'ordre dans lequel elles doivent être affichées.

Note : Le tableau displayOrder agit comme un filtre et un séquenceur. Seules les collections dont les IDs sont listés dans displayOrder seront montrées à l'utilisateur. Il est valide d'avoir des collections définies dans l'objet collections qui ne sont pas actuellement incluses dans displayOrder ; cela signifie simplement que ces éléments ne sont pas affichés. Cependant, si displayOrder contient un ID qui n'existe pas dans l'objet collections, cela provoquera une erreur.

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

Ressources (`Assets`)

La propriété assets (optionnelle) vous permet de définir des composants réutilisables qui peuvent être référencés par plusieurs questions. Ceci est particulièrement utile pour les listes d'options.

"assets": {
  "options-asset-id-1": {
    "type": "options",
    "name": "Options de Couleur",
    "data": {
      "options": {
        "red": { "label": "Rouge" },
        "blue": { "label": "Bleu" },
        "green": { "label": "Vert" },
        "yellow": { "label": "Jaune"}
      },
      "displayOrder": ["red", "blue", "green", "yellow"]
    }
  },
}

Types d'Éléments

L'objet elements dans chaque collection contient les composants individuels de l'enquête. Chaque élément a une propriété type et data. Rappelez-vous que la clé pour chaque élément dans l'objet elements est son ID d'élément unique, et l'ordre est déterminé par le tableau displayOrder de la collection.

Blocs de Construction Généraux

Markdown

Affiche du texte formaté en utilisant la syntaxe Markdown.

{
    "type": "Markdown",
    "data": {
        "markdown": "# Bienvenue à l'Enquête !\n\nVeuillez répondre honnêtement aux questions suivantes."
    }
}

FlowControl

Modifie le flux d'exécution autrement linéaire de l'enquête.

{
    "type": "FlowControl",
    "data": {
        "condition": {...}, // Voir la section sur les instructions conditionnelles
        "action": {
            "type": "survey-finish", // ou "survey-cancel", "page-finish", "page-jump"
            "anchor": "collection id" // utilisé avec page-jump
        }
    }
}

Types de Questions

Tous les types de questions ont une structure de base comme suit, mais certains types de questions ajoutent des éléments de données supplémentaires spécifiques au type de question.

{
    "type": "...",
    "data": {
        "label": "La question telle qu'affichée à l'utilisateur final ?"
    }
}

String

Un champ de saisie de texte.

{
    "type": "String",
    "data": {
        // ... voir options partagées
        "placeholder": "Entrez le nom", // Optionnel : texte affiché comme indicateur pour l'élément de saisie
        "multiline": false // Optionnel : true pour une zone de texte multiligne
    }
}

Number

Un champ de saisie numérique.

Date

Un champ de saisie de date.

Boolean

Une question oui/non, représentée par une case à cocher. L'exigence de réponse obligatoire ne s'applique pas car la valeur par défaut est déjà définie sur non.

{
    "type": "Boolean",
    "data": {
        // ... voir options partagées
        "description": "Oui, j'accepte" // Optionnel : Texte à afficher à côté de la case à cocher
    }
}

SelectOne

Une question à choix multiples où les utilisateurs ne peuvent sélectionner qu'une seule option.

{
    "type": "SelectOne",
    "data": {
        // ... voir options partagées
        "options": {
            "options": {
                "red": { "label": "Rouge" },
                "blue": { "label": "Bleu" }
            },
            "displayOrder": ["red", "blue"]
        }
    }
}

Vous pouvez également référencer une liste d'options en utilisant "options": { "$ref": "#/assets/asset-id/data" }

SelectMany

Une question à choix multiples où les utilisateurs peuvent sélectionner plusieurs options.

{
    "type": "SelectMany",
    "data": {
        // ... voir options partagées
        "options": {
            "options": {
                "win": { "label": "Windows" },
                "mac": { "label": "macOS" }
            },
            "displayOrder": ["win", "mac"]
        },
        "other": true // Optionnel : Inclure une option "Autre" avec une saisie de texte
    }
}