@jambonz/schema 0.1.1

package/lib/validator.js

@@ -0,0 +1,137 @@
+const Ajv = require('ajv');
+const {readFileSync} = require('fs');
+const {resolve, join} = require('path');
+const debug = require('debug')('jambonz:schema:validator');
+const {normalizeJambones} = require('./normalize');
+
+const schemaDir = resolve(__dirname, '..');
+
+function loadSchema(relativePath) {
+  const fullPath = join(schemaDir, relativePath);
+  return JSON.parse(readFileSync(fullPath, 'utf-8'));
+}
+
+function discoverSchemas(subdir) {
+  const {readdirSync} = require('fs');
+  const dir = join(schemaDir, subdir);
+  try {
+    return readdirSync(dir)
+      .filter((f) => f.endsWith('.schema.json'))
+      .map((f) => f.replace('.schema.json', ''));
+  } catch {
+    return [];
+  }
+}
+
+let _ajv = null;
+let _validateApp = null;
+
+function getAjv() {
+  if (_ajv) return _ajv;
+
+  _ajv = new Ajv({
+    allErrors: false,
+    strict: false,
+    validateSchema: false,
+    logger: false,
+  });
+
+  /* register component schemas first (referenced by verb schemas) */
+  for (const name of discoverSchemas('components')) {
+    const schema = loadSchema(`components/${name}.schema.json`);
+    _ajv.addSchema(schema);
+  }
+
+  /* register callback schemas */
+  for (const name of discoverSchemas('callbacks')) {
+    const schema = loadSchema(`callbacks/${name}.schema.json`);
+    _ajv.addSchema(schema);
+  }
+
+  /* register verb schemas */
+  for (const name of discoverSchemas('verbs')) {
+    const schema = loadSchema(`verbs/${name}.schema.json`);
+    _ajv.addSchema(schema);
+  }
+
+  /* compile the root app schema */
+  const appSchema = loadSchema('jambonz-app.schema.json');
+  _validateApp = _ajv.compile(appSchema);
+
+  debug('schemas compiled successfully');
+  return _ajv;
+}
+
+/**
+ * Validate a single verb against its JSON Schema.
+ *
+ * API-compatible with @jambonz/verb-specifications validateVerb.
+ *
+ * @param {string} name - Verb name (e.g. 'say', 'gather', 'llm')
+ * @param {object} data - Verb data (without the 'verb' property)
+ * @param {object} logger - Logger instance
+ * @throws {Error} If the verb is unknown or validation fails
+ */
+function validateVerb(name, data, logger) {
+  const ajv = getAjv();
+
+  /* look up the verb schema by $id */
+  const schemaId = `https://jambonz.org/schema/verbs/${name}`;
+  const validate = ajv.getSchema(schemaId);
+  if (!validate) {
+    throw new Error(`invalid instruction: ${name}`);
+  }
+
+  /* the JSON Schema expects the full verb object including {verb: 'name'} */
+  const verbObj = {verb: name, ...data};
+  const valid = validate(verbObj);
+  if (!valid) {
+    const errors = validate.errors || [];
+    const messages = errors.map((e) => `${e.instancePath || '/'}: ${e.message}`).join('; ');
+    debug(`validation failed for ${name}: ${messages}`);
+    throw new Error(`${name}: ${messages}`);
+  }
+}
+
+/**
+ * Validate a complete jambonz application (array of verbs).
+ *
+ * API-compatible with @jambonz/verb-specifications validate.
+ *
+ * @param {object} logger - Logger instance
+ * @param {Array} obj - Array of verb objects
+ * @throws {Error} If the payload is malformed or any verb is invalid
+ */
+function validate(logger, obj) {
+  /* normalize first (handles both verb formats + transforms) */
+  const normalized = normalizeJambones(logger, obj);
+
+  /* validate each verb individually for better error messages */
+  for (const tdata of normalized) {
+    const keys = Object.keys(tdata);
+    const name = keys[0];
+    const data = tdata[name];
+    validateVerb(name, data, logger);
+  }
+}
+
+/**
+ * Validate a verb array using the root app schema (validates the full array at once).
+ *
+ * @param {Array} app - Array of verb objects in {verb: 'name', ...} format
+ * @returns {{valid: boolean, errors: Array}} Validation result
+ */
+function validateApp(app) {
+  getAjv();
+  const valid = _validateApp(app);
+  if (valid) return {valid: true, errors: []};
+  return {
+    valid: false,
+    errors: (_validateApp.errors || []).map((e) => ({
+      path: e.instancePath || '/',
+      message: e.message || 'Unknown validation error',
+    })),
+  };
+}
+
+module.exports = {validate, validateVerb, validateApp};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@jambonz/schema",
+  "version": "0.1.1",
+  "description": "JSON Schema definitions and validation for jambonz verb applications",
+  "main": "index.js",
+  "scripts": {
+    "test": "node test/",
+    "lint": "eslint lib/ index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jambonz/schema.git"
+  },
+  "author": "Dave Horton",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/jambonz/schema/issues"
+  },
+  "homepage": "https://github.com/jambonz/schema#readme",
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "debug": "^4.3.4"
+  },
+  "devDependencies": {
+    "eslint": "^9.3.0",
+    "eslint-plugin-promise": "^6.2.0",
+    "globals": "^15.3.0"
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "verbs/",
+    "components/",
+    "callbacks/",
+    "docs/",
+    "jambonz-app.schema.json",
+    "AGENTS.md"
+  ]
+}

package/verbs/alert.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/alert",
+  "minVersion": "0.9.6",
+  "title": "Alert",
+  "description": "Sends a 180 Ringing provisional response with an Alert-Info header. Used to trigger a specific ring tone or alert behavior on the caller's device before the call is answered.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "alert"
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "message": {
+      "type": "string",
+      "description": "The value to include in the Alert-Info header.",
+      "examples": [
+        "info=alert-internal",
+        "http://example.com/ringtone.wav"
+      ]
+    }
+  },
+  "required": [
+    "message"
+  ],
+  "examples": [
+    {
+      "verb": "alert",
+      "message": "info=alert-internal"
+    }
+  ]
+}

package/verbs/answer.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/answer",
+  "minVersion": "0.9.6",
+  "title": "Answer",
+  "description": "Answers an incoming call (sends a 200 OK to the SIP INVITE). Most verbs implicitly answer the call, so this verb is only needed when you want to explicitly control when the call is answered — for example, to play early media before answering.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "answer"
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    }
+  },
+  "examples": [
+    {
+      "verb": "answer"
+    }
+  ]
+}

package/verbs/conference.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/conference",
+  "minVersion": "0.9.6",
+  "title": "Conference",
+  "description": "Places the caller into a multi-party conference room. Multiple callers in the same named conference can speak to each other. Supports features like muting, recording, waiting rooms, and participant limits.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "conference"
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "name": {
+      "type": "string",
+      "description": "The name of the conference room. All callers joining the same named conference are connected together.",
+      "examples": [
+        "team-standup",
+        "customer-call-12345"
+      ]
+    },
+    "beep": {
+      "type": "boolean",
+      "description": "If true, play a beep when participants join or leave."
+    },
+    "memberTag": {
+      "type": "string",
+      "description": "A tag to identify this participant. Can be used to target specific members for actions like muting or whispering."
+    },
+    "speakOnlyTo": {
+      "type": "string",
+      "description": "If set, this participant's audio is only heard by the member with the specified memberTag. Creates a private whisper channel."
+    },
+    "startConferenceOnEnter": {
+      "type": "boolean",
+      "description": "If true (default), the conference starts when this participant joins. If false, this participant waits silently until a participant with startConferenceOnEnter=true joins."
+    },
+    "endConferenceOnExit": {
+      "type": "boolean",
+      "description": "If true, the conference ends for all participants when this participant leaves."
+    },
+    "endConferenceDuration": {
+      "type": "number",
+      "description": "Maximum duration of the conference in seconds."
+    },
+    "maxParticipants": {
+      "type": "number",
+      "description": "Maximum number of participants allowed in the conference."
+    },
+    "joinMuted": {
+      "type": "boolean",
+      "description": "If true, this participant joins the conference muted."
+    },
+    "actionHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when this participant leaves the conference."
+    },
+    "waitHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked while this participant is waiting for the conference to start. Should return verbs to play (e.g. hold music)."
+    },
+    "statusEvents": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "List of conference events to receive via the statusHook."
+    },
+    "statusHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook to receive conference status events (joins, leaves, etc.)."
+    },
+    "enterHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when this participant first enters the conference."
+    },
+    "record": {
+      "type": "object",
+      "description": "Recording configuration for the conference.",
+      "additionalProperties": true
+    },
+    "listen": {
+      "type": "object",
+      "description": "Audio streaming configuration for the conference.",
+      "additionalProperties": true
+    },
+    "distributeDtmf": {
+      "type": "boolean",
+      "description": "If true, DTMF events from this participant are distributed to all other participants."
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "examples": [
+    {
+      "verb": "conference",
+      "name": "team-standup",
+      "beep": true,
+      "startConferenceOnEnter": true,
+      "endConferenceOnExit": false,
+      "statusHook": "/conference-events"
+    }
+  ]
+}

package/verbs/config.schema.json

@@ -0,0 +1,218 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/config",
+  "minVersion": "0.9.6",
+  "title": "Config",
+  "description": "Sets session-level defaults for the call. Configures default TTS, STT, VAD, recording, streaming, and other session-wide settings. These defaults apply to all subsequent verbs unless overridden at the verb level. Typically the first verb in an application. Can be used multiple times during a call to change settings.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "config",
+      "description": "The verb name."
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "synthesizer": {
+      "$ref": "../components/synthesizer",
+      "description": "Default TTS configuration for the session."
+    },
+    "recognizer": {
+      "$ref": "../components/recognizer",
+      "description": "Default STT configuration for the session."
+    },
+    "bargeIn": {
+      "type": "object",
+      "description": "Default barge-in configuration. When enabled, callers can interrupt playing prompts with speech or DTMF.",
+      "properties": {
+        "enable": {
+          "type": "boolean"
+        },
+        "sticky": {
+          "type": "boolean",
+          "description": "If true, barge-in settings persist across verbs rather than resetting after each verb."
+        },
+        "actionHook": {
+          "$ref": "../components/actionHook"
+        },
+        "input": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "speech",
+              "digits"
+            ]
+          }
+        },
+        "minBargeinWordCount": {
+          "type": "number"
+        }
+      }
+    },
+    "ttsStream": {
+      "type": "object",
+      "description": "Default TTS streaming configuration for the session.",
+      "properties": {
+        "enable": {
+          "type": "boolean"
+        },
+        "synthesizer": {
+          "$ref": "../components/synthesizer"
+        }
+      }
+    },
+    "record": {
+      "type": "object",
+      "description": "Session-level call recording configuration.",
+      "additionalProperties": true
+    },
+    "listen": {
+      "$ref": "listen",
+      "description": "Nested listen verb — session-level audio streaming configuration."
+    },
+    "stream": {
+      "$ref": "stream",
+      "description": "Nested stream verb — session-level audio streaming configuration. Alias for 'listen'."
+    },
+    "transcribe": {
+      "$ref": "transcribe",
+      "description": "Nested transcribe verb — session-level real-time transcription configuration."
+    },
+    "amd": {
+      "$ref": "../components/amd",
+      "description": "Session-level answering machine detection configuration."
+    },
+    "fillerNoise": {
+      "$ref": "../components/fillerNoise",
+      "description": "Default filler noise configuration for the session."
+    },
+    "vad": {
+      "$ref": "../components/vad",
+      "description": "Default voice activity detection configuration for the session."
+    },
+    "notifyEvents": {
+      "type": "boolean",
+      "description": "If true, send call events (e.g. DTMF, call status changes) to the application via the status webhook."
+    },
+    "notifySttLatency": {
+      "type": "boolean",
+      "description": "If true, include STT latency measurements in webhook payloads."
+    },
+    "reset": {
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ],
+      "description": "Reset specific session-level settings to their defaults. Pass a setting name or array of setting names to reset."
+    },
+    "onHoldMusic": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL of an audio file to play when the call is placed on hold."
+    },
+    "actionHookDelayAction": {
+      "$ref": "../components/actionHookDelayAction",
+      "description": "Default configuration for handling slow webhook responses."
+    },
+    "sipRequestWithinDialogHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook to invoke when a SIP request (e.g. INFO, NOTIFY) is received within the dialog."
+    },
+    "boostAudioSignal": {
+      "oneOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "Boost (or attenuate) the audio signal in dB for the session."
+    },
+    "referHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook to invoke when a SIP REFER request is received."
+    },
+    "earlyMedia": {
+      "type": "boolean",
+      "description": "If true, allow early media (audio before call answer) for the session."
+    },
+    "autoStreamTts": {
+      "type": "boolean",
+      "description": "If true, automatically use streaming TTS for all 'say' verbs in the session."
+    },
+    "disableTtsCache": {
+      "type": "boolean",
+      "description": "If true, disable TTS caching for the session."
+    },
+    "trackTtsPlayout": {
+      "type": "boolean",
+      "description": "If true, report the actual text spoken via TTS. Requires a TTS vendor that supports alignment data (e.g. ElevenLabs). On each utterance completion or interruption, a tts_spoken event is sent to the '/streaming-event' endpoint with fields: 'text' (string — the text actually spoken) and 'bargein' (boolean — true if the user interrupted before TTS finished). See the tts-streaming-event callback schema for full details."
+    },
+    "noiseIsolation": {
+      "type": "object",
+      "description": "Noise isolation configuration to reduce background noise on call audio. Defaults to filtering inbound (caller) audio; can also filter outbound audio via the direction option.",
+      "properties": {
+        "enable": {
+          "type": "boolean"
+        },
+        "vendor": {
+          "type": "string"
+        },
+        "level": {
+          "type": "number"
+        },
+        "model": {
+          "type": "string"
+        }
+      }
+    },
+    "turnTaking": {
+      "type": "object",
+      "description": "Turn-taking detection configuration for conversational AI applications.",
+      "properties": {
+        "enable": {
+          "type": "boolean"
+        },
+        "vendor": {
+          "type": "string"
+        },
+        "threshold": {
+          "type": "number"
+        },
+        "model": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "required": [],
+  "examples": [
+    {
+      "verb": "config",
+      "synthesizer": {
+        "vendor": "elevenlabs",
+        "voice": "Rachel",
+        "language": "en-US"
+      },
+      "recognizer": {
+        "vendor": "deepgram",
+        "language": "en-US"
+      },
+      "fillerNoise": {
+        "enable": true,
+        "url": "https://example.com/sounds/typing.wav",
+        "startDelaySecs": 2
+      }
+    }
+  ]
+}

package/verbs/deepgram_s2s.schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/deepgram_s2s",
+  "minVersion": "10.1.0",
+  "title": "Deepgram S2S",
+  "description": "Shortcut for 'llm' with vendor automatically set to 'deepgram'. Connects the caller to a Deepgram model for real-time speech-to-speech voice conversation.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "../components/llm-base"
+    }
+  ],
+  "properties": {
+    "verb": {
+      "const": "deepgram_s2s",
+      "description": "The verb name."
+    },
+    "vendor": {
+      "type": "string",
+      "const": "deepgram",
+      "description": "The LLM vendor (always 'deepgram' for this shortcut)."
+    },
+    "llmOptions": {
+      "type": "object",
+      "description": "IMPORTANT: Deepgram does NOT use a 'messages' array. The llmOptions must contain a 'Settings' object with 'agent.think' (LLM provider, model, and prompt) and 'agent.speak' (TTS provider and voice model). The system prompt goes in Settings.agent.think.prompt, NOT in messages.",
+      "additionalProperties": true,
+      "examples": [
+        {
+          "Settings": {
+            "agent": {
+              "think": {
+                "provider": {
+                  "type": "open_ai",
+                  "model": "gpt-4o"
+                },
+                "prompt": "You are a helpful voice assistant."
+              },
+              "speak": {
+                "provider": {
+                  "type": "deepgram",
+                  "model": "aura-2-thalia-en"
+                }
+              }
+            }
+          }
+        }
+      ]
+    }
+  },
+  "required": [
+    "llmOptions"
+  ],
+  "examples": [
+    {
+      "verb": "deepgram_s2s",
+      "auth": {
+        "apiKey": "your-deepgram-api-key"
+      },
+      "llmOptions": {
+        "Settings": {
+          "agent": {
+            "think": {
+              "provider": {
+                "type": "open_ai",
+                "model": "gpt-4o"
+              },
+              "prompt": "You are a helpful voice assistant."
+            },
+            "speak": {
+              "provider": {
+                "type": "deepgram",
+                "model": "aura-2-thalia-en"
+              }
+            }
+          }
+        }
+      },
+      "actionHook": "/s2s-complete"
+    }
+  ]
+}