Skip to main content

Schema Management

This page describes how to create, update, delete, and retrieve schemas in MAPS Messaging using:

  • The REST API (/api/v1/server/schema)
  • The MQTT pub/sub interface ($SCHEMA/<namespace>)

Both methods allow full lifecycle management of schema definitions.

1. Managing Schemas via REST API​

The server exposes schema endpoints under:

/api/v1/server/schema

1.1 Add (POST)​

Endpoint

POST /api/v1/server/schema

Body format

{
  "context": "sensors/bme688",
  "schema": { ...SchemaConfig JSON... }
}

Example using Java HttpClient​

HttpClient client = HttpClient.newHttpClient();

String body = Files.readString(Path.of("bme688-schema.json"));

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://server/api/v1/server/schema"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());

1.2 Get by Schema ID (GET)​

Endpoint

GET /api/v1/server/schema/{schemaId}

1.3 Get by Context (GET)​

GET /api/v1/server/schema/context/{context}

Returns all schemas bound to that topic or pattern.

1.4 Delete Schema (DELETE)​

DELETE /api/v1/server/schema/{schemaId}

1.5 List All Schemas​

GET /api/v1/server/schema

Optional filtering using selector expressions:

GET /api/v1/server/schema?filter=resource=='sensor'

2. Managing Schemas Using MQTT​

The server provides a schema management topic:

$SCHEMA/<namespace>

2.1 Publish a Schema​

Topic

$SCHEMA/sensors/bme688

Payload The SchemaConfig JSON.

Example:

mosquitto_pub -h server -t '$SCHEMA/sensors/bme688' -f bme688-schema.json

2.2 Subscribe for Schema Updates​

mosquitto_sub -h server -t '$SCHEMA/#'

Subscribers receive existing schemas, updates, and deletion notices.

3. Schema Update Behaviour​

  1. Validate schema
  2. Assign uniqueId if missing
  3. Store in repository
  4. Update context bindings
  5. Refresh processors/transforms
  6. Notify $SCHEMA/<namespace> subscribers

4. Schema Deletion via MQTT​

Publish an empty payload:

$SCHEMA/sensors/bme688
(payload = "")

Subscribers receive:

{ "deleted": true, "uniqueId": "..." }

5. Best Practices​

  • Set uniqueId
  • Use resource + interface labels
  • Keep schemas small
  • Version consistently
  • Prefer REST for bulk ops; MQTT for live updates