Uxtly’s schema for AI app builders
This document is intended for AI. Also, the JSON schema it discusses it’s also only for AI.
Uxtly has a "Copy for AI" feature for exporting UI drafts as JSON. This document contains several examples of mentioned JSON files. Each example is in a section that also contains a screenshot of how the file looks in Uxtly.
Since Uxtly is a drafting and spec’ing out tool, not a graphic design program, the images are not representative of an expected visual design. In other words, their layout and style are not part of what the UI draft specifies. For instance, the next two images are for illustrating how the draft looks in Uxtly versus a graphic designed UI that’s functionally equivalent.
In a sense, Uxtly’s UI drafts are like wireframes, but wireframes usually describe some 2D layout design, while the UI drafts are always single column groups. That’s to reiterate that besides styling, AI can suggest layout variants, such as a multi-column one, or any design composition.
JSDoc definitions for the JSON schema for AI app builders
In the JSDoc definitions, fields wrapped in square brackets are optional (e.g. [key]).
Optional fields have their default value within that wrap as well, for example [thousands_grouped=true].
After this section, you’ll find several example UI Drafts, and each one of them has screenshot of how it looks in Uxtly.
/** @enum {string} */
const OperatorEnum = {
ADD: '+',
SUBTRACT: '-',
MULTIPLY: '*',
DIVIDE: '/',
EXPONENTIATE: '**'
}
/** @enum {string} */
const RoundingFunctionEnum = {
HALF_UP: 'HALF_UP',
CEIL: 'CEIL',
FLOOR: 'FLOOR',
SIGNIFICANT_FIGURES: 'SIGNIFICANT_FIGURES'
}
/** @enum {string} */
const FormulaPresetEnum = {
SUM_ALL: 'SUM_ALL',
MULTIPLY_ALL: 'MULTIPLY_ALL',
AVERAGE: 'AVERAGE',
MEDIAN: 'MEDIAN',
MIN: 'MIN',
MAX: 'MAX'
}
/** @enum {string} */
const NumberFormatEnum = {
PERCENT: 'PERCENT',
CURRENCY: 'CURRENCY',
SCIENTIFIC: 'SCIENTIFIC'
}
/** @enum {string} */
const ButtonKindEnum = {
PRIMARY: 'PRIMARY',
SECONDARY: 'SECONDARY'
}
/** @enum {string} */
const ItemTemplateEnum = {
INPUT: 'INPUT',
MULTILINE_INPUT: 'MULTILINE_INPUT',
PARAGRAPH: 'PARAGRAPH',
CHECKBOX: 'CHECKBOX',
SELECTOR: 'SELECTOR',
BUTTON: 'BUTTON',
GROUP_HOUSE: 'GROUP_HOUSE' // AI_HINT
}
/** @enum {string} */
const ButtonActionEnum = {
GO_TO_URL: 'GO_TO_URL', // Navigate to external URL
GO_TO_GROUP: 'GO_TO_GROUP', // Navigate to a Group in the draft
FORK_MASTER_FORM: 'FORK_MASTER_FORM', // Duplicate a template Group
DELETE_GROUP: 'DELETE_GROUP' // Remove a Group from the draft
}
/** @enum {string} */
const ButtonActionTargetEnum = {
PREVIOUS_GROUP: ':WHICHEVER_ROOT_GROUP_IS_BEFORE',
NEXT_GROUP: ':WHICHEVER_ROOT_GROUP_IS_NEXT',
CURRENT_GROUP: ':CURRENT_GROUP'
}
/**
* @typedef {Object} File
* @property {string} schema - URL with the schema documentation.
* @property {string} [schema_role='UI_DRAFT_FOR_AI'] - Always for AI.
* @property {boolean} [layout_relevant=false] - Always false. Uxtly’s UI drafts are layout agnostic.
* @property {string} title - UI draft title.
* @property {Group[]} groups - All Groups.
*/
/**
* @typedef {Object} Group
* @property {string} id - Group IDs are unique within a File.
* @property {string} [key=undefined] - Non-unique identifier that users can attach to a Group. Ignore it unless users explain its purpose.
* @property {boolean} [is_auxiliary=false] - If true, the Group is not meant to be shown in the final app. It could be used for comments, instructions, intermediate computations, or as a data store.
* @property {boolean} [ai_hint_is_nested=false] - If true, place this Group in the position of the Item that has `nested_group_id` equal to this Group `id`.
* @property {Item[]} [items=undefined] - Items contained in the Group.
* @property {string} [title=undefined] - The Group title.
* @property {number} [color=undefined] - Meaningless by default (integer from 0 to 15). Ignore unless users explain its purpose.
* @property {boolean} [is_master_form=false] - If true, the Group acts as a template for creating Groups.
* @property {boolean} [has_formula=false] - If true, numeric Items within the Group are meant to be computed in a mathematical formula.
*
* // Fields applicable when `has_formula` is true
* @property {FormulaPresetEnum} [formula_preset=undefined] - Defines the formula to apply (e.g., 'SUM_ALL' for summing all Items).
* @property {string} [ai_hint_total=undefined] - Computed at runtime. Use it to confirm the correctness of your formula algorithm.
* @property {OutputLink[]} [output_links=undefined] - Indicates the Items whose data is fed from the Group total.
* @property {NumberFormatEnum} [number_format=undefined] - Numeric format for the Group total.
* @property {number} [decimals=undefined] - Number of decimal digits for formatting the Group total, when empty
* @property {number} [rounding_digit=undefined] - Digit to which the Group total should be rounded.
* @property {RoundingFunctionEnum} [rounding_function=undefined] - Method used to round the Group total.
* @property {boolean} [thousands_grouped=true] - If false, the total should not be formatted with thousands grouping. Defaults to true if undefined.
*/
/**
* @typedef {Object} Item
* @property {string} id - Item IDs are unique within a Group.
* @property {string} [key=undefined] - Non-unique identifier users can attach to an Item. Ignore unless its purpose is explained.
* @property {boolean} [is_auxiliary=false] - If true, the Item is not meant to be shown in the final app. Used for comments, instructions, or intermediate computations.
* @property {ItemTemplateEnum} [template='INPUT'] - Defines the semantic purpose (e.g., button, paragraph).
* @property {string} [nested_group_id=undefined] - If defined, this Item indicates the placement of the specified Group. Think of as the Group house.
* @property {OutputLink[]} [output_links=undefined] - Items whose `label`, `value`, `number_format`, `decimals`, and `thousands_grouped` are fed from this Item.
* @property {string} [label=undefined] - The Item label.
* @property {string} [value=undefined] - The Item value (even numeric values are passed as strings).
* @property {boolean} [struck=false] - If true, applies a "strikethrough" style and excludes the Item from formula computations in Groups with `has_formula = true`.
* @property {boolean} [is_read_only=false] - If true, the input field should be locked from changes.
* @property {number} [color=undefined] - Integer from 0 to 15. Ignore unless its purpose is explained.
* @property {OperatorEnum} [operator=undefined] - Applies when the parent Group has `has_formula`. Defines the arithmetic operator used before this Item’s `value`.
* @property {NumberFormatEnum} [number_format=undefined] - Defines how numeric values should be formatted.
* @property {number} [decimals=undefined] - Number of decimal digits to display when the Item’s `value` is numeric.
* @property {boolean} [thousands_grouped=true] - If false, the `value` should not be formatted with thousands grouping. Defaults to true if undefined.
* @property {ButtonKindEnum} [button_kind=undefined] - Defines button importance. 'PRIMARY' buttons have more visual weight than 'SECONDARY' ones.
* @property {number} [button_color=undefined] - Integer from 0 to 15. Ignore unless its purpose is explained.
* @property {[ButtonActionEnum, ButtonActionTargetEnum | string][]} [button_actions=undefined] - Defines an action and its target Group `id`. Targets prefixed with `:` determine the corresponding Group.
*
* // Applicable when `template` is 'SELECTOR'
* @property {string} [selector_source_group_id=undefined] - Group containing the options.
* @property {string} [selector_source_item_id=undefined] - Item describing the currently selected option.
*
* // For dynamically specifying selector options based on another selector Item.
* @property {string} [selector_chained_group_id=undefined] - Group containing the selector Item.
* @property {string} [selector_chained_item_id=undefined] - Selector Item used as the source.
*/
/**
* @typedef {Object} OutputLink
* @property {string} group_id - Target Group ID.
* @property {string} item_id - Target Item ID.
*/
Examples
The rest of this document has the examples mentioned at the beginning.
Example: Sign Up and Log In
This schema has two non-nested Groups. Think of these "Root Groups" as individual pages on the final app.
{
"schema": "https://docs.uxtly.com/ai-schema",
"title": "Example 1: Sign Up and Log In",
"groups": [
{
"id": "a",
"title": "Create a new Account",
"items": [
{
"id": "b",
"label": "Full Name"
},
{
"id": "g",
"label": "Email"
},
{
"id": "c",
"label": "Password"
},
{
"id": "f",
"label": "Confirm Password"
},
{
"id": "j",
"template": "PARAGRAPH",
"label": "By clicking Sign Up, you agree to our Terms, and Privacy Policy."
},
{
"id": "d",
"template": "BUTTON",
"label": "Sign Up"
},
{
"id": "h",
"template": "BUTTON",
"label": "Already have an account?",
"button_kind": "SECONDARY"
}
]
},
{
"id": "e",
"title": "Log In",
"items": [
{
"id": "b",
"label": "Email"
},
{
"id": "c",
"label": "Password"
},
{
"id": "d",
"template": "BUTTON",
"label": "Log In"
},
{
"id": "i",
"template": "BUTTON",
"label": "Forgot Password?",
"button_kind": "SECONDARY"
},
{
"id": "k",
"template": "BUTTON",
"label": "Create new account",
"button_kind": "SECONDARY"
}
]
}
]
}
Example: Simple Selector
In this example there’s a paragraph Item, and a simple fruit selector Item.
{
"schema": "https://docs.uxtly.com/ai-schema",
"title": "Paragraph and Selector",
"groups": [
{
"id": "a",
"items": [
{
"id": "h",
"template": "PARAGRAPH",
"label": "Select a fruit from the list:"
},
{
"id": "b",
"template": "SELECTOR",
"label": "Fruit",
"selector_source_group_id": "c",
"selector_source_item_id": "e"
},
{
"id": "d",
"nested_group_id": "c",
"template": "AI_HINT_GROUP_HOUSE"
}
]
},
{
"id": "c",
"title": "Fruits",
"is_auxiliary": 1,
"ai_hint_is_nested": 1,
"items": [
{
"id": "e",
"label": "Apple"
},
{
"id": "f",
"label": "Banana"
},
{
"id": "g",
"label": "Coconut"
}
]
}
]
}
Example: Beneficiaries (Dynamic Master Form)
In this example the root Group has a nested group flagged as
is_master_form. The root Group has a button Item with an action
of ["FORK_MASTER_FORM", id_of_master_form_group], which is meant
to create a new Group using the master form as template. The master Group has a
button Item with an action of ["DELETE_GROUP", ":CURRENT_GROUP"],
which would remove the group that has that button Item when clicked.
{
"schema": "https://docs.uxtly.com/ai-schema",
"title": "Beneficiaries Dynamic Form",
"groups": [
{
"id": "s",
"title": "Beneficiaries",
"items": [
{
"id": "t",
"nested_group_id": "p",
"template": "AI_HINT_GROUP_HOUSE"
},
{
"id": "w",
"nested_group_id": "v",
"template": "AI_HINT_GROUP_HOUSE"
},
{
"id": "x",
"template": "BUTTON",
"label": "Add Another",
"button_actions": [
[
"FORK_MASTER_FORM",
"p"
]
]
}
]
},
{
"id": "k",
"title": "Relationships",
"is_auxiliary": 1,
"items": [
{
"id": "m",
"label": "Spouse"
},
{
"id": "n",
"label": "Child"
}
]
},
{
"id": "p",
"is_auxiliary": 1,
"ai_hint_is_nested": 1,
"is_master_form": 1,
"items": [
{
"id": "q",
"label": "Name"
},
{
"id": "r",
"template": "SELECTOR",
"label": "Relationship",
"selector_source_group_id": "k",
"selector_source_item_id": "m"
},
{
"id": "u",
"template": "BUTTON",
"label": "Delete",
"button_kind": "SECONDARY",
"button_color": "#f44336",
"button_actions": [
[
"DELETE_GROUP",
":CURRENT_GROUP"
]
]
}
]
},
{
"id": "v",
"ai_hint_is_nested": 1,
"items": [
{
"id": "q",
"label": "Name"
},
{
"id": "r",
"template": "SELECTOR",
"label": "Relationship",
"selector_source_group_id": "k",
"selector_source_item_id": "m"
},
{
"id": "u",
"template": "BUTTON",
"label": "Delete",
"button_kind": "SECONDARY",
"button_color": "#f44336",
"button_actions": [
[
"DELETE_GROUP",
":CURRENT_GROUP"
]
]
}
]
}
]
}
Example: Select Car Model by Manufacturer
In this example the options for the car model choice Selector (could be a dropdown or radio button) are dynamic. They depend on the selection of the manufacturer Selector.
{
"schema": "https://docs.uxtly.com/ai-schema",
"title": "Chained Selectors Example",
"groups": [
{
"id": "j",
"title": "Chained Selectors Demo",
"items": [
{
"id": "k",
"template": "SELECTOR",
"label": "Manufacturer",
"selector_source_group_id": "a",
"selector_source_item_id": "c"
},
{
"id": "A",
"template": "SELECTOR",
"label": "Model",
"selector_source_group_id": "i",
"selector_source_item_id": "F",
"selector_chained_group_id": "j",
"selector_changed_item_id": "k"
}
]
},
{
"id": "a",
"title": "Manufacturer",
"color": 2,
"is_auxiliary": 1,
"items": [
{
"id": "b",
"template": "SELECTOR",
"label": "Toyota",
"selector_source_group_id": "d"
},
{
"id": "c",
"template": "SELECTOR",
"label": "Volkswagen",
"selector_source_group_id": "i",
"selector_source_item_id": "F"
}
]
},
{
"id": "d",
"title": "Toyota",
"color": 6,
"is_auxiliary": 1,
"items": [
{
"id": "D",
"template": "PARAGRAPH",
"label": "Camry"
},
{
"id": "C",
"template": "PARAGRAPH",
"label": "Corolla"
},
{
"id": "E",
"template": "PARAGRAPH",
"label": "RAV4"
}
]
},
{
"id": "i",
"title": "Volkswagen",
"color": 6,
"is_auxiliary": 1,
"items": [
{
"id": "F",
"template": "PARAGRAPH",
"label": "Arteon"
},
{
"id": "G",
"template": "PARAGRAPH",
"label": "Jetta"
},
{
"id": "H",
"template": "PARAGRAPH",
"label": "Passat"
}
]
}
]
}
Example: Fahrenheit to Celsius
This formula example shows how Nested Groups act as mathematical parentheses. In other words, deeper nested Groups need to be computed before their parent(s). Also, since the position of a Nested Group is dictated by an Item’s position, Nested Groups can also have an arithmetic operator.
{
"schema": "https://docs.uxtly.com/ai-schema",
"title": "Fahrenheit to Celsius",
"groups": [
{
"id": "j",
"title": "°C",
"is_auxiliary": 1,
"has_formula": 1,
"decimals": 1,
"ai_hint_total": "100.0",
"output_links": [
{
"group_id": "a",
"item_id": "o"
}
],
"items": [
{
"id": "n",
"nested_group_id": "g",
"template": "AI_HINT_GROUP_HOUSE",
"value": "0.555555555555556",
"operator": "*"
},
{
"id": "m",
"nested_group_id": "d",
"template": "AI_HINT_GROUP_HOUSE",
"value": "180",
"operator": "*"
}
]
},
{
"id": "a",
"title": "Fahrenheit to Celsius",
"items": [
{
"id": "c",
"output_links": [
{
"group_id": "d",
"item_id": "e"
}
],
"label": "°F",
"value": "212"
},
{
"id": "o"
}
]
},
{
"id": "d",
"ai_hint_is_nested": 1,
"has_formula": 1,
"ai_hint_total": "180",
"items": [
{
"id": "e"
},
{
"id": "f",
"value": "32",
"operator": "-"
}
]
},
{
"id": "g",
"ai_hint_is_nested": 1,
"has_formula": 1,
"ai_hint_total": "0.555555555555556",
"items": [
{
"id": "h",
"value": "5"
},
{
"id": "i",
"value": "9",
"operator": "/"
}
]
}
]
}
Example: Shopping List
The Group in this example has formula_preset='SUM_ALL',
which adds all Item’s with numeric value.
{
"schema": "https://docs.uxtly.com/ai-schema",
"title": "Shopping List",
"groups": [
{
"id": "a",
"title": "Shopping List",
"has_formula": 1,
"formula_preset": "SUM_ALL",
"number_format": "CURRENCY",
"ai_hint_total": "17",
"items": [
{
"id": "b",
"label": "Milk",
"value": "4",
"number_format": "CURRENCY"
},
{
"id": "d",
"label": "Eggs",
"value": "8.00",
"number_format": "CURRENCY"
},
{
"id": "c",
"label": "Bread",
"value": "5",
"number_format": "CURRENCY"
}
]
}
]
}
Example: Selector and Checkbox in Formula
This example illustrates how the numeric `value` of checkbox and selector Items are used in formulas. For that, they have to have a numeric `value` and an `operator`.
{
"schema": "https://docs.uxtly.com/ai-schema",
"title": "Selectors and Checkbox in Formula",
"groups": [
{
"id": "a",
"title": "Customize your product",
"has_formula": 1,
"number_format": "CURRENCY",
"ai_hint_total": "125",
"items": [
{
"id": "h",
"label": "Price",
"value": "100.00",
"is_read_only": 1,
"number_format": "CURRENCY"
},
{
"id": "b",
"template": "SELECTOR",
"label": "Gold Plating",
"value": "20",
"operator": "+",
"selector_source_group_id": "c",
"selector_source_item_id": "g"
},
{
"id": "i",
"template": "CHECKBOX",
"label": "Gift Wrap (+$5)",
"value": "1",
"operator": "+"
},
{
"id": "j",
"is_auxiliary": 1,
"value": "5",
"operator": "*",
"number_format": "CURRENCY"
}
]
},
{
"id": "c",
"title": "Gold Plating",
"is_auxiliary": 1,
"items": [
{
"id": "e",
"label": "No plating",
"value": "0",
"number_format": "CURRENCY"
},
{
"id": "g",
"label": "18K (+$20)",
"value": "20",
"number_format": "CURRENCY"
},
{
"id": "f",
"label": "24K (+$30)",
"value": "30",
"number_format": "CURRENCY"
}
]
}
]
}
Example: Paint Calculator
In this example notice how a Nested Group computed total is part of the formula for its parent Group computed total.
{
"schema": "https://docs.uxtly.com/ai-schema",
"title": "Paint Calculator",
"groups": [
{
"id": "R",
"title": "Total Cost",
"is_auxiliary": 1,
"has_formula": 1,
"number_format": "CURRENCY",
"ai_hint_total": "60",
"output_links": [
{
"group_id": "l",
"item_id": "X"
}
],
"items": [
{
"id": "Z",
"nested_group_id": "G",
"template": "AI_HINT_GROUP_HOUSE",
"value": "2"
},
{
"id": "V",
"output_links": [
{
"group_id": "l",
"item_id": "W"
}
],
"label": "Cost per Gallon",
"value": "30.00",
"operator": "*",
"number_format": "CURRENCY"
}
]
},
{
"id": "be",
"title": "Paint Calculator",
"items": [
{
"id": "bj",
"nested_group_id": "h",
"template": "AI_HINT_GROUP_HOUSE"
},
{
"id": "bk",
"template": "SELECTOR",
"output_links": [
{
"group_id": "v",
"item_id": "x"
}
],
"label": "Wall Finish",
"value": "400",
"selector_source_group_id": "q",
"selector_source_item_id": "r"
},
{
"id": "bl",
"nested_group_id": "l",
"template": "AI_HINT_GROUP_HOUSE"
}
]
},
{
"id": "q",
"title": "Gallon Coverage by Wall Finish (sq. ft.)",
"is_auxiliary": 1,
"items": [
{
"id": "r",
"label": "Smooth",
"value": "400"
},
{
"id": "s",
"label": "Textured",
"value": "350"
}
]
},
{
"id": "v",
"title": "Gallons Needed",
"ai_hint_is_nested": 1,
"has_formula": 1,
"rounding_digit": 2,
"ai_hint_total": "1.5",
"output_links": [
{
"group_id": "l",
"item_id": "bb"
}
],
"items": [
{
"id": "B",
"nested_group_id": "y",
"template": "AI_HINT_GROUP_HOUSE",
"value": "600"
},
{
"id": "x",
"operator": "/"
}
]
},
{
"id": "h",
"title": "Room Size",
"ai_hint_is_nested": 1,
"items": [
{
"id": "i",
"output_links": [
{
"group_id": "y",
"item_id": "z"
}
],
"label": "Width (ft)",
"value": "14"
},
{
"id": "j",
"output_links": [
{
"group_id": "y",
"item_id": "A"
}
],
"label": "Length (ft)",
"value": "16"
},
{
"id": "p",
"output_links": [
{
"group_id": "y",
"item_id": "C"
},
{
"group_id": "y",
"item_id": "F"
}
],
"label": "Height (ft)",
"value": "10"
}
]
},
{
"id": "l",
"ai_hint_is_nested": 1,
"items": [
{
"id": "bb"
},
{
"id": "K"
},
{
"id": "W"
},
{
"id": "X"
}
]
},
{
"id": "y",
"title": "Wall area (sq. ft.)",
"ai_hint_is_nested": 1,
"has_formula": 1,
"ai_hint_total": "600",
"items": [
{
"id": "z"
},
{
"id": "C",
"operator": "*"
},
{
"id": "D",
"value": "2",
"operator": "*"
},
{
"id": "A",
"operator": "+"
},
{
"id": "F",
"operator": "*"
},
{
"id": "E",
"value": "2",
"operator": "*"
}
]
},
{
"id": "G",
"title": "Gallons (Rounded)",
"ai_hint_is_nested": 1,
"has_formula": 1,
"rounding_function": "CEIL",
"ai_hint_total": "2",
"output_links": [
{
"group_id": "l",
"item_id": "K"
}
],
"items": [
{
"id": "bh",
"nested_group_id": "v",
"template": "AI_HINT_GROUP_HOUSE",
"value": "1.5"
}
]
}
]
}