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 |
|---|---|---|---|
|
|
|
The ask: who out there knows a subverse? Carries the deadline. |
|
|
|
A subverse answer: a world, its instances nested under it. Caused by the query. |
|
|
|
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 |
|---|---|---|---|
|
string |
yes |
The protocol version key: the constant |
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 |
|---|---|---|---|
|
string |
yes |
A label for the ask. The schema does not constrain it: the map sends |
|
string |
yes |
What is being asked for, as a GraphQL selection over the expanse: |
|
integer |
yes |
How long the asker waits for answers, in milliseconds, anchored to the message’s |
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 |
|---|---|---|---|
|
object |
yes |
The world: an Expanse subverse, identity, face, |
|
array |
yes |
The protocols the world speaks: an Expanse protocols. Required, and the empty array is a statement: absence is never an omission. |
|
object |
no |
Facts about the world: an Expanse info. |
|
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 |
|---|---|---|---|
|
array |
yes |
The places: an Expanse instances. The empty array validates and says: none. |
|
object |
no |
The world they belong to, by id: an Expanse subverse-id, |
|
array |
no |
What the places run on: an Expanse platforms. |
|
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 |
|---|---|
|
The identity of a verse: |
|
What a subverse and an instance share: the identity plus a face, |
|
A world: the header plus |
|
A world by identity alone. Closed. |
|
The places in a world: an array of header plus |
|
Facts about a verse: age restrictions, user counts, attributes. |
|
What a verse runs on: platform ids with their architectures or user agents. |
|
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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
|---|---|---|---|
|
string |
yes |
The identity. The current answers send a reverse-DNS style id, |
|
string |
yes |
The display name: |
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 |
|---|---|---|---|
|
string |
yes |
The identity, |
|
string |
no |
The icon a map draws for the verse, as a URL. |
|
string or object |
no |
Where a user goes to get there: a Hyperport, validated against its own definition ( |
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 |
|---|---|---|---|
|
per header |
per header |
The identity and face of the world: |
|
string |
no |
Where the world’s own map is, as a URL: |
|
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 |
|---|---|---|---|
|
string |
yes |
The world’s identity, as in unique-id. |
|
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 |
|---|---|---|---|
|
per header |
per header |
The identity and face of the place: |
|
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 |
|---|---|---|---|
|
object |
no |
Who may enter. |
|
any |
no |
The minimum age. Untyped by the schema; the examples send a string such as |
|
object |
no |
How many are there. |
|
integer |
no |
Users active now. |
|
integer |
no |
Daily active users. |
|
integer |
no |
Monthly active users. |
|
integer |
no |
The most users at once. |
|
array of string |
no |
Free-form labels, unique within the array. The schema gives |
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 |
|---|---|---|---|
|
string |
yes |
The platform: |
|
array of string |
no |
The architectures, for a native platform: |
|
array of string |
no |
The user agents, for a browser platform: |
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 |
|---|---|---|---|
|
string |
yes |
The protocol’s identity, reverse-DNS style: |
|
string |
no |
The display name: |
|
string |
no |
The protocol version, on its own. |
|
string |
yes |
The attributes, as a string of flags in any combination. The schema does not enumerate them; the flags:
|
|
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"
}
}
}
Related schemas
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 |
|---|---|---|
|
The base envelopes the messages extend: |
|
|
The Expanse definitions, on this page: what sits under each key of an answer. |
|
|
A Hyperport: where a user goes to get to the verse, a string URI or a |
|
|
The sibling notion, not the same list: Discovery’s |
|
|
The sibling facet: a product’s |