Handlers
Optional output fields whose value is null are treated as absent before validation when the declared field is optional and nonnullable. This tolerance applies to outputs only, as in the handler schema profile. Required fields still must satisfy their schema, and an explicitly nullable field retains null. SDK static types may require authors to omit optional values; they do not remove the host’s output tolerance.
A handler is a named verb in a namespace. Every other part of the realm names it as
namespace.verb.
handlers: { incidents: { namespace: "oncall", description: "Unresolved incidents for a batch of services, a page at a time.", input: { type: "object", properties: { serviceIds: { type: "array", items: { type: "string" } }, cursor: { type: "string" }, impact: { type: "array", items: { type: "string" } }, status: { type: "array", items: { type: "string" } }, }, required: ["serviceIds"], }, output: { type: "object" }, }, sweep: { namespace: "oncall", schedule: "0 */15 * * * *" },},The code lives in the entry file as exported functions named after the verbs. Optional SDK
handler types give each one its input, output and context. The reference snippets use
illustrative aliases from an ordinary author-side handler-types.ts; these are editor aids,
not generated realm declarations. The complete composition examples instead write their
handler signatures directly:
import type { SweepHandler } from "../handler-types";
export const sweep: SweepHandler = async (_input, ctx) => { ctx.log("sweeping status pages"); return {};};- The verb must be a JavaScript identifier.
inputandoutputare JSON Schema fragments. Left out, each is{"type": "object"}in the declaration. The host holds them to the handler schema profile: a bounded subset of JSON Schema, checked before binding, with input validated before the handler runs and output validated before the result is released.$ref,pattern,formatanduniqueItemsrefuse the binding.scheduleis a six-field cron expression (second, minute, hour, day of month, month, day of week). A scheduled handler is called with{}, so itsinputmay list norequiredfield. A schedule may not sit on a handler withonType, and may not also be declared withdefineSchedule("<verb>", ...)in a TypeScript entry.onTypeturns the handler into a method on a graph label, and may not be blank.classNamenames the class the sandbox instantiates for that method: it needsonType, may not be blank, and is refused whenhostis"wasm".- Declaring a handler grants it nothing. The owner approves each handler at admission.

