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}

Java Example

HttpRequest req = HttpRequest.newBuilder(
    URI.create("https://server/api/v1/server/schema/" + id)
).GET().build();

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>

Where <namespace> is typically:

  • a topic (sensors/bme688)
  • a device type (device/bme688)
  • an application group

This topic supports:

  • Publish → Add or update schemas
  • Subscribe → Receive schemas and updates

2.1 Publish a Schema​

Topic

$SCHEMA/sensors/bme688

Payload The SchemaConfig JSON exactly as defined by the server.

Example (mosquitto_pub)

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

2.2 Subscribe for Schema Updates​

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

Clients will receive:

  • existing schema on subscription
  • updates whenever schemas change
  • deletion notices encoded as empty payloads or deleted=true

3. Schema Update Behaviour​

When a new schema is published or POSTed:

  1. MAPS validates the schema.
  2. It assigns a uniqueId if missing.
  3. The schema is stored in the repository.
  4. Context bindings are updated.
  5. Cached processors, transforms, and stats engines are refreshed.
  6. Subscribers of $SCHEMA/<namespace> receive update notifications.

4. Schema Deletion via MQTT​

Publish an empty payload:

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

The server removes the binding and marks the schema as deleted.

Subscribers receive:

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

5. Best Practices​

  • Always set uniqueId so clients can track revisions.
  • Use resource + interface labels to populate CoAP .well-known/core.
  • Keep schemas small and explicit.
  • Use versions (versionId) consistently.
  • Prefer REST for bulk operations, MQTT for live updates.