ai-actions-schemas

AI Actions Schemas (actions.json)

Structure

Each action in actions.json has:

• display_name — Human-readable name
• description — What the action does
• parameters — JSON Schema for input (request)
• response — JSON Schema for output

Parameters Schema

Preferred: Flat Structure

• Types: string, number, integer, boolean
• All properties need description
• Use required array for mandatory fields
• Use $schema: "http://json-schema.org/draft-07/schema#"
• Draft-07 keywords on string (and similar) properties are allowed where the automation UI supports them—common ones: enum (fixed allowed values), pattern (regex), format (semantic hint, e.g. email, date-time)

String constraints (enum, pattern, format)

{
  "parameters": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "priority": {
        "type": "string",
        "enum": ["low", "medium", "high", "urgent"],
        "description": "Ticket priority"
      },
      "order_id": {
        "type": "string",
        "pattern": "^[A-Z]{2}-[0-9]{6}$",
        "description": "Vendor order id, e.g. OR-000123"
      },
      "notify_email": {
        "type": "string",
        "format": "email",
        "description": "Email to notify when the action completes"
      }
    },
    "required": ["priority", "order_id"]
  }
}

Arrays of Primitives Allowed

{
  "parameters": {
    "properties": {
      "ids": {
        "type": "array",
        "items": { "type": "string" },
        "description": "List of resource IDs"
      },
      "tags": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Tags to apply"
      }
    }
  }
}

Nested Objects: Flatten or Construct in server.js

If API requires nested object, accept flat params and build in server.js:

{ "name": { "type": "string" }, "email": { "type": "string" } }

// server.js builds: { contact: { name, email } }