OpenVerb Specification

OpenVerb: Universal Action Language

OpenVerb is an open-source specification for describing actions in software systems. Instead of imperative code, define what users can do—not how to check it.

What is OpenVerb?

OpenVerb is a semantic language for describing actions (verbs) that software can perform. Instead of writing logic like:

if (user.hasPermission('export_data')) {
  exportData()
}

You define verbs in plain language:

{
  "namespace": "myapp.core",
  "verbs": [
    {
      "name": "export_data",
      "category": "file_system",
      "description": "Export user data to CSV or JSON",
      "parameters": ["format", "filters"]
    }
  ]
}

Verb Structure

Complete Verb Definition

{
  "name": "export_data",
  "category": "file_system",
  "description": "Export user data to various formats",
  "parameters": [
    {
      "name": "format",
      "type": "string",
      "required": true,
      "description": "Export format (csv, json, xlsx)"
    },
    {
      "name": "filters",
      "type": "object",
      "required": false,
      "description": "Data filters to apply"
    }
  ],
  "returns": {
    "type": "file",
    "description": "Downloaded file in specified format"
  },
  "examples": [
    {
      "description": "Export all data as CSV",
      "parameters": { "format": "csv" }
    }
  ]
}

Field Descriptions

name (required)

Unique identifier for the verb in snake_case

Examples: export_data,generate_report,create_task

category (required)

Semantic category for the verb

datafile_systemcommunicationanalysisworkflowaiauthenticationpayment

description (required)

Human-readable description of what the verb does

Clear, concise explanation that AI and humans can understand. This is what PaywallOS AI uses to make intelligent decisions.

Standard Categories

data

CRUD operations on data

create_record

update_record

delete_record

query_data

file_system

File operations

export_csv

upload_file

download_attachment

import_data

communication

Messaging and notifications

send_email

post_comment

share_link

notify_user

analysis

Analytics and reporting

generate_report

view_analytics

export_insights

create_dashboard

AI-powered features

generate_suggestions

ai_autocomplete

analyze_sentiment

generate_image

workflow

Process automation

approve_request

schedule_task

trigger_automation

assign_task

Example: TaskFlow App

{
  "namespace": "taskflow.core",
  "version": "1.0.0",
  "description": "Task management application verb library",
  "verbs": [
    {
      "name": "create_task",
      "category": "data",
      "description": "Create a new task with title and details"
    },
    {
      "name": "assign_task",
      "category": "workflow",
      "description": "Assign task to a team member"
    },
    {
      "name": "export_tasks",
      "category": "file_system",
      "description": "Export tasks to CSV or Excel"
    },
    {
      "name": "generate_report",
      "category": "analysis",
      "description": "Generate task completion report"
    },
    {
      "name": "ai_suggestions",
      "category": "ai",
      "description": "Get AI suggestions for task prioritization"
    },
    {
      "name": "send_reminder",
      "category": "communication",
      "description": "Send task reminder email to assignee"
    }
  ]
}

Installation

Node.js / JavaScript

npm install openverb

import { OpenVerb } from 'openverb'

const verb = new OpenVerb({
  name: "export_data",
  category: "file_system"
})

Python

pip install openverb

from openverb import OpenVerb

verb = OpenVerb(
    name="export_data",
    category="file_system"
)

OpenVerb Resources

Official Website

www.openverb.org →

GitHub Repository

github.com/sgthancel/openverb →

Video Introduction

Watch on YouTube →

PaywallOS Integration

Integration Guide →