@buildcanada/charts 0.1.0

package/src/grapher/schema/grapher-schema.009.yaml

@@ -0,0 +1,781 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+# if you update the required keys, make sure that the mergeGrapherConfigs and
+# diffGrapherConfigs functions both reflect this change
+$id: "https://files.ourworldindata.org/schemas/grapher-schema.009.json"
+required:
+    - $schema
+    - dimensions
+type: object
+description: |
+    Our World In Data grapher configuration. Most of the fields can be left empty and will be
+    filled with reasonable default values.
+properties:
+    $schema:
+        type: string
+        description: Url of the concrete schema version to use to validate this document
+        format: uri
+        default: "https://files.ourworldindata.org/schemas/grapher-schema.009.json"
+        # We restrict the $schema field to a single value since we expect all
+        # configs in our database to be valid against the latest schema.
+        # If we ever need to validate configs against multiple schema versions,
+        # we can remove this constraint.
+        const: "https://files.ourworldindata.org/schemas/grapher-schema.009.json"
+    id:
+        type: integer
+        description: Internal DB id. Useful internally for OWID but not required if just using grapher directly.
+        minimum: 0
+    map:
+        type: object
+        description: Configuration of the world map chart
+        properties:
+            region:
+                type: string
+                description: Which region to focus on
+                enum:
+                    - World
+                    - Europe
+                    - Africa
+                    - Asia
+                    - NorthAmerica
+                    - SouthAmerica
+                    - Oceania
+                default: World
+            hideTimeline:
+                type: boolean
+                default: false
+                description: Whether the timeline should be hidden in the map view and thus the user not be able to change the year
+            colorScale:
+                $ref: "#/$defs/colorScale"
+            timeTolerance:
+                type: integer
+                description: |
+                    Tolerance to use. If data points are missing for a time point, a match is accepted if it lies
+                    within the specified time period. The unit is the dominating time unit, usually years but can be days for
+                    daily time series. If not provided, the tolerance specified in the metadata of the indicator is used.
+                    If that's not specified, 0 is used.
+                minimum: 0
+            toleranceStrategy:
+                type: string
+                description: |
+                    Tolerance strategy to use. Options include accepting matches that are "closest" to the time point in question
+                    (going forwards and backwards in time), and accepting matches that lie in the past ("backwards") or
+                    the future ("forwards").
+                enum:
+                    - closest
+                    - forwards
+                    - backwards
+                default: closest
+            tooltipUseCustomLabels:
+                type: boolean
+                default: false
+                description: Show the label from colorSchemeLabels in the tooltip instead of the numeric value
+            time:
+                description: Select a specific time to be displayed. If startTime is given, this acts as the end time.
+                default: "latest"
+                oneOf:
+                    - type: number
+                    - type: string
+                      enum:
+                          - latest
+                          - earliest
+            startTime:
+                description: Select a specific start time to be displayed. If given, two maps are shown next to each other.
+                oneOf:
+                    - type: number
+                    - type: string
+                      enum:
+                          - latest
+                          - earliest
+            columnSlug:
+                # TODO: remove this once we have a convention of using the first y dimension instead
+                description: |
+                    Column to show in the map tab. Can be a column slug (e.g. in explorers) or a variable ID (as string).
+                    If not provided, the first y dimension is used.
+                type: string
+            selectedEntityNames:
+                type: array
+                description: The initial selection of entities to show on the map
+                default: []
+                items:
+                    type:
+                        - string
+            globe:
+                type: object
+                description: Configuration of the globe
+                properties:
+                    isActive:
+                        type: boolean
+                        description: Whether the globe is initially shown
+                    rotation:
+                        type: array
+                        description: Latitude and Longitude of the globe rotation
+                        items:
+                            type:
+                                - number
+                    zoom:
+                        type: number
+                        description: Zoom level of the globe
+                additionalProperties: false
+        additionalProperties: false
+    maxTime:
+        description: End point of the initially selected time span.
+        default: latest
+        oneOf:
+            - type: number
+            - type: string
+              enum:
+                  - latest
+                  - earliest
+    subtitle:
+        type: string
+        description: The longer subtitle text to show beneath the title
+    selectedEntityNames:
+        type: array
+        description: The initial selection of entities
+        default: []
+        items:
+            type:
+                - string
+    focusedSeriesNames:
+        type: array
+        description: |
+            The initially focused chart elements. Is either a list of entity or variable names.
+            Only works for line and slope charts for now.
+        default: []
+        items:
+            type:
+                - string
+    baseColorScheme:
+        $ref: "#/$defs/colorScheme"
+    yAxis:
+        $ref: "#/$defs/axis"
+    tab:
+        type: string
+        description: The tab that is shown initially
+        default: chart
+        enum:
+            - chart
+            - map
+            - table
+            - line
+            - slope
+            - discrete-bar
+            - marimekko
+    matchingEntitiesOnly:
+        type: boolean
+        default: false
+        description: Exclude entities that do not belong in any color group
+    hideLegend:
+        type: boolean
+        default: false
+    hideLogo:
+        type: boolean
+        default: false
+    timelineMinTime:
+        description: |
+            The lowest year to show in the timeline. If this is set then the user is not able to see
+            any data before this year. If set to "earliest", then the earliest year in the data is used.
+        default: earliest
+        oneOf:
+            - type: number
+            - type: string
+              enum:
+                  - earliest
+    variantName:
+        type: string
+        description: Optional internal variant name for distinguishing charts with the same title
+    hideTimeline:
+        type: boolean
+        default: false
+        description: "Whether to hide the timeline from the user. If it is hidden then the user can't change the time"
+    originUrl:
+        type: string
+        description: The page containing this chart where more context can be found
+    colorScale:
+        $ref: "#/$defs/colorScale"
+    scatterPointLabelStrategy:
+        type: string
+        default: year
+        description: |
+            When a user hovers over a connected series line in a ScatterPlot we show
+            a label for each point. By default that value will be from the "year" column
+            but by changing this option the column used for the x or y axis could be used instead.
+        enum:
+            - x
+            - "y"
+            - year
+    selectedFacetStrategy:
+        type: string
+        default: none
+        description: The desired facetting strategy (none for no facetting)
+        enum:
+            - none
+            - entity
+            - metric
+    sourceDesc:
+        type: string
+        description: Short comma-separated list of source names
+    isPublished:
+        type: boolean
+        description: Indicates if the chart is published on Our World In Data or still in draft
+    invertColorScheme:
+        type: boolean
+        default: false
+        description: Reverse the order of colors in the color scheme
+    hideRelativeToggle:
+        type: boolean
+        default: true
+        description: Whether to hide the relative mode UI toggle
+    comparisonLines:
+        description: List of comparison lines to draw
+        type: array
+        default: []
+        items:
+            anyOf:
+                - type: object
+                  description: Comparison line of arbitrary shape defined by a formula. Defaults to `yEquals = x` if not specified
+                  properties:
+                      label:
+                          type: string
+                      yEquals:
+                          type: string
+                  additionalProperties: false
+                - type: object
+                  description: Vertical comparison line drawn at a specific x-value
+                  properties:
+                      label:
+                          type: string
+                      xEquals:
+                          type: number
+                  required: [xEquals]
+                  additionalProperties: false
+    slug:
+        type: string
+        description: Slug of the chart on Our World In Data
+    internalNotes:
+        type: string
+    version:
+        type: integer
+        minimum: 0
+    logo:
+        type: string
+        description: Which logo to show on the upper right side
+        default: owid
+        enum:
+            - owid
+            - core+owid
+            - gv+owid
+    entityType:
+        type: string
+        default: country or region
+        description: Display string for naming the primary entities of the data. Default is 'country or region', but you can specify a different one such as 'state' or 'region'
+    facettingLabelByYVariables:
+        type: string
+        default: metric
+        description: Display string that replaces 'metric' in the 'Split by metric' label in facet controls (e.g. 'product' displays 'Split by product')
+    note:
+        type: string
+        description: Note displayed in the footer of the chart. To be used for clarifications etc about the data.
+    dimensions:
+        type: array
+        description: List of dimensions and their mapping to variables
+        items:
+            type: object
+            required:
+                - property
+                - variableId
+            properties:
+                targetYear:
+                    type: integer
+                    description: |
+                        Charts that can display more than one primary dimensions (i.e. scatter and marimekko)
+                        sometimes need to "hardcode" one dimension to a specific year. This happens e.g. when
+                        mixing a daily X variable in a scatter plot with a yearly one, e.g. population.
+                property:
+                    type: string
+                    description: Which dimension this property maps to
+                    enum:
+                        - "y"
+                        - "x"
+                        - "size"
+                        - "color"
+                        - "table"
+                display:
+                    type: object
+                    properties:
+                        isProjection:
+                            type: boolean
+                            default: false
+                            description: |
+                                Indicates if this time series is a forward projection (if yes then this is rendered
+                                differently in e.g. line charts)
+                        plotMarkersOnlyInLineChart:
+                            type: boolean
+                            default: false
+                            description: |
+                                Indicates if data points should be connected with a line in a line chart
+                        name:
+                            type: string
+                            description: The display string for this variable
+                        description:
+                            type: string
+                            description: Variable description
+                            $comment: This is a new field that did not exist prior to November 2021 in the DB. It overrides the description on the variable DB table.
+                        tableDisplay:
+                            type: object
+                            description: Configuration for the table sheet for this variable
+                            properties:
+                                hideAbsoluteChange:
+                                    type: boolean
+                                    default: false
+                                hideRelativeChange:
+                                    type: boolean
+                                    default: false
+                            additionalProperties: false
+                        tolerance:
+                            type: integer
+                            default: 0
+                            description: |
+                                Tolerance to use. If data points are missing for a time point, a match is accepted if it lies
+                                within the specified time period. The unit is the dominating time unit, either years or days.
+                            minimum: 0
+                        entityAnnotationsMap:
+                            type: string
+                            description: Entity annotations
+                        yearIsDay:
+                            type: boolean
+                            default: false
+                            description: Switch to indicate if the number in the year column represents a day (since zeroDay) or not i.e. a year
+                        color:
+                            type: string
+                            description: Default color for this time series
+                        includeInTable:
+                            type: boolean
+                            default: true
+                            description: Whether to render this time series in the table sheet
+                        shortUnit:
+                            type: string
+                            description: Short unit symbol - This is used in tight UI spaces when the value is shown
+                        conversionFactor:
+                            type: number
+                            description: Conversion factor to apply before showing values
+                        unit:
+                            type: string
+                            description: Long unit text - This is shown in the UI when there is more space (e.g. tooltips) after values
+                        roundingMode:
+                            type: string
+                            description: |
+                                Rounding strategy to use. Supported are rounding to a fixed number of decimals and rounding to significant figures.
+                                If 'decimalPlaces' is selected, then 'numDecimalPlaces' is used. If 'significantFigures' is selected, then 'numSignificantFigures' is used.
+                            default: decimalPlaces
+                            enum:
+                                - decimalPlaces
+                                - significantFigures
+                        numDecimalPlaces:
+                            type: integer
+                            description: Number of decimal places to show
+                            minimum: 0
+                            default: 2
+                        numSignificantFigures:
+                            type: integer
+                            description: Number of significant figures to show
+                            minimum: 1
+                            default: 3
+                        zeroDay:
+                            type: string
+                            description: Iso date day string for the starting date if yearIsDay is used
+                            default: "2020-01-21"
+                    additionalProperties: false
+                variableId:
+                    type: integer
+                    description: The variable id to get the values for this time series
+                    minimum: 0
+            additionalProperties: false
+    addCountryMode:
+        type: string
+        description: Whether the user can change countries, add additional ones or neither
+        default: add-country
+        enum:
+            - add-country
+            - change-country
+            - disabled
+    compareEndPointsOnly:
+        type: boolean
+        default: false
+        description: Drops in between points in scatter plots
+    selectedEntityColors:
+        type: object
+        description: Colors for selected entities
+        patternProperties:
+            ".*":
+                type: string
+    relatedQuestions:
+        type: array
+        description: Links to related questions
+        default: []
+        items:
+            type: object
+            properties:
+                url:
+                    type: string
+                text:
+                    type: string
+            additionalProperties: false
+    title:
+        type: string
+        description: Big title text of the chart
+    chartTypes:
+        type: array
+        description: Which chart types should be shown
+        default: ["LineChart", "DiscreteBar"]
+        items:
+            type: string
+            enum:
+                - LineChart
+                - ScatterPlot
+                - StackedArea
+                - DiscreteBar
+                - StackedDiscreteBar
+                - SlopeChart
+                - StackedBar
+                - Marimekko
+    hasMapTab:
+        type: boolean
+        default: false
+        description: Indicates if the map tab should be shown
+    stackMode:
+        type: string
+        description: Stack mode. Only absolute and relative are actively used.
+        default: absolute
+        enum:
+            - absolute
+            - relative
+            - grouped
+            - stacked
+    minTime:
+        description: Start point of the initially selected time span.
+        default: earliest
+        oneOf:
+            - type: number
+            - type: string
+              enum:
+                  - latest
+                  - earliest
+    hideAnnotationFieldsInTitle:
+        type: object
+        description: Whether to hide any automatically added title annotations like the selected year
+        properties:
+            entity:
+                type: boolean
+                description: Whether to hide the entity annotation
+                default: false
+            time:
+                type: boolean
+                description: Whether to hide the time annotation
+                default: false
+            changeInPrefix:
+                type: boolean
+                description: Whether to hide "Change in" in relative line charts
+                default: false
+    excludedEntityNames:
+        type: array
+        description: Entities that should be excluded (opposite of includedEntityNames)
+        default: []
+        items:
+            type: string
+    includedEntityNames:
+        type: array
+        description: |
+            Entities that should be included (opposite of excludedEntityNames).
+            If empty, all available entities are used. If set, all entities not specified here are excluded.
+            excludedEntityNames are evaluated afterwards and can still remove entities even if they were included before.
+        default: []
+        items:
+            type: string
+    xAxis:
+        $ref: "#/$defs/axis"
+    timelineMaxTime:
+        description: |
+            The highest year to show in the timeline. If this is set then the user is not able to see
+            any data after this year. If set to "latest", then the latest year in the data is used.
+        default: latest
+        oneOf:
+            - type: number
+            - type: string
+              enum:
+                  - latest
+    hideConnectedScatterLines:
+        type: boolean
+        default: false
+        description: Whether to hide connecting lines on scatter plots when a time range is selected
+    showNoDataArea:
+        type: boolean
+        default: true
+        description: Whether to show an area for entities that have no data (currently only used in marimekko charts)
+    zoomToSelection:
+        type: boolean
+        default: false
+        description: Whether to zoom to the selected data points
+    showYearLabels:
+        type: boolean
+        default: false
+        description: Whether to show year labels in bar charts
+    hideTotalValueLabel:
+        type: boolean
+        default: false
+        description: Whether to hide the total value label (used on stacked discrete bar charts)
+    hideScatterLabels:
+        type: boolean
+        default: false
+        description: Hide entity names in Scatter plots
+    sortBy:
+        type: string
+        description: Sort criterium (used by stacked bar charts and marimekko)
+        default: total
+        enum:
+            - column
+            - total
+            - entityName
+            - custom
+    sortOrder:
+        type: string
+        description: Sort order (used by stacked bar charts and marimekko)
+        default: desc
+        enum:
+            - desc
+            - asc
+    sortColumnSlug:
+        description: Sort column if sortBy is column (used by stacked bar charts and marimekko)
+        type: string
+    hideFacetControl:
+        type: boolean
+        default: true
+        description: Whether to hide the faceting control
+    entityTypePlural:
+        description: Plural of the entity type (i.e. when entityType is 'country' this would be 'countries')
+        default: countries and regions
+        type: string
+    missingDataStrategy:
+        type: string
+        default: auto
+        description: The desired strategy for handling entities with missing data
+        enum:
+            - auto
+            - hide
+            - show
+additionalProperties: false
+
+$defs:
+    axis:
+        type: object
+        properties:
+            removePointsOutsideDomain:
+                type: boolean
+                default: false
+            label:
+                type: string
+                description: Axis label
+            min:
+                description: |
+                    Minimum domain value of the axis. Inferred from data if set to "auto".
+                    Usually defaults to "auto", but defaults to 0 for line charts on the y-axis.
+                oneOf:
+                    - type: number
+                    - type: string
+                      enum:
+                          - auto
+            scaleType:
+                type: string
+                description: Toggle linear/logarithmic
+                default: linear
+                enum:
+                    - linear
+                    - log
+            max:
+                description: Maximum domain value of the axis. Inferred from data if set to "auto".
+                default: auto
+                oneOf:
+                    - type: number
+                    - type: string
+                      enum:
+                          - auto
+            canChangeScaleType:
+                type: boolean
+                description: Allow user to change lin/log
+                default: false
+            facetDomain:
+                type: string
+                description: Whether the axis domain should be the same across faceted charts (if possible)
+                default: shared
+                enum:
+                    - independent
+                    - shared
+        additionalProperties: false
+    colorScheme:
+        type: string
+        description: |
+            One of the predefined base color schemes.
+            If not provided, a default is automatically chosen based on the chart type.
+        enum:
+            - YlGn
+            - YlGnBu
+            - GnBu
+            - BuGn
+            - PuBuGn
+            - BuPu
+            - RdPu
+            - PuRd
+            - OrRd
+            - YlOrRd
+            - YlOrBr
+            - Purples
+            - Blues
+            - Greens
+            - Oranges
+            - Reds
+            - Greys
+            - PuOr
+            - BrBG
+            - PRGn
+            - PiYG
+            - RdBu
+            - RdGy
+            - RdYlBu
+            - Spectral
+            - RdYlGn
+            - Accent
+            - Dark2
+            - Paired
+            - Pastel1
+            - Pastel2
+            - Set1
+            - Set2
+            - Set3
+            - PuBu
+            - Magma
+            - Inferno
+            - Plasma
+            - Viridis
+            - continents
+            - stackedAreaDefault
+            - owid-distinct
+            - SingleColorDenim
+            - SingleColorTeal
+            - SingleColorPurple
+            - SingleColorDustyCoral
+            - SingleColorDarkCopper
+            - OwidCategoricalA
+            - OwidCategoricalB
+            - OwidCategoricalC
+            - OwidCategoricalD
+            - OwidCategoricalE
+            - OwidEnergy
+            - OwidEnergyLines
+            - OwidDistinctLines
+            - BinaryMapPaletteA
+            - BinaryMapPaletteB
+            - BinaryMapPaletteC
+            - BinaryMapPaletteD
+            - BinaryMapPaletteE
+            - SingleColorGradientDenim
+            - SingleColorGradientTeal
+            - SingleColorGradientPurple
+            - SingleColorGradientDustyCoral
+            - SingleColorGradientDarkCopper
+    colorScale:
+        type: object
+        description: Color scale definition
+        properties:
+            customNumericLabels:
+                type: array
+                description: |
+                    Custom labels for each numeric bin. Only applied when strategy is `manual`.
+                    `null` falls back to default label.
+                items:
+                    type:
+                        - string
+                        - "null"
+            customCategoryColors:
+                type: object
+                description: Map of categorical values to colors. Colors are CSS colors, usually in the form `#aa9944`
+                patternProperties:
+                    ".*":
+                        type: string
+            baseColorScheme:
+                $ref: "#/$defs/colorScheme"
+            customHiddenCategories:
+                type: object
+                description: Allow hiding categories from the legend
+                patternProperties:
+                    ".*":
+                        type: boolean
+            binningStrategy:
+                type: string
+                description: The strategy for generating the bin boundaries
+                default: auto
+                enum:
+                    - manual
+                    - auto
+                    - log-auto
+                    - log-1-2-5
+                    - log-1-3
+                    - log-10
+                    - equalSizeBins-few-bins
+                    - equalSizeBins-normal
+                    - equalSizeBins-many-bins
+                    - equalSizeBins-percent
+            minValue:
+                type: number
+                description: Minimum value of the color scale, for automated binning.
+            maxValue:
+                type: number
+                description: Maximum value of the color scale, for automated binning.
+            midpoint:
+                type: number
+                default: 0
+                description: Midpoint value for the color scale, for automated binning around the midpoint.
+            midpointMode:
+                type: string
+                description: How to handle the midpoint when generating bins. Undefined means automatically choosing between 'none' and 'symmetric'.
+                enum:
+                    - none
+                    - symmetric
+                    - same-num-bins
+                    - asymmetric
+            createBinForMidpoint:
+                type: boolean
+                default: false
+                description: Whether to create a separate bin that only contains the midpoint value.
+            legendDescription:
+                type: string
+                description: A custom legend description. Only used in ScatterPlot legend titles for now.
+            customNumericColors:
+                type: array
+                description: |
+                    Override some or all colors for the numerical color legend.
+                    Colors are CSS colors, usually in the form `#aa9944`
+                    `null` falls back the color scheme color.
+                items:
+                    type:
+                        - string
+                        - "null"
+            customNumericValues:
+                type: array
+                description: Custom maximum brackets for each numeric bin. Only applied when strategy is `manual`
+                items:
+                    type: number
+            customNumericColorsActive:
+                type: boolean
+                default: false
+                description: Whether `customNumericColors` are used to override the color scheme
+            colorSchemeInvert:
+                type: boolean
+                default: false
+                description: Reverse the order of colors in the color scheme
+            customCategoryLabels:
+                type: object
+                description: Map of category values to color legend labels.
+                patternProperties:
+                    ".*":
+                        type: string
+        additionalProperties: false