Content structure¶

This section describes the file architecture and JSON format that composes a scenario. Knowledge of this structure is not necessary for using the Scenario Editor, but is useful for advanced modifications, debugging, or generating scenarios programmatically.

File architecture¶

ChoiceMap clearly separates the framework (code) from content (data). HTML files contain the application and should not be modified; all customizations happen through JSON files.

HTML files (framework)¶

The three HTML files are complete applications that require no modification:

These files load React and Tailwind CSS from CDN and read content from JSON files. It's not necessary (nor recommended) to modify them.

config.json (the director)¶

The config.json file is the entry point that tells the Navigator what to load:

{
    "scenario": "scenario-my-project.json",
    "theme": "theme.json",
    "showCredits": true
}

By changing the scenario value and reloading the Navigator, you switch to a different scenario without modifying anything else. The same applies to theme.

defaults.json (default values)¶

Contains all default values for the theme: colors, fonts, branding configuration. It's the "base theme" from which all others start.

{
    "brand": {
        "name": "",
        "logo": "",
        "website": ""
    },
    "colors": {
        "background": "#ffffff",
        "text": "#1f2937",
        "accent": "#6366f1"
    }
}

This file should not be modified. To customize appearance, create a separate theme file.

theme.json (customizations)¶

The theme file contains only customizations relative to defaults. The Navigator reads defaults.json first, then overwrites with values present in theme.json.

If theme.json contains only the company logo, all other values (colors, fonts) are taken from defaults.json:

{
    "brand": {
        "name": "Company XYZ",
        "logo": "images/logo.png"
    }
}

This approach allows creating minimal themes that specify only what changes.

shared-styles.css (editors only)¶

Contains CSS styles shared between Scenario Editor and Theme Editor. It's not used by the Navigator and doesn't need to be included when publishing a scenario for end users.

The scenario file¶

Each scenario is a JSON file with a well-defined structure:

{
    "meta": {
        "title": "Scenario title",
        "description": "Optional description",
        "author": "Author name"
    },
    "translations": {
        "step": "Step",
        "restart": "Start Over",
        "endOfPath": "End of this path",
        "resources": "Resources",
        "viewMap": "View Map",
        "mapOf": "Map of",
        "back": "Back",
        "download": "Download",
        "openLink": "Open",
        "watchVideo": "Watch"
    },
    "startNode": "start",
    "nodes": {
        "start": {
            "content": "# Welcome\n\nContent in **Markdown**.",
            "choices": [
                { "text": "First option", "next": "node_a" },
                { "text": "Second option", "next": "node_b" }
            ],
            "resources": []
        }
    }
}

Meta section¶

The meta section contains the scenario's descriptive information.

Translations section¶

Defines interface labels, allowing scenario localization in any language.

For a quiz, you could use "Question" instead of "Step" and "Try Again" instead of "Start Over".

startNode field¶

Indicates which node is the scenario's starting point. The value must correspond to a key present in the nodes object.

Typically "start" is used by convention, but it can be any valid identifier.

Nodes section¶

An object where each key is a node identifier and the value contains the node data.

Node identifier: each node's key is its unique ID, used internally for connections. Recommended conventions: - Only lowercase letters, numbers, and underscores - Descriptive but short names: intro, question_1, answer_ok - Avoid spaces and special characters

Node content: the content field contains text in Markdown format. For supported syntax, see Content.

To create line breaks in JSON, use \n:

"content": "First line\n\nSecond line after a space"

Node choices: the choices field is an array of objects defining choice buttons:

"choices": [
    { "text": "Button text", "next": "destination_node_id" }
]

• text: what the user reads on the button
• next: the destination node identifier

A node without choices (empty array []) is a terminal node.

Node resources: the resources field is optional and defines attachments:

"resources": [
    { "type": "download", "label": "Download PDF", "url": "docs/guide.pdf" },
    { "type": "link", "label": "Learn more", "url": "https://example.com" },
    { "type": "video", "label": "Video tutorial", "url": "https://youtube.com/watch?v=..." }
]

Validation¶

The Navigator shows errors if something doesn't work in JSON files. Common errors:

• Malformed JSON (missing commas, unclosed quotes)
• startNode pointing to a non-existent node
• Choices pointing to non-existent nodes
• Missing or incomplete translations section

The Scenario Editor always generates valid JSON, but manual modifications can introduce errors. In case of problems, verify syntax with an online JSON validator.