Discovery

Fields

This section documents version 5 of the protocol (_v is the constant "5"). Each message has its own table listing the payload’s field name, its JSON type, whether it is required, and what it means. The payload shapes a discover or announce can carry are documented after the messages, one table each.

Message model

Discovery has two messages and no required order between them. A discover asks: a participant broadcasts it, and every participant that recognises the body answers with an announce caused by it. An announce declares: this is what I am, or serve. It needs no discover; a participant sends one whenever it has something to declare, coming up being the common case, and the base _cause is what tells an answer from a standalone declaration. Broadcast means zero or many answers, so the asker parks the discover for ttl_msec and takes what arrives before the deadline.

The protocol deliberately owns only the envelope. discover pins ttl_msec and nothing else; announce pins nothing. What a discover asks about, and what an announce declares, is a payload shape owned and validated by its own definition and chosen by context: a participant validates the body against the shapes it serves and drops what it does not recognise. Enriching Discovery with those members would duplicate definitions the sibling schemas already own.

Every message extends a base envelope, named by its x-base: JSON_Msg for the discover, JSON_Eff for the announce. 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_MsgDiscover

JSON_Msg

discover

The ask: who out there matches this body? Carries the deadline.

JSON_EffAnnounce

JSON_Eff

announce

The declaration: this is what I am, or serve. Sent on its own, or caused by a discover as its answer.

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

Common to every message

Field Type Required Description

Discovery

string

yes

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

JSON_MsgDiscover

The ask. The asker publishes it, logs it as an event with a deadline and waits: an answer is any JSON_EffAnnounce whose _cause is this message. The body is open. Beyond ttl_msec it carries one or more payload-shape members, say a hyperport or an echo-request, that name what is being asked about; a participant that recognises none of them drops the message.

Fields of the discover payload:

Field Type Required Description

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.

(payload-shape members)

per shape

no

What is being asked about. See Payload shapes; the schema does not constrain them.

JSON_EffAnnounce

A declaration, sent with or without a discover. The base JSON_Eff requires the _cause key on every effect and puts no type on its value, so the key is always present on an announce; what varies is what it holds.

  • With a discover, _cause carries the discover being answered, the whole message, and the body carries the matching shape: an echo-response for an echo-request, the protocols or methods the participant supports for a capability ask.

  • Without one, _cause carries no message. Both null and the empty object {} validate against the base; the spec examples write null, the JavaScript responders today emit {}. The body says what the participant is, or serves: a participant that just came up tells the room what it serves, a hyperport with only its uri being enough.

A receiver tells the two apart by correlation, not by the value of _cause: an announce whose _cause carries the id of one of its own logged discovers is an answer to it; anything else, whether null, {} or somebody else’s discover, is a declaration to it. By IPSME ricochet a participant also receives its own announces.

Fields of the announce payload:

Field Type Required Description

(payload-shape members)

per shape

no

What is being declared. See Payload shapes; the schema pins announce to an object and nothing more.

Payload shapes

Each shape is a definition of its own, kept under schema_Discovery_objs/, with its own $id and its own _v. A shape validates a whole discover or announce body, as in Interfaces.validate(json_msgDiscover.discover). Members the body carries beyond the shape’s own are outside its concern and pass untouched, so one body can satisfy several shapes at once.

Shape _v Carried in Asks, or declares

hyperport

2

discover, announce

A place in a subverse. Discover: who integrates this hyperport? Announce: I handle this URI.

echo-request / echo-response

1

discover / announce

Liveness: are you there? Asked and answered by participant name.

interfaces

2

discover, announce

The message-dialect interfaces accepted, by schema hash.

protocols

2

discover, announce

The transport protocols serviced, plus the interfaces accepted over them.

install-methods

2

discover, announce

The install methods executed, plus the install dialect accepted.

maplibre-layers

1

announce

The map layers a MapLibreMessages provider serves, plus the interfaces accepted.

The interfaces member recurs in four of the shapes. It is the pin that makes a capability answer usable: a participant that services the transport but does not accept the asker’s dialect is of no use to the asker.

Each shape publishes a standalone entry point, for validators that embed one schema per header:

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

Hyperport

hyperport#/definitions/hyperport

Interfaces

interfaces#/definitions/interfaces

Protocols

protocols#/definitions/protocols

InstallMethods

install-methods#/definitions/install-methods

MapLibreLayers

maplibre-layers#/definitions/maplibre-layers

Echo is the exception: it publishes EchoRequest and EchoResponse under https://root-interface.se/protocols/Echo/, as message-style shapes rather than a definition.

hyperport

A place a user can go to in a subverse: a world, a platform, a location in it. Where a connection point is an endpoint a consumer dials, a hyperport is a destination; see Related schemas. A oneOf of two forms.

Form Type Shape

string

string

The full URI of the place, deep link included: https://play.decentraland.org/?position=32,-144. The way a map asks; an integration matches it by prefix against the URIs it handles.

object

object

The place split in two: the subverse (uri) and the location within it (port).

Fields of the object form:

Field Type Required Description

uri

string

yes

The subverse: the platform or world root an integration handles, such as https://play.decentraland.org. An uncaused announce carrying a hyperport with only its uri is enough; a participant could not otherwise announce without first having received a discover.

port

any

yes

The location within the subverse: the deep link or instance, such as https://play.decentraland.org/?position=32,-144. Required by the schema but left untyped; a string in practice. Note that the uri-only announce above does not validate against this arm; consumers today read an announce’s hyperport without validating it.

echo-request, echo-response

Liveness by name. A discover carries an echo-request listing the participants it wants to hear from; each one that finds its own name in the list answers with an echo-response. A participant not named drops the discover. The names are the participant element of the base referer tuple.

echo-request is an array of items, one per participant asked:

Field Type Required Description

referer

object

no

Who is asked.

referer.participant

string

no

The participant name: the first element of the asked participant’s referer. A responder answers when this equals its own.

echo-response is an array of objects, unconstrained. Today it is the empty array: the announce’s own referer says who answered, and its _cause says to what.

interfaces

The message-dialect interfaces a participant accepts. Carried alone, or as the interfaces member of protocols, install-methods and maplibre-layers, where it is the pin that makes a capability answer usable.

Field Type Required Description

interfaces

object, string values

yes

A map of interface name to the SHA-256 of its schema file. The hash is the identity, byte-exact, so a schema bump changes the identity asked for; the name is the human-readable label. Two participants speak the same dialect when the hashes match. In a discover: the dialects the asker needs a receiver for. In an announce: the dialects the announcer accepts.

protocols

Transport capability: who services these transports? A store gathers the distinct protocols off the connection points of a product batch and asks once; the participants that service them answer with their own list.

Field Type Required Description

protocols

array of string

yes

The transport protocols serviced, as wire spellings: ipsme+tcp+l4end, http+json-rpc, and so on; the same vocabulary as a connection point’s protocol. A participant with none states the empty array: absence is never an omission.

interfaces

object, string values

yes

As interfaces: the dialects accepted over those transports.

install-methods

Install capability: who executes these install methods, and do you speak my install dialect? A store asks with the methods of the products in view; an installer agent answers with the methods it executes and the Installer dialect it accepts. A store answers for observable itself, since nobody else installs a curated list, and claims no interfaces for it, since observable rides no install dialect.

Field Type Required Description

methods

array of string

yes

The install-spec methods executed, as source+mechanism compounds: registry+self-contained, observable, and so on. The vocabulary is the install types of InstallSpec. A participant with none states the empty array: absence is never an omission.

interfaces

object, string values

yes

As interfaces: the install dialect accepted, today Installer.

maplibre-layers

The announce of a MapLibreMessages provider: the map layers it serves, and the dialect it accepts.

Field Type Required Description

interfaces

object, string values

yes

As interfaces.

layers

object, object values

yes

A map of layer_id to the layer’s display metadata. "Layer" is MapLibreMessages' own wire vocabulary (layer_id, layer-fragment, layer-remove), reused here as-is.

layers.*.name

string

yes

The layer’s display name.

Schema

{
  "$id": "https://root-interface.se/protocols/Discovery",
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "schemas": {
    "https://root-interface.se/protocols/Discovery/definitions": {
      "$id": "https://root-interface.se/protocols/Discovery/definitions",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "definitions": {
        "_v": {
          "const": "5"
        }
      }
    },
    "https://root-interface.se/protocols/Discovery/JSON_MsgDiscover": {
      "$id": "https://root-interface.se/protocols/Discovery/JSON_MsgDiscover",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "type": "object",
      "required": [
        "discover",
        "Discovery"
      ],
      "properties": {
        "discover": {
          "type": "object",
          "required": [
            "ttl_msec"
          ],
          "properties": {
            "ttl_msec": {
              "type": "integer"
            }
          }
        },
        "Discovery": {
          "$ref": "definitions#/definitions/_v"
        }
      },
      "x-base": "JSON_Msg"
    },
    "https://root-interface.se/protocols/Discovery/JSON_EffAnnounce": {
      "$id": "https://root-interface.se/protocols/Discovery/JSON_EffAnnounce",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "type": "object",
      "required": [
        "announce",
        "Discovery"
      ],
      "properties": {
        "announce": {
          "type": "object"
        },
        "Discovery": {
          "$ref": "definitions#/definitions/_v"
        }
      },
      "x-base": "JSON_Eff"
    }
  }
}

Payload schemas

The definitions behind Payload shapes, from schema_Discovery_objs/.

schema_Hyperport.json
{
  "$id": "https://root-interface.se/protocols/Definitions/Hyperport",
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "schemas": {
    "https://root-interface.se/protocols/Definitions/hyperport": {
      "$id": "https://root-interface.se/protocols/Definitions/hyperport",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "definitions": {
        "_v": {
          "const": "2"
        },
        "hyperport": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "object",
              "required": [
                "uri",
                "port"
              ],
              "properties": {
                "uri": {
                  "type": "string"
                }
              }
            }
          ]
        }
      }
    },
    "https://root-interface.se/protocols/Definitions/Hyperport": {
      "$id": "https://root-interface.se/protocols/Definitions/Hyperport",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$ref": "hyperport#/definitions/hyperport"
    }
  }
}
schema_Echo.json
{
  "$id": "https://root-interface.se/protocols/Echo",
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "schemas": {
    "https://root-interface.se/protocols/Echo/definitions": {
      "$id": "https://root-interface.se/protocols/Echo/definitions",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "definitions": {
        "_v": {
          "const": "1"
        }
      }
    },
    "https://root-interface.se/protocols/Echo/EchoRequest": {
      "$id": "https://root-interface.se/protocols/Echo/EchoRequest",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "referer": {
            "type": "object",
            "properties": {
              "participant": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "https://root-interface.se/protocols/Echo/EchoResponse": {
      "$id": "https://root-interface.se/protocols/Echo/EchoResponse",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  }
}
schema_Interfaces.json
{
  "$id": "https://root-interface.se/protocols/Definitions/Interfaces",
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "schemas": {
    "https://root-interface.se/protocols/Definitions/interfaces": {
      "$id": "https://root-interface.se/protocols/Definitions/interfaces",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "definitions": {
        "_v": {
          "const": "2"
        },
        "interfaces": {
          "$comment": "validates a whole discover/announce PAYLOAD carrying an `interfaces` member (the SoS idiom: Interfaces.validate(json_msgDiscover.discover)); sibling members a payload may carry (e.g. SoS's `methods`) are outside this schema's concern and pass untouched",
          "type": "object",
          "required": [
            "interfaces"
          ],
          "properties": {
            "interfaces": {
              "$comment": "the message-dialect interfaces accepted: a MAP of interface name -> sha256 of its SCHEMA FILE (the hash is the identity, the name the label)",
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "https://root-interface.se/protocols/Definitions/Interfaces": {
      "$id": "https://root-interface.se/protocols/Definitions/Interfaces",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$ref": "interfaces#/definitions/interfaces"
    }
  }
}
schema_Protocols.json
{
  "$id": "https://root-interface.se/protocols/Definitions/Protocols",
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "schemas": {
    "https://root-interface.se/protocols/Definitions/protocols": {
      "$id": "https://root-interface.se/protocols/Definitions/protocols",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "definitions": {
        "_v": {
          "const": "2"
        },
        "protocols": {
          "type": "object",
          "required": [
            "protocols",
            "interfaces"
          ],
          "properties": {
            "protocols": {
              "$comment": "the transport protocols serviced (wire spellings, e.g. \"ipsme+tcp+l4end\"); a participant with none states the empty array -- absence is never an omission",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "interfaces": {
              "$comment": "the message-dialect interfaces accepted: a MAP of interface name -> sha256 of its SCHEMA FILE (the hash is the identity, the name the label)",
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "https://root-interface.se/protocols/Definitions/Protocols": {
      "$id": "https://root-interface.se/protocols/Definitions/Protocols",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$ref": "protocols#/definitions/protocols"
    }
  }
}
schema_InstallMethods.json
{
  "$id": "https://root-interface.se/protocols/Definitions/InstallMethods",
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "schemas": {
    "https://root-interface.se/protocols/Definitions/install-methods": {
      "$id": "https://root-interface.se/protocols/Definitions/install-methods",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "definitions": {
        "_v": {
          "const": "2"
        },
        "install-methods": {
          "type": "object",
          "required": [
            "methods",
            "interfaces"
          ],
          "properties": {
            "methods": {
              "$comment": "the install-spec METHODS executed (source+mechanism compounds, e.g. \"registry+self-contained\"); a participant with none states the empty array -- absence is never an omission",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "interfaces": {
              "$comment": "the message-dialect interfaces accepted: a MAP of interface name -> sha256 of its SCHEMA FILE (the hash is the identity, the name the label)",
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "https://root-interface.se/protocols/Definitions/InstallMethods": {
      "$id": "https://root-interface.se/protocols/Definitions/InstallMethods",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$ref": "install-methods#/definitions/install-methods"
    }
  }
}
schema_MapLibreLayers.json
{
  "$id": "https://root-interface.se/protocols/Definitions/MapLibreLayers",
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "schemas": {
    "https://root-interface.se/protocols/Definitions/maplibre-layers": {
      "$id": "https://root-interface.se/protocols/Definitions/maplibre-layers",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "definitions": {
        "_v": {
          "const": "1"
        },
        "maplibre-layers": {
          "$comment": "validates a whole discover/announce PAYLOAD of a MapLibreMessages provider (the SoS idiom: MapLibreLayers.validate(json_effAnnounce.announce)); sibling members a payload may carry are outside this schema's concern and pass untouched",
          "type": "object",
          "required": [
            "interfaces",
            "layers"
          ],
          "properties": {
            "interfaces": {
              "$comment": "the message-dialect interfaces accepted: a MAP of interface name -> sha256 of its SCHEMA FILE (the hash is the identity, the name the label)",
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            },
            "layers": {
              "$comment": "the (MapLibreMessages) layers this participant serves: a MAP of layer_id -> display metadata ('layer' is that interface's own wire vocabulary — layer_id, layer-fragment, layer-remove)",
              "type": "object",
              "additionalProperties": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "https://root-interface.se/protocols/Definitions/MapLibreLayers": {
      "$id": "https://root-interface.se/protocols/Definitions/MapLibreLayers",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$ref": "maplibre-layers#/definitions/maplibre-layers"
    }
  }
}
Field Schema Shape

x-base

JSON_Msg

The base envelopes the messages extend: JSON_Msg and JSON_Eff.

install-methods.methods[]

schema_InstallSpec

The install types an install-spec can name: the vocabulary the methods array is drawn from.

protocols.protocols[]

schema_ConnectionPoint

The protocol of a connection point: the wire spellings a store harvests into its ask.

hyperport

schema_ConnectionPoint

The sibling notion: a connection point is an endpoint a consumer dials, a hyperport a place a user goes to.

(discovery service)

schema_Discovery-svc

The out-of-band registry for what broadcast cannot reach: a store registers its connection point over HTTP and a consumer queries for stores by type. Its own messages, not Discovery’s.