Skip to main content

JSON Schema

JSON Schema is a declarative language that provides a standardized way to describe and validate JSON data.

Check out

Full documentation on JSON Schema is available. Also, click here for some examples of JSON Schemas for common widgets.

JSON basics
{
    "type": "object",
    "properties": {
        "[class]": {
            "[property]": "[propertyVar]",
            "[property]": "[propertyVar]",
            "[property]": "[propertyVar]"
        }
    }
}

[class] (required)​

The name of the instance, which can be called upon in the widget code with properties.[class] or item.[class].

Do NOT use a "-" in a [class]. Use an "_" instead, the only exception is a csstring.

[property] (required)​

Properties are used to dictate the options for each [class]. They also dictate what information is needed to properly convey the information to the Jinja field in the HTML.

Keep in mind, if you pick more than one [property], you need to add a "," after each "[propertyVar]", except for the last one.

"title"​

Can be anything. This is printed in the widget as the name of the item. It will be filled with [class] if left empty.

"type" (required)​

PropertyVar:
string | csstring | boolean | object | array
  • string: Just a string.
  • csstring: Usually combined with "object" (to link to an internal page) and "filemanager" (to link a file or image).
  • boolean: Gives a true/false option. Usually combined with "checkbox".
  • object: Used for initializing an object. Usually combined with "properties": {}
  • array: Used in combination with either format table or tabs. See below for more details.

"format"​

PropertyVar:
object | color | range | text | textarea | checkbox | filemanager | table | tabs | select

More options are available, but most are outdated.

  • object: Used to create a link.
  • color: Only hex-based colors.
  • range: Used to pick from a range of numbers, usually through a slider.
  • text: Standard text input, one row.
  • textarea: Standard text input, sizeable rows.
  • checkbox: Creates a checkbox, which returns 'true' or 'false', to be used by Jinja. See "Checkbox example".
  • filemanager: Used in conjunction with csstring to, for example, pick an image. See "Image example".
  • table: The table format works great when every array element has the same schema and is not too complex. Used in combination with "type": "array"
  • tabs: The tabs format can handle any array, but only shows one array element at a time. It has tabs on the left for switching between items. Used in combination with "type": "array"
  • select: Use with "enum" to force checkboxes.

"enum"​

Gives the user an array of options, fill in like:

"enum": ["aaa","bbb","ccc"]

"default"​

Can be filled with a default option. When used alongside enum, shows the default enum option.

"propertyOrder"​

Can be used to set the order of properties. The lower the number, the higher in the list it is.

"options"​

PropertyVar:
hidden | enum_titles | input_{{ options }} | disable_{{ options }} | expand_height | remove_empty_properties
  • enum_titles: Use to rename the enum titles without changing the value. Use like 
    "options": {
        "enum_titles": ["1","2","3"]
    }
  • input_{{ options }}: {{ options }} include: height | width
    • height: Set the height of an input element. Should be a valid CSS height string (e.g., "100px"). Works best with textareas.
    • width: Set the width of an input element. Should be a valid CSS width string (e.g., "100px"). Works best with string, number, and integer data types.
  • expand_height: Used to automatically change the height of an input element to fit the content. Works best with textareas.
  • disable_{{ options }}: {{ options }} include: 
    array_add | array_delete | array_delete_all_rows | array_delete_last_row | array_reorder | collapse | edit_json | properties
    • array_add: If set to true, the "add row" button will be hidden.
    • array_delete: If set to true, all of the "delete" buttons will be hidden.
    • array_delete_all_rows: If set to true, just the "delete all rows" button will be hidden.
    • array_delete_last_row: If set to true, just the "delete last row" button will be hidden.
    • array_reorder: If set to true, the "move up/down" buttons will be hidden.
    • collapse: If set to true, the collapse button will be hidden.
    • edit_json: If set to true, the Edit JSON button will be hidden.
    • properties: If set to true, the Edit Properties button will be hidden.