UniversalUI
Fields
This section documents version 7 of the protocol (_v is the constant "7"). Each message has its own table listing the payload’s field name, its JSON type, whether it is required, and what it means.
Message model
UniversalUI puts a piece of user interface on screen for a participant that has none. A translator running headless, say the one that warps a user into Decentraland, needs to ask the user something: is it all right to install the client? It has no window. So it describes the dialog in XAML, names the clicks it wants to hear about, and publishes it. A participant that does have a screen, the UUI host, renders the fragment and, when the user clicks a named control, publishes the click back as an effect caused by the fragment. The publisher never learns how or where the UI was drawn; it learns which control was clicked, and gets back the value it attached to that control when it published.
Two messages, a round trip. JSON_MsgUI_XAML is the offer: the UI, how long it stands, and the click map. JSON_EffUI is the click: one entry of that map, echoed. Broadcast means zero or many hosts may render the same fragment, and the user may click in more than one; the publisher correlates by _cause and decides for itself what a second click means. A menu is offered the same way as a dialog: a participant with something to put in the host’s menu bar publishes a <Menu> fragment with a long ttl_msec, and each menu item is a named click.
The protocol deliberately owns only the exchange. What the XAML contains is between the publisher and the host’s renderer; the schema asks for a string. What a click’s value is, is the publisher’s own: a UUID, an event index, a whole command object, anything the publisher wants back verbatim. The host carries it and never reads it.
Every message extends a base envelope, named by its x-base: JSON_Msg for the offer, JSON_Eff for the click. The base’s own fields, among them referer and the _cause back-reference of an effect, are documented on the JSON_Msg page and not repeated here. The message kind is inferred from which payload key is present.
| Message | Base | Payload key | Purpose |
|---|---|---|---|
|
|
|
The offer: a XAML fragment to render, with the clicks to report and how long it stands. |
|
|
|
The click: which named control was clicked, with the value the offer attached to it. Caused by the offer. |
Each message is published under its own $id (under https://root-interface.se/protocols/UniversalUI/), named as in the table. The shared definition _v lives under UniversalUI/definitions.
Common to every message
| Field | Type | Required | Description |
|---|---|---|---|
|
string |
yes |
The protocol version key: the constant |
JSON_MsgUI_XAML
The offer. The publisher publishes it, logs it as an event and waits: an answer is any JSON_EffUI whose _cause is this message. A host that receives it renders xaml; a participant that does not render XAML drops it. The publisher may check more than the schema does before it trusts an answer: the install prompt of tx-Decentraland parses the cause’s XAML and accepts the click only if the window title is its own.
Fields of the ui payload:
| Field | Type | Required | Description |
|---|---|---|---|
|
any |
yes |
What the UI is called. Required by the schema but left untyped; a UUID string in practice, in the examples the message’s own |
|
string |
yes |
The fragment to render, as XAML: a |
|
array of object |
no |
The click map: which handlers to report, and what to send back for each. Each item is one entry, |
|
integer |
no |
How long the offer stands, in milliseconds, anchored to the message’s |
A menu, as the identity translator offers it: two items, each a named click whose value is the command the translator wants back.
"ui": {
"id": "16075C1A-28B8-455F-B1BA-62298651CA35",
"xaml": "<Menu Name=\"Personas\">\n <MenuItem Header=\"Personas\">\n <MenuItem Header=\"Work\" IsCheckable=\"True\" Click=\"Work_Clicked\" IsChecked=\"True\" />\n <MenuItem Header=\"Personal\" IsCheckable=\"True\" Click=\"Personal_Clicked\" />\n </MenuItem>\n</Menu>",
"click": [
{ "Work_Clicked": { "id-provider": "0.1", "personas": { "set": { "active-persona": "32ea5794-d6a6-4254-90fb-c566caf19a76" } } } },
{ "Personal_Clicked": { "id-provider": "0.1", "personas": { "set": { "active-persona": "da6f14ca-3180-4e52-b716-49930c9fd5cd" } } } }
],
"ttl_msec": 80000
}
JSON_EffUI
The click. The host publishes it when the user clicks a control whose handler the offer named, caused by the offer: the base JSON_Eff requires _cause, and here it carries the JSON_MsgUI_XAML that was clicked, the whole message, XAML and click map included. The publisher correlates by the cause’s id and reads which control was clicked off action. A click on a control the offer did not name is not reported. There is no effect for a dismissed dialog or a lapsed offer: silence until the deadline is the only signal, so a publisher that needs a no has to name one, as the install prompt does with its No button.
Fields of the action payload:
| Field | Type | Required | Description |
|---|---|---|---|
|
any |
no |
One entry of the offer’s |
The click on the menu above:
"action": {
"Personal_Clicked": { "id-provider": "0.1", "personas": { "set": { "active-persona": "da6f14ca-3180-4e52-b716-49930c9fd5cd" } } }
}
The schema does not type _cause. Consumers do: the C++ validators accept an effect only if its cause reads as a JSON_MsgUI_XAML, and a publisher with a specific dialog checks the cause is that dialog before it acts.
Schema
{
"$id": "https://root-interface.se/protocols/UniversalUI",
"$schema": "https://json-schema.org/draft/2019-09/schema",
"schemas": {
"https://root-interface.se/protocols/UniversalUI/definitions": {
"$id": "https://root-interface.se/protocols/UniversalUI/definitions",
"$schema": "https://json-schema.org/draft/2019-09/schema",
"definitions": {
"_v": {
"const": "7"
}
}
},
"https://root-interface.se/protocols/UniversalUI/JSON_MsgUI_XAML": {
"$id": "https://root-interface.se/protocols/UniversalUI/JSON_MsgUI_XAML",
"$schema": "https://json-schema.org/draft/2019-09/schema",
"type": "object",
"required": [
"ui",
"universal-ui"
],
"properties": {
"ui": {
"type": "object",
"required": [
"id",
"xaml"
],
"properties": {
"xaml": {
"type": "string"
},
"click": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": false,
"patternProperties": {
"^.*$": {}
}
}
},
"ttl_msec": {
"type": "integer"
}
}
},
"universal-ui": {
"$ref": "definitions#/definitions/_v"
}
},
"x-base": "JSON_Msg"
},
"https://root-interface.se/protocols/UniversalUI/JSON_EffUI": {
"$id": "https://root-interface.se/protocols/UniversalUI/JSON_EffUI",
"$schema": "https://json-schema.org/draft/2019-09/schema",
"type": "object",
"required": [
"action",
"universal-ui"
],
"properties": {
"action": {
"type": "object"
},
"universal-ui": {
"$ref": "definitions#/definitions/_v"
}
},
"x-base": "JSON_Eff"
}
}
}
Related schemas
The payload values are left opaque in this schema: the XAML is the renderer’s to parse, and a click value is the publisher’s own, carried by the host and never read.
| Field | Schema | Shape |
|---|---|---|
|
The base envelopes the messages extend: |
|
|
The dialect pin: a participant that announces the interfaces it accepts names UniversalUI by the SHA-256 of this schema file. |