Interface Metadata & Reflection

The interface metadata store holds descriptions and JSON Schemas for WAMP procedures, topics and errors, published to Bondy as documents — versioned artifacts a developer or CI pipeline uploads at deploy time — and read through WAMP Interface Reflection. Metadata describes a URI, never a registration or a session: it changes at release cadence, is valid whether or not any callee is currently registered to serve its URI, and outlives every connection.

Documents replicate cluster-wide like other realm state. The MCP Gateway draws its tools' descriptions and schemas from this store (what it exposes is the overlay's decision, under the default curated manifest mode); reflection is the general read path any WAMP client can use.

Documents

A document carries an id, an optional version, and entries, each entry describing one (realm, kind, match_policy, uri):

{
  "id": "com.example.vehicle_api",
  "version": "1.4.0",
  "entries": [
    {
      "realm": "com.example.fleet",
      "kind": "procedure",
      "uri": "com.example.vehicle.locate",
      "description": "Returns the last known position of a vehicle.",
      "kwargs_schema": { "...": "JSON Schema" },
      "result_kwargs_schema": { "...": "JSON Schema" },
      "errors": ["com.example.error.unknown_vehicle"]
    }
  ]
}

Entry fields:

Field	Required	Meaning
realm	yes	The realm the entry belongs to. Bondy rejects the document if the realm does not exist at load time.
kind	yes	procedure, topic or error.
uri	yes	The WAMP URI described, valid under the entry's match policy.
match_policy	no	Defaults to exact.
description	no	Prose description.
format	no	The format every schema-valued field is in. json_schema_2020_12 is the default and the only accepted value.
args_schema	no	Schema for positional call/publish arguments.
kwargs_schema	no	Schema for keyword arguments.
result_args_schema	no	Schema for positional result arguments.
result_kwargs_schema	no	Schema for keyword result arguments.
errors	no	Error URIs this procedure may answer with.
version	no	The entry's own version string.

Three rules give the store its integrity:

• Replace-on-load. Loading a document whose id was loaded before replaces it: entries the new version no longer declares are removed.
• Exclusive ownership. One entry belongs to exactly one document. A document claiming a (realm, kind, match_policy, uri) another document currently owns is rejected whole.
• Atomic validation. A document is validated as a whole before anything is written — one invalid entry rejects the entire document.

Management procedures

All four procedures are master realm only. A call from any other realm fails with wamp.error.not_authorized. None of the four takes a realm argument: each entry of a document names its own realm.

bondy.interface.load(document) -> []

Loads (or replaces) a document. Errors name the first violation — an invalid entry, an unknown realm, a duplicate key inside the document, or an ownership conflict with another document.

bondy.interface.get(id) -> [document]

Returns the document as originally loaded — the source, not a parsed form.

bondy.interface.list() -> [documents]

Returns the sources of every loaded document.

bondy.interface.delete(id) -> []

Removes the document and every entry it declared.

WAMP Interface Reflection

The six reflection procedures are the read side, callable by any client on its realm. Bondy announces the reflection feature in its dealer and broker roles.

Results are authorization-projected: they answer with what the calling principal is authorized to access or provide — for a procedure, a caller that may wamp.call or wamp.register it; for a topic, one that may wamp.subscribe or wamp.publish it. Error URIs are not filtered. A describe of an entry the caller may not see answers exactly as an absent one, so the reply is not an existence oracle. A caller on a realm with security disabled sees every entry of that realm. The master realm gets no exemption: its callers see what their grants permit.

wamp.reflection.procedure.list() -> [uris]

wamp.reflection.topic.list() -> [uris]

wamp.reflection.error.list() -> [uris]

The URIs of the caller's realm's described procedures, topics or errors, filtered as above. The reflection procedures take no realm argument; a call with extra positional arguments fails with wamp.error.invalid_argument.

wamp.reflection.procedure.describe(uri) -> [entry]

wamp.reflection.topic.describe(uri) -> [entry]

wamp.reflection.error.describe(uri) -> [entry]

The full metadata entry for one URI — description, schemas, declared errors, version and the source document id that declared it.

Raises bondy.error.not_found when the caller's realm has no entry for uri, or when the caller may not see the entry. Raises wamp.error.invalid_argument when uri is not a string.

Reflection reads metadata, not the registry

An entry answers whether or not a callee is currently registered for its URI. Liveness is the registry's business — see the Registration Meta API.