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

JSON_MsgUI_XAML

JSON_Msg

ui

The offer: a XAML fragment to render, with the clicks to report and how long it stands.

JSON_EffUI

JSON_Eff

action

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

universal-ui

string

yes

The protocol version key: the constant "7". Every UniversalUI message carries it, whatever its kind.

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

id

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 id or a fresh one.

xaml

string

yes

The fragment to render, as XAML: a <Window> for a dialog, a <Menu> for a menu. A control the publisher wants to hear about carries a Click attribute naming a handler, Click="OnButtonClick_YES"; the handler name is the key the click comes back under. The schema asks for a string and nothing more; parsing and rendering are the host’s.

click

array of object

no

The click map: which handlers to report, and what to send back for each. Each item is one entry, { "<handler>": <value> }: the key a Click handler named in the XAML, the value anything the publisher wants back when it is clicked. The value is opaque to the host and travels verbatim into the click’s action. The schema admits any object per item; the one-entry shape is the constructors' convention.

ttl_msec

integer

no

How long the offer stands, in milliseconds, anchored to the message’s dt: a dialog for minutes, a menu for as long as the publisher is up. A host takes the UI down when it lapses; a click after the deadline is late, and whether a late click still counts is the publisher’s affair. Absent, the schema puts no deadline on the offer.

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

(handler)

any

no

One entry of the offer’s click map, echoed: the key is the handler the clicked control named, the value is what the offer attached to it, verbatim. The schema pins action to an object and nothing more; one entry per click is the constructors' convention, and the empty object validates.

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"
    }
  }
}

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

x-base

JSON_Msg

The base envelopes the messages extend: JSON_Msg and JSON_Eff.

universal-ui

schema_Discovery

The dialect pin: a participant that announces the interfaces it accepts names UniversalUI by the SHA-256 of this schema file.