SubverseInfo

Fields

This section documents version 6 of the protocol (_v is the constant "6"). Each message has its own table listing the payload’s field name, its JSON type, whether it is required, and what it means. The Expanse definitions an answer carries are documented after the messages, one table each.

Message model

SubverseInfo asks the room what is out there: the subverses, the worlds and platforms a user can go to, and the instances within them. One message asks, two answer. A query is broadcast by a participant that wants the expanse drawn, the subverse map being the asker today, and every participant that knows a subverse answers with what it knows: a translator for Decentraland answers with Decentraland, one for oncyber with its exhibits. Broadcast means zero or many answers, so the asker parks the query for ttl_msec and takes what arrives before the deadline. By IPSME ricochet the asker receives its own query too and, being a SubverseInfo participant itself, answers it with the subverses it curates.

An answer comes in two layouts, told apart by where instances sits. A subverse answer, JSON_EffSubverse, carries a whole world under expanse.subverse, its instances nested under it, and forbids instances at the top of expanse. An instances answer, JSON_EffInstances, carries expanse.instances and names the world they belong to by id only. A participant that speaks for a world answers with the first; one that only knows places in a world somebody else describes answers with the second.

The protocol deliberately owns only the layout. SubverseInfo pins which keys make a subverse answer and which an instances answer, and types each of them as an object or an array and nothing more. What sits under each key is an Expanse definition, owned and validated by its own schema, as Discovery leaves echo-request to Echo. A receiver validates the parts against Expanse and drops an answer that does not read: a failure there means the answer is not its own, never an error.

Every message extends a base envelope, named by its x-base: JSON_Msg for the query, JSON_Eff for the answers. 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, and for the two answers from the layout of expanse.

Message Base Payload key Purpose

JSON_MsgQuery

JSON_Msg

query

The ask: who out there knows a subverse? Carries the deadline.

JSON_EffSubverse

JSON_Eff

expanse

A subverse answer: a world, its instances nested under it. Caused by the query.

JSON_EffInstances

JSON_Eff

expanse

An instances answer: places in a world named by id. Caused by the query.

Each message is published under its own $id (under https://root-interface.se/protocols/SubverseInfo/), named as in the table. The shared definition _v lives under SubverseInfo/definitions.

Common to every message

Field Type Required Description

subverse_info

string

yes

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

JSON_MsgQuery

The ask. The asker publishes it, logs it as an event with a deadline and waits: an answer is any JSON_EffSubverse or JSON_EffInstances whose _cause is this message. The payload is closed (unevaluatedProperties: false): the three fields and nothing else.

Fields of the query payload:

Field Type Required Description

name

string

yes

A label for the ask. The schema does not constrain it: the map sends SubverseInfo-expanse, older participants discovery-expanse. No responder today selects on it.

graphql

string

yes

What is being asked for, as a GraphQL selection over the expanse: query { expanse { name map logo(width: 200, height: 200) { link } platforms { name archs agents } protocols { name attr } } }. Carried, not interpreted: no responder today reads the selection, every participant answers with the whole of what it knows, and the answer’s shape is Expanse’s, not the selection’s.

ttl_msec

integer

yes

How long the asker waits for answers, in milliseconds, anchored to the message’s dt rather than to the receiver’s clock. An answer after the deadline is late; whether a late answer still counts is the asker’s affair.

JSON_EffSubverse

A subverse answer: one world, whole. The base _cause carries the query being answered, the whole message, and the asker correlates by its id. The layout requires subverse and protocols, allows info and platforms, and forbids instances at this level: a world’s instances nest under subverse.instances, so that one answer carries the world and its places together. An expanse carrying a top-level instances member fails this message whatever else it carries; it is an instances answer. The object is otherwise open; the closing is Expanse’s.

Fields of the expanse payload:

Field Type Required Description

subverse

object

yes

The world: an Expanse subverse, identity, face, map-uri and its instances. Validated against Expanse, not here.

protocols

array

yes

The protocols the world speaks: an Expanse protocols. Required, and the empty array is a statement: absence is never an omission.

info

object

no

Facts about the world: an Expanse info.

platforms

array

no

What the world runs on: an Expanse platforms.

JSON_EffInstances

An instances answer: places in a world, with the world named by id only. The layout requires instances and allows subverse, platforms and protocols. Where a subverse answer nests instances under the world, here the instances are the subject and the subverse member is a subverse-id, a uri and name and nothing else: enough for a receiver to attach the places to a world it already has, or hold them until a subverse answer for that id arrives. A participant that knows exhibits on oncyber, say, but does not speak for oncyber itself, answers this way.

Fields of the expanse payload:

Field Type Required Description

instances

array

yes

The places: an Expanse instances. The empty array validates and says: none.

subverse

object

no

The world they belong to, by id: an Expanse subverse-id, uri and name, closed.

platforms

array

no

What the places run on: an Expanse platforms.

protocols

array

no

The protocols the places speak: an Expanse protocols. Optional here, where a subverse answer requires it: places linked to a world can lean on the world’s.

Expanse definitions

The objects the answers carry are definitions of their own, kept under schema_SubverseInfo_objs/schema_Expanse.json, with their own $id and their own _v (the constant "1"). SubverseInfo binds them loosely: each member of expanse is typed as an object or an array there and validated against its Expanse definition by the participant, as in Subverse.validate(json_effSubverse.expanse.subverse).

Definition Purpose

unique-id

The identity of a verse: uri and name.

verse-header

What a subverse and an instance share: the identity plus a face, favicon and hyperport.

subverse

A world: the header plus map-uri and its instances. Closed.

subverse-id

A world by identity alone. Closed.

instances

The places in a world: an array of header plus info, each item closed.

info

Facts about a verse: age restrictions, user counts, attributes.

platforms

What a verse runs on: platform ids with their architectures or user agents.

protocols

What a verse speaks: protocols with the native, read and write attribute.

The definitions live under the schema id expanse. The schema also publishes a standalone entry point for each of the six that SubverseInfo carries, for validators that embed one schema per header:

$id (under https://root-interface.se/protocols/Definitions/Expanse/) Resolves to

Subverse

expanse#/definitions/subverse

SubverseId

expanse#/definitions/subverse-id

Instances

expanse#/definitions/instances

Info

expanse#/definitions/info

Platforms

expanse#/definitions/platforms

Protocols

expanse#/definitions/protocols

unique-id and verse-header have no entry point of their own: they are the parts the others are composed from.

unique-id

The identity of a verse, a subverse or an instance alike. Both parts are required, and the pair is what a receiver keys on: an instances answer names its world by exactly this.

Field Type Required Description

uri

string

yes

The identity. The current answers send a reverse-DNS style id, org.decentraland or io.oncyber, and for an instance the world’s id with the place appended, io.oncyber/angell; older answers send a URL. The schema asks for a string and nothing more. Where the verse is reached is the `hyperport’s affair, not the `uri’s.

name

string

yes

The display name: Decentraland, oncyber, Angell Lounge.

verse-header

What a subverse and an instance have in common: the unique-id plus a face. Composed into subverse and instances; never carried on its own.

Field Type Required Description

(unique-id members)

string

yes

The identity, uri and name. See unique-id.

favicon

string

no

The icon a map draws for the verse, as a URL.

hyperport

string or object

no

Where a user goes to get there: a Hyperport, validated against its own definition (Definitions/Hyperport) by the participant, not here; see Related schemas. A string is the full URI of the place, ipsme+https://play.decentraland.org/?position=32,-144; the object form splits it into the subverse uri and the port within it. The schema puts no type on the member.

subverse

A world: the header plus where its map is and the places in it. Closed (unevaluatedProperties: false): a member the header or this definition does not declare fails it, which is the test that keeps a subverse answer from being mistaken for anything else.

Field Type Required Description

(verse-header members)

per header

per header

The identity and face of the world: uri, name, favicon, hyperport. See verse-header.

map-uri

string

no

Where the world’s own map is, as a URL: https://genesis.city for Decentraland. A map links out to it.

instances

instances

no

The places in the world, nested: this is where a subverse answer carries them.

subverse-id

A world by identity alone: the unique-id and nothing else, closed. This is the subverse member of an instances answer: a reference to a world, not a description of it, so a favicon or a map-uri here fails it.

Field Type Required Description

uri

string

yes

The world’s identity, as in unique-id.

name

string

yes

The world’s display name.

instances

The places in a world: an array, one item per place. Each item is a header plus its info, closed. The empty array validates. A place carries no map-uri and no instances of its own: the nesting is one level, world then place.

Field Type Required Description

(verse-header members)

per header

per header

The identity and face of the place: uri, name, favicon, hyperport. See verse-header.

info

info

no

Facts about the place.

info

Facts about a verse, for a map to filter and badge on. Every member is optional and the object is open: a member not listed here passes. Beside the subverse of a subverse answer it describes the world; on an instance it describes the place.

Field Type Required Description

age-restrictions

object

no

Who may enter.

age-restrictions.min

any

no

The minimum age. Untyped by the schema; the examples send a string such as 16+.

users-count

object

no

How many are there.

users-count.active

integer

no

Users active now.

users-count.DAU

integer

no

Daily active users.

users-count.MAU

integer

no

Monthly active users.

users-count.concurrent-max

integer

no

The most users at once.

attributes

array of string

no

Free-form labels, unique within the array. The schema gives single-user and multi-user as examples, not as an enumeration.

platforms

What a verse runs on: an array, one item per platform. A platform is an id plus, where it applies, the architectures or the user agents it is reached with. The ids are open: the examples use Darwin, Windows and WebBr, the browser being a platform here as it is in the catalog.

Field Type Required Description

id

string

yes

The platform: Darwin, Windows, WebBr, and so on. The schema does not enumerate it.

archs

array of string

no

The architectures, for a native platform: arm64, x86_64, x64.

agents

array of string

no

The user agents, for a browser platform: Firefox, Chrome.

protocols

What a verse speaks: an array, one item per protocol. The attr says how the protocol relates to the verse, whether it is the verse’s native tongue and whether it can be read from and written to; a map reads it to tell a world it can translate for from one it can only link to. Not the Discovery protocols capability, which lists the transports a participant services; see Related schemas.

Field Type Required Description

id

string

yes

The protocol’s identity, reverse-DNS style: org.ethereum, org.whatwg.spec.html. Older answers send a scheme, secondlife://, or the empty string.

name

string

no

The display name: Ethereum, Hyperlink, Second Life protocol. Older answers append the version, Discovery@4.

version

string

no

The protocol version, on its own.

attr

string

yes

The attributes, as a string of flags in any combination. The schema does not enumerate them; the flags:

  • 0: native. The protocol is the verse’s own; no translator is needed.

  • r: read. The verse speaks the protocol; it can be listened to over it.

  • w: write. The verse can be spoken to over the protocol.

0rw is a protocol the verse owns and speaks both ways; r alone one a translator reads off the verse.

url

string

no

Where the protocol is specified or served, as a URL.

Schema

{
  "$id": "https://root-interface.se/protocols/SubverseInfo",
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "schemas": {
    "https://root-interface.se/protocols/SubverseInfo/definitions": {
      "$id": "https://root-interface.se/protocols/SubverseInfo/definitions",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "definitions": {
        "_v": {
          "const": "6"
        }
      }
    },
    "https://root-interface.se/protocols/SubverseInfo/JSON_MsgQuery": {
      "$id": "https://root-interface.se/protocols/SubverseInfo/JSON_MsgQuery",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "type": "object",
      "required": [
        "query",
        "subverse_info"
      ],
      "properties": {
        "query": {
          "type": "object",
          "required": [
            "name",
            "graphql",
            "ttl_msec"
          ],
          "properties": {
            "name": {
              "type": "string"
            },
            "graphql": {
              "type": "string"
            },
            "ttl_msec": {
              "type": "integer"
            }
          },
          "unevaluatedProperties": false
        },
        "subverse_info": {
          "$ref": "definitions#/definitions/_v"
        }
      },
      "x-base": "JSON_Msg"
    },
    "https://root-interface.se/protocols/SubverseInfo/JSON_EffSubverse": {
      "$id": "https://root-interface.se/protocols/SubverseInfo/JSON_EffSubverse",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "type": "object",
      "required": [
        "expanse",
        "subverse_info"
      ],
      "properties": {
        "expanse": {
          "type": "object",
          "required": [
            "subverse",
            "protocols"
          ],
          "not": {
            "required": [
              "instances"
            ]
          },
          "properties": {
            "subverse": {
              "$comment": "loosely bound: an Expanse/Subverse (https://root-interface.se/protocols/Definitions/Expanse/Subverse), validated on its own definition by the participant, not here -- the subverse itself, its instances nested under it",
              "type": "object"
            },
            "info": {
              "$comment": "loosely bound: an Expanse/Info (https://root-interface.se/protocols/Definitions/Expanse/Info), validated on its own definition by the participant, not here",
              "type": "object"
            },
            "platforms": {
              "$comment": "loosely bound: an Expanse/Platforms (https://root-interface.se/protocols/Definitions/Expanse/Platforms), validated on its own definition by the participant, not here",
              "type": "array"
            },
            "protocols": {
              "$comment": "loosely bound: an Expanse/Protocols (https://root-interface.se/protocols/Definitions/Expanse/Protocols), validated on its own definition by the participant, not here",
              "type": "array"
            }
          }
        },
        "subverse_info": {
          "$ref": "definitions#/definitions/_v"
        }
      },
      "x-base": "JSON_Eff"
    },
    "https://root-interface.se/protocols/SubverseInfo/JSON_EffInstances": {
      "$id": "https://root-interface.se/protocols/SubverseInfo/JSON_EffInstances",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "type": "object",
      "required": [
        "expanse",
        "subverse_info"
      ],
      "properties": {
        "expanse": {
          "type": "object",
          "required": [
            "instances"
          ],
          "properties": {
            "instances": {
              "$comment": "loosely bound: an Expanse/Instances (https://root-interface.se/protocols/Definitions/Expanse/Instances), validated on its own definition by the participant, not here",
              "type": "array"
            },
            "subverse": {
              "$comment": "loosely bound: an Expanse/SubverseId (https://root-interface.se/protocols/Definitions/Expanse/SubverseId), validated on its own definition by the participant, not here -- the subverse these instances belong to, by id only",
              "type": "object"
            },
            "platforms": {
              "$comment": "loosely bound: an Expanse/Platforms (https://root-interface.se/protocols/Definitions/Expanse/Platforms), validated on its own definition by the participant, not here",
              "type": "array"
            },
            "protocols": {
              "$comment": "loosely bound: an Expanse/Protocols (https://root-interface.se/protocols/Definitions/Expanse/Protocols), validated on its own definition by the participant, not here",
              "type": "array"
            }
          }
        },
        "subverse_info": {
          "$ref": "definitions#/definitions/_v"
        }
      },
      "x-base": "JSON_Eff"
    }
  }
}

Expanse schema

The definitions behind Expanse definitions, from schema_SubverseInfo_objs/.

schema_Expanse.json
{
  "$id": "https://root-interface.se/protocols/Definitions/Expanse",
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "schemas": {
    "https://root-interface.se/protocols/Definitions/Expanse/expanse": {
      "$id": "https://root-interface.se/protocols/Definitions/Expanse/expanse",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "definitions": {
        "_v": {
          "const": "1"
        },
        "unique-id": {
          "type": "object",
          "required": [
            "uri",
            "name"
          ],
          "properties": {
            "uri": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          }
        },
        "info": {
          "type": "object",
          "properties": {
            "age-restrictions": {
              "type": "object",
              "properties": {
                "min": {}
              }
            },
            "users-count": {
              "type": "object",
              "properties": {
                "active": {
                  "type": "integer"
                },
                "DAU": {
                  "type": "integer"
                },
                "MAU": {
                  "type": "integer"
                },
                "concurrent-max": {
                  "type": "integer"
                }
              }
            },
            "attributes": {
              "type": "array",
              "items": {
                "type": "string",
                "examples": [
                  "single-user",
                  "multi-user"
                ]
              },
              "uniqueItems": true
            }
          }
        },
        "verse-header": {
          "type": "object",
          "allOf": [
            {
              "$ref": "expanse#/definitions/unique-id"
            }
          ],
          "required": [],
          "properties": {
            "favicon": {
              "type": "string"
            },
            "hyperport": {
              "$comment": "loosely bound: a Hyperport (https://root-interface.se/protocols/Definitions/Hyperport), validated on its own definition by the participant, not here"
            }
          }
        },
        "instances": {
          "type": "array",
          "items": {
            "type": "object",
            "allOf": [
              {
                "$ref": "expanse#/definitions/verse-header"
              }
            ],
            "properties": {
              "info": {
                "$ref": "expanse#/definitions/info"
              }
            },
            "unevaluatedProperties": false
          }
        },
        "subverse": {
          "type": "object",
          "allOf": [
            {
              "$ref": "expanse#/definitions/verse-header"
            }
          ],
          "required": [],
          "properties": {
            "map-uri": {
              "type": "string"
            },
            "instances": {
              "$ref": "expanse#/definitions/instances"
            }
          },
          "unevaluatedProperties": false
        },
        "subverse-id": {
          "type": "object",
          "allOf": [
            {
              "$ref": "expanse#/definitions/unique-id"
            }
          ],
          "unevaluatedProperties": false
        },
        "platforms": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "id"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "archs": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "agents": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        },
        "protocols": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "id",
              "attr"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "version": {
                "type": "string"
              },
              "attr": {
                "type": "string"
              },
              "url": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "https://root-interface.se/protocols/Definitions/Expanse/Subverse": {
      "$id": "https://root-interface.se/protocols/Definitions/Expanse/Subverse",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$ref": "expanse#/definitions/subverse"
    },
    "https://root-interface.se/protocols/Definitions/Expanse/SubverseId": {
      "$id": "https://root-interface.se/protocols/Definitions/Expanse/SubverseId",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$ref": "expanse#/definitions/subverse-id"
    },
    "https://root-interface.se/protocols/Definitions/Expanse/Instances": {
      "$id": "https://root-interface.se/protocols/Definitions/Expanse/Instances",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$ref": "expanse#/definitions/instances"
    },
    "https://root-interface.se/protocols/Definitions/Expanse/Info": {
      "$id": "https://root-interface.se/protocols/Definitions/Expanse/Info",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$ref": "expanse#/definitions/info"
    },
    "https://root-interface.se/protocols/Definitions/Expanse/Platforms": {
      "$id": "https://root-interface.se/protocols/Definitions/Expanse/Platforms",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$ref": "expanse#/definitions/platforms"
    },
    "https://root-interface.se/protocols/Definitions/Expanse/Protocols": {
      "$id": "https://root-interface.se/protocols/Definitions/Expanse/Protocols",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$ref": "expanse#/definitions/protocols"
    }
  }
}

The members of expanse are left opaque in this schema because iface-gen embeds one schema per header. Consumers validate them against Expanse, and every hyperport an Expanse verse carries against Hyperport.

Field Schema Shape

x-base

JSON_Msg

The base envelopes the messages extend: JSON_Msg and JSON_Eff.

expanse.subverse, expanse.instances, expanse.info, expanse.platforms, expanse.protocols

schema_Expanse

The Expanse definitions, on this page: what sits under each key of an answer.

subverse.hyperport, instances[].hyperport

schema_Discovery

A Hyperport: where a user goes to get to the verse, a string URI or a uri plus port object. The same shape a discover asks about.

protocols[]

schema_Discovery

The sibling notion, not the same list: Discovery’s protocols are the transports a participant services, as wire spellings; Expanse’s are the protocols a world speaks, with the native, read and write attribute.

platforms[].id

schema_ProductsAndBundles

The sibling facet: a product’s platforms are what it installs on, as icon names; a verse’s are what it is reached from, with their architectures or agents. Neither is enumerated, and the vocabularies differ today.