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 |
|---|---|---|---|
|
|
|
The ask: who out there matches this body? Carries the deadline. |
|
|
|
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 |
|---|---|---|---|
|
string |
yes |
The protocol version key: the constant |
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 |
|---|---|---|---|
|
integer |
yes |
How long the asker waits for answers, in milliseconds, anchored to the message’s |
|
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,
_causecarries the discover being answered, the whole message, and the body carries the matching shape: anecho-responsefor anecho-request, theprotocolsormethodsthe participant supports for a capability ask. -
Without one,
_causecarries no message. Bothnulland the empty object{}validate against the base; the spec examples writenull, 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, ahyperportwith only itsuribeing 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 |
|---|---|---|---|
|
per shape |
no |
What is being declared. See Payload shapes; the schema pins |
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 |
|---|---|---|---|
2 |
discover, announce |
A place in a subverse. Discover: who integrates this hyperport? Announce: I handle this URI. |
|
1 |
discover / announce |
Liveness: are you there? Asked and answered by participant name. |
|
2 |
discover, announce |
The message-dialect interfaces accepted, by schema hash. |
|
2 |
discover, announce |
The transport protocols serviced, plus the interfaces accepted over them. |
|
2 |
discover, announce |
The install methods executed, plus the install dialect accepted. |
|
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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
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: |
object |
object |
The place split in two: the subverse ( |
Fields of the object form:
| Field | Type | Required | Description |
|---|---|---|---|
|
string |
yes |
The subverse: the platform or world root an integration handles, such as |
|
any |
yes |
The location within the subverse: the deep link or instance, such as |
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 |
|---|---|---|---|
|
object |
no |
Who is asked. |
|
string |
no |
The participant name: the first element of the asked participant’s |
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 |
|---|---|---|---|
|
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 |
|---|---|---|---|
|
array of string |
yes |
The transport protocols serviced, as wire spellings: |
|
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 |
|---|---|---|---|
|
array of string |
yes |
The install-spec methods executed, as source+mechanism compounds: |
|
object, string values |
yes |
As interfaces: the install dialect accepted, today |
maplibre-layers
The announce of a MapLibreMessages provider: the map layers it serves, and the dialect it accepts.
| Field | Type | Required | Description |
|---|---|---|---|
|
object, string values |
yes |
As interfaces. |
|
object, object values |
yes |
A map of |
|
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"
}
}
}
Related schemas
| Field | Schema | Shape |
|---|---|---|
|
The base envelopes the messages extend: |
|
|
The install types an install-spec can name: the vocabulary the |
|
|
The |
|
|
The sibling notion: a connection point is an endpoint a consumer dials, a hyperport a place a user goes to. |
|
|
|
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. |