Params JSON Schema

Registry entries may include paramsJsonSchema — a JSON Schema draft-07 subset that describes the whole positional args array as a tuple (one schema entry per argument index).

Think of RPC args as args: [arg0, arg1, …]. The schema is always shaped like an array with items: [ … ], not a schema for a single object argument (unless you only have one positional arg).

Tuple shape (one argument)

For a service method greet(name: string) registered as Greeter.greet, the tuple has one slot:


import { cat, Return } from '@gloocan/cat-inspector'
 
const greetSchema = {
	type: 'array',
	minItems: 1,
	maxItems: 1,
	items: [{ type: 'string', minLength: 1 }],
}
 
export const Greeter = cat(
	'Greeter.greet',
	function greet(name: string) {
		return Return('OK', { message: `Hello, ${name}` })
	},
	{ paramsJsonSchema: greetSchema },
)

minItems / maxItems should match how many parameters the catalog entry expects.
items[0] validates args[0] when QA (or your code) calls rpc:call with args: ['Ada'].

Two positional arguments

For createOrder(sku: string, qty: number):


import { catModule, Return } from '@gloocan/cat-inspector'
 
const createOrderSchema = {
	type: 'array',
	minItems: 2,
	maxItems: 2,
	items: [
		{ type: 'string', minLength: 1 },
		{ type: 'integer', minimum: 1 },
	],
}
 
export const Orders = catModule(
	'Orders',
	{
		createOrder(sku: string, qty: number) {
			return Return('ORDER_OK', { sku, qty })
		},
	},
	{ createOrder: { paramsJsonSchema: createOrderSchema } },
)

Valid RPC args: ['sku-42', 3]. Invalid: ['sku-42', 0] or ['only-one-arg'].

Attach schema after registration

If the function is already in the registry, use registerParamsJsonSchema:


import { registerParamsJsonSchema } from '@gloocan/cat-inspector'
 
registerParamsJsonSchema('RegP.f', {
	type: 'array',
	minItems: 1,
	maxItems: 1,
	items: [{ type: 'string', minLength: 1 }],
})

The fnKey must already exist; otherwise registration throws.

Turn on validation at invoke time

Schemas are stored on the catalog entry, but executeRPC only checks them when opted in:


import { setRpcSerializationConfig } from '@gloocan/cat-inspector'
 
setRpcSerializationConfig({ validateParamsJsonSchema: true })

You can also set rpcSerialization.validateParamsJsonSchema on attachCatRPC / bootstrap options (see Serialization).

With validation on:

args: [3] for a number schema → invoke runs.
args: ['nope'] for a number schema → invoke does not run the handler; client gets an error response.

With validation off, bad args still reach the handler (same as omitting a schema).

Call the validator directly

For a custom gateway or tests:


import { validateArgsAgainstParamsJsonSchema } from '@gloocan/cat-inspector'
 
const schema = {
	type: 'array',
	minItems: 1,
	maxItems: 1,
	items: [{ type: 'number' }],
}
 
const good = validateArgsAgainstParamsJsonSchema('In.f', schema, [42])
// { ok: true }
 
const bad = validateArgsAgainstParamsJsonSchema('In.f', schema, ['not-a-number'])
// { ok: false, message: 'paramsJsonSchema validation failed for In.f: ...' }

`validateArgsAgainstParamsJsonSchema`


function validateArgsAgainstParamsJsonSchema(
	fnKey: string,
	schema: Record<string, unknown>,
	args: unknown[],
): { ok: true } | { ok: false; message: string }

`resetParamsJsonSchemaValidators`

Clears cached AJV validators — call in tests when schemas change between cases:


import { resetParamsJsonSchemaValidators } from '@gloocan/cat-inspector'
 
afterEach(() => {
	resetParamsJsonSchemaValidators()
})

Failure shape on RPC

When validation fails inside executeRPC, the client receives RpcResponse with:

status: 'error'
label: INPUT_SCHEMA_INVALID
error.code: INPUT_SCHEMA_INVALID

The handler is not called.