openverb

OpenVerb

Lightweight helpers for working with OpenVerb verb libraries.

OpenVerb is an open, text-first standard for describing what actions an AI is allowed to perform inside an application. Instead of wiring one-off "tools" or plugins, applications expose verb libraries: JSON files that describe actions (verbs), their parameters, and their results.

This package provides TypeScript types and helper functions for loading, validating, and executing OpenVerb actions.

Installation

npm install openverb

Quick Start

import { loadLibrary, createExecutor } from 'openverb';
import coreLibrary from './openverb.core.json';

// Load library
const library = loadLibrary(coreLibrary);

// Create executor
const executor = createExecutor(library);

// Register handlers
executor.register('create_item', (params) => {
  const { collection, data } = params;
  // Your implementation here
  const item = { id: '123', ...data };
  
  return {
    verb: 'create_item',
    status: 'success',
    data: item,
  };
});

// Execute actions
const action = {
  verb: 'create_item',
  params: {
    collection: 'jobs',
    data: {
      client: 'Smith Construction',
      job_type: 'Boundary Survey',
    },
  },
};

const result = await executor.execute(action);
console.log(result);
// { verb: 'create_item', status: 'success', data: { id: '123', ... } }

Core Concepts

From the OpenVerb specification:

• Verb – An action the AI can perform (e.g. create_item, navigate, create_file)
• Verb Library – A JSON file that groups related verbs under a namespace (e.g. openverb.core)
• Action – A single request from the AI to execute a verb with parameters
• Executor – Your code that takes (verb, params) and performs the real work

API Reference

loadLibrary(source)

Load a verb library from a JSON object or string.

import library from './my-library.json';
const loaded = loadLibrary(library);

buildRegistry(library)

Build a verb registry for quick lookup by verb name.

import { buildRegistry } from 'openverb';

const registry = buildRegistry(library);
const verbDef = registry['create_item'];

validateAction(action, verbDef)

Validate an action against a verb definition.

import { validateAction } from 'openverb';

const validation = validateAction(action, verbDef);
if (!validation.valid) {
  console.error(validation.error);
}

createExecutor(library)

Create a simple executor with handler registration.

const executor = createExecutor(library);

// Register handlers
executor.register('create_item', async (params) => {
  // Your implementation
  return { verb: 'create_item', status: 'success', data: {...} };
});

// Execute actions
const result = await executor.execute(action);

Executor methods:

• register(verbName, handler) - Register a handler for a verb
• execute(action) - Execute an action
• getRegistry() - Get the verb registry
• getVerbs() - Get list of verb names
• getVerb(name) - Get a specific verb definition

TypeScript Types

Full TypeScript support included:

import type {
  VerbLibrary,
  Verb,
  Action,
  ActionResult,
  VerbHandler,
} from 'openverb';

const library: VerbLibrary = {
  namespace: 'my.app',
  version: '1.0.0',
  verbs: [...]
};

const action: Action = {
  verb: 'create_item',
  params: {...}
};

const handler: VerbHandler = (params) => {
  return {
    verb: 'create_item',
    status: 'success',
    data: {...}
  };
};

Verb Library Format

Based on the official spec:

{
  "namespace": "openverb.core",
  "version": "0.1.0",
  "description": "Core verbs for AI-driven applications",
  "verbs": [
    {
      "name": "create_item",
      "category": "data",
      "description": "Create a new item in a logical collection",
      "params": {
        "collection": {
          "type": "string",
          "description": "Collection name",
          "required": true
        },
        "data": {
          "type": "object",
          "description": "Item data",
          "required": true
        }
      },
      "returns": {
        "id": {
          "type": "string",
          "description": "Created item ID"
        },
        "data": {
          "type": "object",
          "description": "Created item with system fields"
        }
      },
      "destructive": false,
      "requires_confirmation": false
    }
  ]
}

Complete Example

import { loadLibrary, createExecutor } from 'openverb';
import type { Action } from 'openverb';

// Simple in-memory database
const db: Record<string, any[]> = {
  jobs: [],
};

// Load library
const library = loadLibrary({
  namespace: 'my.app',
  version: '1.0.0',
  verbs: [
    {
      name: 'create_item',
      category: 'data',
      description: 'Create an item',
      params: {
        collection: { type: 'string', description: 'Collection', required: true },
        data: { type: 'object', description: 'Data', required: true },
      },
    },
    {
      name: 'list_items',
      category: 'data',
      description: 'List items',
      params: {
        collection: { type: 'string', description: 'Collection', required: true },
      },
    },
  ],
});

// Create executor
const executor = createExecutor(library);

// Register handlers
executor.register('create_item', (params) => {
  const { collection, data } = params;
  if (!db[collection]) db[collection] = [];
  
  const id = String(db[collection].length);
  const item = { id, ...data };
  db[collection].push(item);
  
  return {
    verb: 'create_item',
    status: 'success',
    data: item,
  };
});

executor.register('list_items', (params) => {
  const { collection } = params;
  return {
    verb: 'list_items',
    status: 'success',
    items: db[collection] || [],
  };
});

// Execute actions
async function main() {
  // Create item
  const createAction: Action = {
    verb: 'create_item',
    params: {
      collection: 'jobs',
      data: {
        client: 'Smith Construction',
        job_type: 'Boundary Survey',
      },
    },
  };
  
  const result1 = await executor.execute(createAction);
  console.log('Created:', result1);
  
  // List items
  const listAction: Action = {
    verb: 'list_items',
    params: { collection: 'jobs' },
  };
  
  const result2 = await executor.execute(listAction);
  console.log('Jobs:', result2);
}

main();

Using with AI Models

// 1. Provide the library to the AI in your prompt
const verbs = executor.getVerbs();
const prompt = `
Available actions: ${verbs.join(', ')}

You can perform these actions by responding with:
{ "verb": "create_item", "params": { "collection": "jobs", "data": {...} } }
`;

// 2. Parse AI response and execute
const aiResponse = '{"verb":"create_item","params":{...}}';
const action = JSON.parse(aiResponse);
const result = await executor.execute(action);

OpenVerb Core Library

The official openverb.core library includes these verbs:

Data:

• create_item - Create a new item in a collection
• get_item - Fetch a single item by ID
• list_items - List items with optional filtering
• update_item - Update fields on an item
• delete_item - Delete an item
• search_items - Search items with free-text query

File System:

• create_file - Create a new file
• read_file - Read file contents
• write_file - Write/overwrite file
• delete_file - Delete a file

Navigation:

• navigate - Navigate to a route/view

Communication:

• notify_user - Show user notification

System:

• log_message - Write to application log
• run_command - Execute pre-approved command

Analysis:

• calculate - Perform calculations

NLP:

• summarize_text - Generate text summaries
• transform_text - Transform text (rewrite, translate, etc.)

Download from: https://github.com/sgthancel/openverb/blob/main/libraries/openverb.core.json

Philosophy

From the OpenVerb README:

AI already "thinks" and talks in verbs. OpenVerb turns that into a clear, reusable action API.

OpenVerb is:

• ✅ Language-native – Verbs are how humans and AIs naturally express actions
• ✅ Text-first – Works with any LLM that can read/write text
• ✅ Framework-agnostic – Use with agents, tools, MCP, or your own executor
• ✅ Simple JSON – Verb libraries are just JSON files

Links

• Specification
• Core Library
• Examples
• Website

License

MIT © Roman Hancel