Canonical protocol definitions for the Mapepire WebSocket protocol.
This package provides:
- Zod schemas for all 15 Mapepire protocol message types (requests + responses)
- TypeScript types inferred from schemas for compile-time safety
- JSON Schema files generated from Zod for cross-language consumption
- Discriminated union (
MapepireRequest) for runtime message parsing and type narrowing - PROTOCOL.md — human-readable protocol specification for client implementors
npm install @ibm/mapepire-protocol zod
zodis a peer dependency — install it alongside this package.
import { MapepireRequest } from "@ibm/mapepire-protocol";
const message = JSON.parse(rawWebSocketMessage);
const request = MapepireRequest.parse(message);
switch (request.type) {
case "sql":
console.log(request.sql); // TypeScript knows this is SqlRequest
break;
case "connect":
console.log(request.technique); // TypeScript knows this is ConnectRequest
break;
}import { SqlRequest } from "@ibm/mapepire-protocol";
const request: SqlRequest = {
id: "1",
type: "sql",
sql: "SELECT * FROM MYLIB.MYTABLE",
rows: 100,
};
// Validate at runtime
SqlRequest.parse(request);import { QueryResult, PingResponse } from "@ibm/mapepire-protocol";
const response = QueryResult.parse(serverMessage);
if (response.has_results) {
console.log(response.data);
console.log(response.metadata?.columns);
}import schema from "@ibm/mapepire-protocol/schemas/requests/sql-request.json";Or access the combined schema:
import allSchemas from "@ibm/mapepire-protocol/schemas/index.json";The generated JSON Schema files in schemas/ can be used by any language. For Python, use the jsonschema library to validate outgoing requests and incoming responses at runtime.
First, grab the schema files. You can either vendor them into your project or fetch them from the npm package:
npm pack @ibm/mapepire-protocol && tar -xzf ibm-mapepire-protocol-*.tgz package/schemasThen validate messages in Python:
import json
from pathlib import Path
from jsonschema import validate, ValidationError
# Load schemas once at import time
SCHEMA_DIR = Path("schemas")
def load_schema(name: str) -> dict:
return json.loads((SCHEMA_DIR / name).read_text())
sql_request_schema = load_schema("requests/sql-request.json")
query_result_schema = load_schema("responses/query-result.json")
# Validate an outgoing request before sending
request = {
"id": "1",
"type": "sql",
"sql": "SELECT * FROM MYLIB.MYTABLE",
"rows": 100,
}
validate(instance=request, schema=sql_request_schema) # raises on invalid
# Validate an incoming response from the server
response = json.loads(websocket.recv())
try:
validate(instance=response, schema=query_result_schema)
except ValidationError as e:
print(f"Unexpected server response: {e.message}")For full type safety, generate Python types directly from the JSON Schema files using datamodel-code-generator:
pip install datamodel-code-generator
# Generate Pydantic v2 models from all request schemas
datamodel-codegen \
--input schemas/requests/ \
--output mapepire_protocol/requests.py \
--output-model-type pydantic_v2.BaseModel
# Generate from a single schema
datamodel-codegen \
--input schemas/requests/sql-request.json \
--output mapepire_protocol/sql_request.py \
--output-model-type pydantic_v2.BaseModelThis produces typed Python classes like:
from pydantic import BaseModel
from typing import Optional
class SqlRequest(BaseModel):
id: str
type: str # const: "sql"
sql: str
rows: Optional[int] = None
terse: Optional[bool] = None| Type | Request Schema | Description |
|---|---|---|
connect |
ConnectRequest |
Establish JDBC connection |
sql |
SqlRequest |
Execute SQL statement |
prepare_sql |
PrepareSqlRequest |
Prepare SQL without executing |
prepare_sql_execute |
PrepareSqlExecuteRequest |
Prepare and execute in one round-trip |
execute |
ExecuteRequest |
Execute a prepared statement |
sqlmore |
SqlMoreRequest |
Fetch next block of rows |
sqlclose |
SqlCloseRequest |
Close cursor |
cl |
ClRequest |
Execute CL command |
dove |
DoveRequest |
Visual Explain |
ping |
PingRequest |
Health check |
getdbjob |
GetDbJobRequest |
Get job name |
getversion |
GetVersionRequest |
Get server version |
setconfig |
SetConfigRequest |
Configure tracing |
gettracedata |
GetTraceDataRequest |
Retrieve trace data |
exit |
ExitRequest |
Disconnect |
See PROTOCOL.md for the full protocol specification.
Apache-2.0