widget.json Schema

All fields are required unless marked Optional.

Top Level Fields

name: String.

description: String.

version: Number. Use 1 for now. Optional. If unspecified, your widget might not render properly on clients.

default_layout: String. Must match an object name in layouts object. Used to tell client which layout to select when adding a new widget. Optional. Default to the first layout in layouts.

thumbnail_layout: String. Must match an object name in layouts object. Used to tell client which layout to show when space is limited. For instance in a list of widgets. This would typically be a simplified widget or logo. Optional. Default to the first layout in layouts.

layout_display_order: Array of Strings. Strings must match object names in layouts object. Used to tell clients the order to preview the widget layouts. Optional. Default to None. If unspecified, client can determine order.

content_last_modified: ISO-8601 Datetime String (e.g. "2022-08-20T14:15:08Z") Used by clients to prioritize new content. Optional. Default to None.

data: Dictionary of key value pairs used throughout the widget layouts. content_url should always be defined and will be launched when the user taps the widget in areas that link_url don't cover.

layouts: Dictionary of String to Layout object.

Layout Object Fields

size: String. Values are small, medium, large, extra_large. small may not use link_url in cells. extra_large do not render on iPhones. small is a square. medium is roughly two smalls placed side by side (wider than it is tall). large is roughly four smalls arranged in a square. extra_large is roughly four mediums arranged in a grid.

styles: Dictionary with two keys: color and fonts. color is a Dictionary of Color objects. fonts is a Dictionary of Font objects.

layers: Array of Layer objects.

Color Object Fields

color: String. Either a hexcode color (e.g. #FFFFFF55 or #00FF00) or a linear gradient (e.g. linear-gradient(0deg, #76A5D5, #2469AA)) Optional. Default None.

Font Object Fields

family: String. A font that is renderable on a client. See http://iosfonts.com for what Widget Construction Set can render. Optional. Default None.

Layer Object Fields

rows: Array of Row objects.

Row Object Fields

height: Number. Must be 12 or less. All heights in a layer must sum to 12.

cells: Array of Cell objects. Optional. Default None.

Cell Object Fields

width: Number. Must be 12 or less. All widths in a row must sum to 12.

background_color_style: String. Must match a key in styles.color dictionary. Optional. Default None. Undefined behavior if no background on the widget is set. Either an image or a background_color_style should be set as a full width, full height layer.

padding: Number. Must be less than 50% of width of the cell. Optional. Default None.

text: Text object. Optional. Default None.

image: Image object. Optional. Default None.

link_url: String. Url to visit when this cell is tapped. Only usable on medium, large, and extra_large layouts. Optional. Default None.

Text Object Fields

string: String. Not required if data_ref is specified.

data_ref: String. Must match a key in data. Not required if string is specified.

size: Float. Optional. Default 18.0.

font_style: String. Must match a key in styles.font dictionary. Optional. Default client system font.

color_style: String. Must match a key in styles.color dictionary. Optional. Default #FFFFFF.

weight: String. Values are light, medium, bold, extra_bold. Optional. Default medium.

justification: String. Values are left, center, right. Optional. Default center.

min_scale_factor: Number. Must be 1.0 or less. This specifies how small a font can be scaled before it stops being scaled and may experience clipping. For example, 0.5 here would mean that an 18pt font can go as small as 18 * 0.5 or 9pt. Optional. Default 1.0.

Image Object Fields

url: String. Not required if data_ref is specified.

data_ref: String. Must match a key in data. Not required if url is specified.

mask: String. Values are circle. Optional. Default None.