@openverb/format

The official parsing and validation engine for the .ov file format.

The .ov file format is a declarative, portable YAML blueprint for AI-driven semantic software workflows. Instead of executing arbitrary generated code, .ov files orchestrate standardized actions (Verbs) and seamlessly pipe data between them, allowing AI to generate safe, executable actions for your applications.

Installation

npm install @openverb/format

What is a .ov file?

A .ov file consists of metadata, user prompts (inputs), and a sequential pipeline of actions that map directly to the OpenVerb 2.0 runtime.

Example: gis-overlap.ov

version: "1.0"
name: "Location Overlap Analysis"
description: "Geocodes two locations, buffers them, and highlights where the zones overlap."

inputs:
  loc_a:
    type: "string"
    description: "The first location"
    default: "Empire State Building, New York"
  loc_b:
    type: "string"
    description: "The second location"
    default: "Times Square, New York"
  radius:
    type: "number"
    description: "Buffer radius in meters"
    default: 800

actions:
  # 1. Geocode both locations
  - verb: gis.geocode_address
    params:
      address: "${inputs.loc_a}"
    returns: pt_a

  - verb: gis.geocode_address
    params:
      address: "${inputs.loc_b}"
    returns: pt_b

  # 2. Draw buffers around both points using the returned geometry
  - verb: gis.buffer_geometry
    params:
      geometry: "${pt_a.geometry}"
      distance: "${inputs.radius}"
      units: "meters"
    returns: buffer_a

  - verb: gis.buffer_geometry
    params:
      geometry: "${pt_b.geometry}"
      distance: "${inputs.radius}"
      units: "meters"
    returns: buffer_b

  # 3. Find and highlight the intersecting area between the two buffers
  - verb: gis.intersect_geometry
    params:
      geometry_a: "${buffer_a.geometry}"
      geometry_b: "${buffer_b.geometry}"
    returns: overlapping_zone

API Usage

parseOV(yamlString: string): OVScript

Parses a raw YAML string into a validated OVScript AST object. It will throw detailed errors if the YAML structure is malformed or if required fields are missing.

import { parseOV } from '@openverb/format';

const fileContent = await fs.readFile('script.ov', 'utf-8');
const script = parseOV(fileContent);

console.log(script.name); // "Location Overlap Analysis"
console.log(script.inputs); // { loc_a: { type: "string", ... }, ... }

bridgeToRuntime(script: OVScript, options: BridgeOptions): ExecuteRequest[]

Converts a parsed .ov script into an array of ExecuteRequest objects that can be directly fed into the @openverb/runtime engine.

import { parseOV, bridgeToRuntime } from '@openverb/format';
import { createRuntime } from '@openverb/runtime';

// 1. Parse the script
const script = parseOV(yamlContent);

// 2. Collect inputs from the user (e.g., via UI prompt or CLI)
const variables = {
  inputs: {
    loc_a: "Central Park",
    loc_b: "Times Square",
    radius: 500
  }
};

// 3. Bridge the script to runtime requests
const requests = bridgeToRuntime(script, {
  actor: { type: 'user', id: 'user-123' },
  context: { planId: 'pro' },
  variables
});

// 4. Pass the requests to the OpenVerb runtime (pseudo-code)
for (const req of requests) {
  await runtime.execute(req);
}

Variable Interpolation

The @openverb/format engine relies heavily on dynamic variable substitution to pipe data between steps.

Variables are denoted using the ${variable.path} syntax.

• ${inputs.*}: References values provided by the user prior to execution.
• ${step_returns.*}: References the output data of a previous action.

Note: As of version 2.0.0-beta.2, variable substitution between steps must currently be implemented in the execution loop by your application logic while we finalize the native executeScript method in @openverb/runtime.