Schema Management with the JavaScript Client

What You Will Learn

How to register Protobuf schemas on the Infinispan Server using the internal ___protobuf_metadata cache, retrieve them, and check for validation errors.

Prerequisites

Node.js 22+
An Infinispan Server running on localhost:11222

Start an Infinispan Server with Docker or Podman:

docker run -it --rm -p 11222:11222 -e USER=admin -e PASS=password quay.io/infinispan/server:latest

Tip	You can replace `docker` with `podman` in the command above if you use Podman.

Step 1: Connect to the Metadata Cache

Connect directly to the internal ___protobuf_metadata cache with text/plain encoding:

const client = await ispn.client({port: 11222, host: '127.0.0.1'}, {
    cacheName: '___protobuf_metadata',
    dataFormat: {
        keyType: 'text/plain',
        valueType: 'text/plain'
    },
    authentication: { ... }
});

Step 2: Register a Schema

Put the .proto file content with the schema name as the key:

const personProto = `syntax = "proto3";
package tutorial;

/* @Indexed */
message Person {
    /* @Keyword(projectable = true, sortable = true, normalizer = "lowercase") */
    string firstName = 1;
    /* @Keyword(projectable = true, sortable = true, normalizer = "lowercase") */
    string lastName = 2;
    /* @Basic(projectable = true, sortable = true) */
    int32 bornYear = 3;
    /* @Keyword(projectable = true, sortable = true, normalizer = "lowercase") */
    string bornIn = 4;
}`;

await client.put('person.proto', personProto);

Step 3: Retrieve and Validate

Retrieve the schema by key. Check for errors in the .errors suffix key:

const schema = await client.get('person.proto');
const errors = await client.get('person.proto.errors');

If the schema has validation errors, Infinispan stores the error messages in the person.proto.errors key.

Step 4: Run the Tutorial

npm run schemas

You should see output like:

Registered person.proto schema.

Retrieved schema:
syntax = "proto3";
package tutorial;
...

No schema errors.

Removed person.proto schema.

What’s Next

Ickle queries for querying data using registered schemas
Cache encodings for different media type formats