StoryRampSchema.json

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "StoryRAMP Config Schema",
    "type": "object",
    "additionalProperties": false,

    "$defs": {
        "slide": {
            "type": "object",
            "description": "A universal StoryRAMP slide",
            "properties": {
                "title": {
                    "type": "string",
                    "description": "The title for the slide."
                },
                "panel": {
                    "$ref": "#/$defs/panel"
                },
                "backgroundImage": {
                    "type": "string",
                    "description": "An image to display in the background of the slide."
                },
                "includeInToc": {
                    "type": "boolean",
                    "description": "Optional attribute that indicates whether or not to include slide in table of contents. Defaults to true.",
                    "default": true
                }
            },
            "required": ["title", "panel"]
        },

        "panel": {
            "type": "array",
            "description": "A single slide component",
            "items": {
                "oneOf": [
                    {
                        "$ref": "#/$defs/textPanel"
                    },
                    {
                        "$ref": "#/$defs/mapPanel"
                    },
                    {
                        "$ref": "#/$defs/multimediaPanel"
                    },
                    {
                        "$ref": "#/$defs/dqvchartPanel"
                    },
                    {
                        "$ref": "#/$defs/dynamicPanel"
                    },
                    {
                        "$ref": "#/$defs/interactiveImagePanel"
                    },
                    {
                        "$ref": "#/$defs/interactiveMapPanel"
                    }
                ]
            },
            "properties": {
                "width": {
                    "type": "number",
                    "description": "The width of the panel inside the slide (between 0 and 100)."
                },
                "customStyles": {
                    "type": "string",
                    "description": "Optional style string to add to the panel."
                },
                "cssClasses": {
                    "type": "string",
                    "description": "Optional string of css classes to add to the panel."
                }
            },
            "minItems": 1,
            "maxItems": 2
        },

        "textPanel": {
            "type": "object",
            "description": "A text slide component.",
            "properties": {
                "title": {
                    "type": "string",
                    "description": "The title for the text panel."
                },
                "titleTag": {
                    "type": "string",
                    "description": "An optional tag to use for the panel title. If not supplied h2 is used.",
                    "default": "h2"
                },
                "content": {
                    "type": "string",
                    "description": "The main text body."
                },
                "type": {
                    "type": "string",
                    "enum": ["text"]
                },
                "textColour": {
                    "type": "string",
                    "description": "The colour of the text. Defaults to black.",
                    "default": "#000000"
                }
            },
            "required": ["content", "type", "title"]
        },

        "dynamicPanel": {
            "type": "object",
            "description": "A dynamic slide component.",
            "properties": {
                "title": {
                    "type": "string",
                    "description": "The title for the text panel."
                },
                "titleTag": {
                    "type": "string",
                    "description": "An optional tag to use for the panel title. If not supplied h2 is used.",
                    "default": "h2"
                },
                "content": {
                    "type": "string",
                    "description": "The main text body."
                },
                "children": {
                    "type": "array",
                    "description": "The panels to display dynamically.",
                    "items": {
                        "$ref": "#/$defs/dynamicChildItem"
                    },
                    "minItems": 1
                },
                "type": {
                    "type": "string",
                    "enum": ["dynamic"]
                },
                "textColour": {
                    "type": "string",
                    "description": "The colour of the text. Defaults to black.",
                    "default": "#000000"
                },
                "reversed": {
                    "type": "boolean",
                    "description": "If true, the text slide and dynamic slide will be swapped.",
                    "default": false
                },
                "hideReturn": {
                    "type": "boolean",
                    "description": "If true, the return button will be hidden.",
                    "default": false
                },
                "contentWidth": {
                    "type": "string",
                    "description": "If provided, the text slide width will be set to this value. Caps out at the page width on mobile mode.",
                    "default": ""
                }
            },
            "required": ["content", "type", "children", "title"]
        },

        "dynamicChildItem": {
            "type": "object",
            "description": "A child screen of a dynamic panel. Contains an ID and a panel config.",
            "properties": {
                "id": "string",
                "panel": {
                    "oneOf": [
                        {
                            "$ref": "#/$defs/textPanel"
                        },
                        {
                            "$ref": "#/$defs/mapPanel"
                        },
                        {
                            "$ref": "#/$defs/multimediaPanel"
                        },
                        {
                            "$ref": "#/$defs/dqvchartPanel"
                        }
                    ]
                }
            },
            "required": ["id", "panel"]
        },

        "interactiveImagePanel": {
            "type": "object",
            "description": "An interactive image slide component.",
            "properties": {
                "title": {
                    "type": "string",
                    "description": "The title for the text panel."
                },
                "titleTag": {
                    "type": "string",
                    "description": "An optional tag to use for the panel title. If not supplied h2 is used.",
                    "default": "h2"
                },
                "panels": {
                    "type": "array",
                    "description": "The panels to display dynamically.",
                    "items": {
                        "$ref": "#/$defs/dynamicChildItem"
                    },
                    "minItems": 1
                },
                "images": {
                    "type": "array",
                    "description": "The images to replace the original with.",
                    "items": {
                        "$ref": "#/$defs/interactiveImage"
                    },
                    "minItems": 1
                },
                "zones": {
                    "type": "array",
                    "description": "The zones of the image to make interactive.",
                    "items": {
                        "$ref": "#/$defs/interactiveImageZone"
                    },
                    "minItems": 1
                },
                "defaultImage": {
                    "$ref": "#/$defs/interactiveImage"
                },
                "reversed": {
                    "type": "boolean",
                    "description": "If true, the text slide and dynamic slide will be swapped.",
                    "default": false
                },
                "hideReturn": {
                    "type": "boolean",
                    "description": "If true, the return button will be hidden.",
                    "default": false
                },
                "contentWidth": {
                    "type": "string",
                    "description": "If provided, the text slide width will be set to this value. Caps out at the page width on mobile mode.",
                    "default": ""
                },
                "width": {
                    "type": "number",
                    "description": "The image width."
                },
                "height": {
                    "type": "number",
                    "description": "The image height."
                },
                "caption": {
                    "type": "string",
                    "description": "Supporting text content for the image."
                },
                "class": {
                    "type": "string",
                    "description": "Styling class properties for the image."
                }
            },
            "required": ["type", "panels", "zones", "defaultImage"]
        },

        "interactiveImage": {
            "type": "object",
            "description": "An image used in an interactive image panel.",
            "properties": {
                "src": {
                    "type": "string",
                    "description": "The source of the image."
                },
                "id": {
                    "type": "string",
                    "description": "An identifier for the image, used by interactive zones."
                },
                "altText": {
                    "type": "string",
                    "description": "Alt text for the image."
                }
            },
            "required": ["src", "id"]
        },

        "interactiveImageZone": {
            "type": "object",
            "description": "One zone of an interactive image.",
            "properties": {
                "panelId": {
                    "type": "string",
                    "description": "The id of the panel to display dynamically."
                },
                "imageId": {
                    "type": "string",
                    "description": "The id of the image to show on interaction."
                },
                "top": {
                    "type": "string",
                    "description": "The 'top' css style to apply to the element. Must include units, % is preferred."
                },
                "left": {
                    "type": "string",
                    "description": "The 'left' css style to apply to the element. Must include units, % is preferred."
                },
                "width": {
                    "type": "string",
                    "description": "The 'width' css style to apply to the element. Must include units, % is preferred."
                },
                "height": {
                    "type": "string",
                    "description": "The 'height' css style to apply to the element. Must include units, % is preferred."
                },
                "class": {
                    "type": "string",
                    "description": "A css class string to apply to the element"
                },
                "disableHover": {
                    "type": "boolean",
                    "description": "Whether to disable the hover interaction. Main usecase is to only show a different image on click/keyboard input.",
                    "default": "false"
                }
            },
            "required": ["panelId", "top", "left", "width", "height"]
        },

        "multimediaPanel": {
            "type": "object",
            "description": "A multimedia slide component.",
            "oneOf": [
                {
                    "$ref": "#/$defs/multimediaImage"
                },
                {
                    "$ref": "#/$defs/multimediaVideo"
                },
                {
                    "$ref": "#/$defs/multimediaAudio"
                },
                {
                    "$ref": "#/$defs/multimediaSlideshow"
                }
            ],
            "properties": {
                "fullscreen": {
                    "type": "boolean",
                    "description": "Specifies whether the panel can be expanded to full screen.",
                    "default": true
                }
            }
        },

        "mapPanel": {
            "type": "object",
            "description": "A map slide component.",
            "properties": {
                "config": {
                    "type": "string",
                    "description": "A relative path to a JSON file containing the map config.",
                    "default": ""
                },
                "fullscreen": {
                    "type": "boolean",
                    "description": "Specifies whether the panel can be expanded to full screen.",
                    "default": true
                },
                "type": {
                    "type": "string",
                    "enum": ["map"]
                },
                "scrollguard": {
                    "type": "boolean",
                    "description": "Whether or not CTRL is required to scroll this map.",
                    "default": false
                },
                "teleportGrid": {
                    "type": "string",
                    "description": "Specifies where to teleport grid outside of RAMP instance.",
                    "default": "",
                    "enum": ["", "left", "right"]
                },
                "title": {
                    "type": "string",
                    "description": "A title that is displayed centered above this map."
                },
                "caption": {
                    "type": "string",
                    "description": "Supporting text content for the map."
                },
                "customTemplates": {
                    "type": "array",
                    "description": "An array of custom template names that will need to be registered on the map component.",
                    "items": {
                        "type": "string",
                        "description": "The name of a Vue component that will need to be registered."
                    }
                },
                "timeSlider": {
                    "type": "object",
                    "properties": {
                        "range": {
                            "type": "array",
                            "description": "An array of two numbers, specifying the start and end of the slider range.",
                            "items": {
                                "type": "number",
                                "description": "Values for the start and end of the range."
                            }
                        },
                        "start": {
                            "type": "array",
                            "description": "An array of starting locations for slider handles, the number of items dictates the number of handles.",
                            "items": {
                                "type": "number",
                                "description": "The starting value for a handle."
                            }
                        },
                        "attribute": {
                            "type": "string",
                            "description": "The layer attribute that should be queried based on the slider values."
                        },
                        "layers": {
                            "type": "array",
                            "description": "An optional array of layer IDs for the slider to affect.",
                            "items": {
                                "type": "string",
                                "description": "A layer ID"
                            }
                        },
                        "animation": {
                            "type": "object",
                            "description": "Configuration for the timeslider animation/play function",
                            "properties": {
                                "playMode": {
                                    "type": "string",
                                    "description": "The mode to determine behaviour when the play button is used. By default it loops through the values one at a time.",
                                    "default": "distinct",
                                    "enum": ["distinct", "append"]
                                },
                                "interval": {
                                    "type": "number",
                                    "description": "The interval between steps in the animation in ms. 1400 is default.",
                                    "default": "1400"
                                }
                            }
                        },
                        "formatters": {
                            "anyOf": [
                                {
                                    "$ref": "#/$defs/timeSliderFormatter"
                                },
                                {
                                    "type": "array",
                                    "description": "An array of formatters that will take the values in the slider and make them readable.",
                                    "items": {
                                        "$ref": "#/$defs/timeSliderFormatter"
                                    }
                                }
                            ]
                        },
                        "sliderConfig": {
                            "type": "object",
                            "description": "A noUiSlider config object."
                        }
                    },
                    "required": ["start", "range", "attribute"]
                }
            },
            "required": ["config", "type"]
        },

        "timeSliderFormatter": {
            "type": "object",
            "description": "A formatter for use in the timeslider. Used to alias slider values into user readable versions.",
            "oneOf": [
                {
                    "$ref": "#/$defs/timeSliderValuesFormatter"
                },
                {
                    "$ref": "#/$defs/timeSliderRangesFormatter"
                }
            ]
        },

        "timeSliderValuesFormatter": {
            "type": "object",
            "description": "A formatter which maps slider values to the element at that index in the 'values' array.",
            "properties": {
                "mode": {
                    "type": "string",
                    "enum": ["values"]
                },
                "values": {
                    "type": "array",
                    "description": "An array of labels",
                    "items": {
                        "type": "string",
                        "description": "A label for use in the timeslider"
                    }
                }
            },
            "required": ["mode", "values"]
        },

        "timeSliderRangesFormatter": {
            "type": "object",
            "description": "A formatter which concatenates ranges as needed.",
            "properties": {
                "mode": {
                    "type": "string",
                    "enum": ["ranges"]
                },
                "ranges": {
                    "type": "array",
                    "description": "An array of arrays of labels",
                    "items": {
                        "type": "array",
                        "description": "An array of labels, ['January', 'March'] represents the full label 'January-March'",
                        "items": {
                            "type": "string",
                            "description": "A partial label"
                        }
                    }
                },
                "separator": {
                    "type": "string",
                    "description": "A string (default '-') to join/separate the range values",
                    "default": "-"
                }
            },
            "required": ["mode", "ranges"]
        },

        "interactiveMapPanel": {
            "type": "object",
            "description": "An interactive map slide component.",
            "properties": {
                "config": {
                    "type": "string",
                    "description": "A relative path to a JSON file containing the map config.",
                    "default": ""
                },
                "type": {
                    "type": "string",
                    "enum": ["interactive-map"]
                },
                "scrollguard": {
                    "type": "boolean",
                    "description": "Whether or not CTRL is required to scroll this map.",
                    "default": false
                },
                "title": {
                    "type": "string",
                    "description": "A title that is displayed centered above this map."
                },
                "teleportAOI": {
                    "type": "string",
                    "description": "Specifies where to teleport areas of interest outside of RAMP instance.",
                    "default": "",
                    "enum": ["", "left", "right"]
                },
                "duration": {
                    "type": "number",
                    "description": "Animation duration of zoom."
                },
                "points": {
                    "type": "array",
                    "description": "A list of points of interest.",
                    "items": {
                        "$ref": "#/$defs/pointOfInterest"
                    }
                }
            },
            "required": ["type", "config"]
        },

        "pointOfInterest": {
            "type": "object",
            "description": "A map slide component.",
            "properties": {
                "title": {
                    "type": "string",
                    "description": "The name of the point of interest.",
                    "default": ""
                },
                "text": {
                    "type": "string",
                    "description": "Text content for the point of interest."
                },
                "image": {
                    "type": "string",
                    "description": "Image content for the point of interest."
                },
                "altText": {
                    "type": "string",
                    "description": "Alt text for the image."
                },
                "target": {
                    "$ref": "#/$defs/pointOfInterestTarget"
                }
            },
            "required": ["target"]
        },

        "pointOfInterestTarget": {
            "type": "object",
            "description": "The target object for a point of interest.",
            "properties": {
                "oid": {
                    "type": "number",
                    "description": "The target OBJECTID of the point."
                },
                "layerId": {
                    "type": "string",
                    "description": "The ID of the target layer."
                },
                "layerIndex": {
                    "type": "number",
                    "description": "If the target layer is a map image layer, the index of the sublayer to target."
                }
            },
            "required": ["oid", "layerId"]
        },

        "dqvchartPanel": {
            "type": "object",
            "description": "A dqvchart slide component.",
            "properties": {
                "src": {
                    "type": "string",
                    "description": "The source containing the dqvchart json config."
                },
                "config": {
                    "type": "object",
                    "description": "Configured Highcharts JSON object (from editor)."
                },
                "type": {
                    "type": "string",
                    "enum": ["chart"]
                },
                "options": {
                    "$ref": "#/$defs/dqvchartOptions"
                }
            },
            "required": ["src", "type"]
        },

        "multimediaImage": {
            "type": "object",
            "description": "A multimedia image component.",
            "properties": {
                "width": {
                    "type": "number",
                    "description": "The image width."
                },
                "height": {
                    "type": "number",
                    "description": "The image height."
                },
                "src": {
                    "type": "string",
                    "description": "The source for the image."
                },
                "altText": {
                    "type": "string",
                    "description": "The supporting text for the image."
                },
                "caption": {
                    "type": "string",
                    "description": "Supporting text content for the image."
                },
                "class": {
                    "type": "string",
                    "description": "Styling class properties for the image."
                },
                "tooltip": {
                    "type": "string",
                    "description": "Tooltip content for the image."
                },
                "type": {
                    "type": "string",
                    "enum": ["image"]
                }
            },
            "required": ["src", "type"]
        },

        "multimediaVideo": {
            "type": "object",
            "description": "A multimedia video component.",
            "properties": {
                "title": {
                    "type": "string",
                    "description": "The title for the video."
                },
                "width": {
                    "type": "number",
                    "description": "The video width."
                },
                "height": {
                    "type": "number",
                    "description": "The video height. Only for Youtube videos. Changing height for external/local videos won't work due to the aspect ratio of the original video needing to be kept the same."
                },
                "src": {
                    "type": "string",
                    "description": "The source for the video. External and YouTube videos should be a URL, while local video files must be contained in the assets folder."
                },
                "videoType": {
                    "type": "string",
                    "enum": ["local", "external", "YouTube"]
                },
                "thumbnailUrl": {
                    "type": "string",
                    "description": "Optional link for providing URL for video thumbnail image. Limited to non-YouTube videos."
                },
                "transcript": {
                    "type": "string",
                    "description": "The source for the transcript in HTML/Markdown."
                },
                "caption": {
                    "type": "string",
                    "description": "Overlaying subtitles on the video, input should be a .vtt file."
                },
                "type": {
                    "type": "string",
                    "enum": ["video"]
                }
            },
            "required": ["src", "type", "videoType"]
        },

        "multimediaAudio": {
            "type": "object",
            "description": "A multimedia audio component.",
            "properties": {
                "src": {
                    "type": "string",
                    "description": "** TODO: the plan just has 'type' here, how do we want to distinguish mp3, wav, etc?"
                },
                "caption": {
                    "type": "string",
                    "description": "Supporting text content for the audio."
                },
                "type": {
                    "type": "string",
                    "enum": ["audio"]
                }
            },
            "required": ["src", "type"]
        },

        "multimediaSlideshow": {
            "type": "object",
            "description": "A multimedia slideshow component.",
            "properties": {
                "items": {
                    "type": "array",
                    "description": "An array of items to display in the slideshow.",
                    "items": {
                        "type": "object",
                        "description": "A config representing one of the following panel types.",
                        "oneOf": [
                            {
                                "$ref": "#/$defs/multimediaImage"
                            },
                            {
                                "$ref": "#/$defs/mapPanel"
                            },
                            {
                                "$ref": "#/$defs/textPanel"
                            },
                            {
                                "$ref": "#/$defs/dqvchartPanel"
                            }
                        ]
                    },
                    "minItems": 1
                },
                "loop": {
                    "type": "boolean",
                    "description": "Determines whether the slideshow loops back around to the beginning when you reach the end.",
                    "default": false
                },
                "caption": {
                    "type": "text",
                    "description": "A caption to display below the slideshow."
                },
                "type": {
                    "type": "string",
                    "enum": ["slideshow"]
                }
            },
            "required": ["items", "type"]
        },
        "dqvchartOptions": {
            "type": "object",
            "description": "Configuration for a dqvchart.",
            "properties": {
                "title": {
                    "type": "string",
                    "description": "The title of the chart."
                },
                "subtitle": {
                    "type": "string",
                    "description": "The subtitle of the chart."
                },
                "type": {
                    "type": "string",
                    "description": "The type of chart.",
                    "enum": [
                        "line",
                        "spline",
                        "area",
                        "areaspline",
                        "column",
                        "bar",
                        "pie",
                        "scatter",
                        "gauge",
                        "arearange",
                        "areasplinerange",
                        "columnrange"
                    ]
                },
                "width": {
                    "type": "number",
                    "description": "The width of the chart (will not exceed panel container width)."
                },
                "height": {
                    "type": "number",
                    "description": "The height of chart (will not exceed panel container height on mobile resolutions)."
                },
                "colours": {
                    "type": "array",
                    "description": "A list of colors to display chart data that corresponds to the order of columns in CSV file.",
                    "items": {
                        "type": "string"
                    }
                },
                "export": {
                    "type": "boolean",
                    "description": "Specify whether export menu options are enabled.",
                    "default": true
                },
                "credits": {
                    "type": "boolean",
                    "description": "Specify whether credits are enabled.",
                    "default": false
                },
                "xAxisLabel": {
                    "type": "string",
                    "description": "The title of the x-axis."
                },
                "yAxisLabel": {
                    "type": "string",
                    "description": "The title of the y-axis."
                }
            }
        }
    },

    "properties": {
        "title": {
            "type": "string",
            "description": "The title of the story map."
        },

        "introSlide": {
            "type": "object",
            "description": "The introductory slide",
            "properties": {
                "logo": {
                    "type": "object",
                    "description": "Information about the StoryRAMP logo",
                    "properties": {
                        "src": {
                            "type": "string",
                            "description": "An image source that is displayed at the top of the slide"
                        },
                        "altText": {
                            "type": "string",
                            "description": "Alt text for the logo"
                        }
                    },
                    "required": ["src"]
                },
                "title": {
                    "type": "string",
                    "description": "The title of the project, displayed under the image"
                },
                "subtitle": {
                    "type": "string",
                    "description": "An optional subtitle that is displayed under the title."
                },
                "blurb": {
                    "type": "string",
                    "description": "Any additional information to display on the introductory slide."
                },
                "backgroundImage": {
                    "type": "string",
                    "description": "A background image for the introduction slide."
                },
                "titleColour": {
                    "type": "string",
                    "description": "The text colour of the title text."
                },
                "subtitleColour": {
                    "type": "string",
                    "description": "The text colour of the subtitle text."
                },
                "buttonColour": {
                    "type": "string",
                    "description": "The colour of the 'jump to content' button."
                }
            },
            "required": ["logo", "title"]
        },

        "slides": {
            "type": "array",
            "description": "A list of StoryRAMP slides. A minimum of one slide is required.",
            "items": {
                "$ref": "#/$defs/slide"
            },
            "minItems": 1
        },

        "tableOfContents": {
            "type": "array",
            "description": "Defines a custom table of contents structure.",
            "items": {
                "type": "object",
                "description": "A table of contents item that resides on the root level.",
                "properties": {
                    "title": {
                        "type": "string",
                        "description": "Title description of table of contents item."
                    },
                    "slideIndex": {
                        "type": "number",
                        "description": "Slide index linked to this table of contents item."
                    },
                    "sublist": {
                        "type": "array",
                        "description": "List of sublist items that stem from this table of contents item.",
                        "items": {
                            "type": "object",
                            "description": "A table of contents child item that resides inside a sublist.",
                            "properties": {
                                "title": {
                                    "type": "string",
                                    "description": "Title description of table of contents item."
                                },
                                "slideIndex": {
                                    "type": "number",
                                    "description": "Slide index linked to this table of contents item."
                                }
                            },
                            "required": ["title", "slideIndex"]
                        },
                        "default": []
                    }
                },
                "required": ["title", "slideIndex"]
            }
        },

        "tocOrientation": {
            "type": "string",
            "description": "Specifies the orientation of the table of contents navigation menu.",
            "enum": ["vertical", "horizontal"],
            "default": "vertical"
        },

        "returnTop": {
            "type": "boolean",
            "description": "Specifies whether a link is added to scroll back to top of page.",
            "default": true
        },

        "contextLink": {
            "type": "string",
            "description": "A link pointing to the source information"
        },

        "contextLabel": {
            "type": "string",
            "description": "A description that explains the context link."
        },

        "lang": {
            "type": "string",
            "description": "The language to display in the app",
            "enum": ["en", "fr"]
        },

        "stylesheets": {
            "type": "array",
            "description": "A list of relative paths to stylesheets to include on the page.",
            "items": {
                "type": "string",
                "description": "A relative path to a stylesheet."
            }
        },

        "dateModified": {
            "type": "string",
            "description": "The last date that this config file was modified."
        },

        "lazyLoad": {
            "type": "boolean",
            "description": "If true, all images in the product will be lazy loaded.",
            "default": true
        }
    },

    "required": ["title", "introSlide", "slides"]
}