Skip to main content
A schema is essentially a blueprint: if it’s clear and valid, your Action will run smoothly; if not, you’ll run into validation or response errors. This guide explains how to write a strong, valid schema that works seamlessly in Watermelon.

​
What Is a Schema?

A schema describes:
  • What your Action does (e.g., get an order, create a ticket)
  • What parameters it needs (e.g., order number, email)
  • What responses it expects (e.g., success, not found, server error)
Schemas in Watermelon use the OpenAPI 3.0 standard, which defines RESTful APIs in a structured way.

​
The Required Minimum Structure

Your schema must contain five core sections:
SectionPurpose
openapiDefines the OpenAPI version
infoDescribes your Action
serversLists API base URLs
pathsLists available endpoints and their parameters
componentsDefines reusable objects and response examples
Here’s the simplest valid example: 
openapi: "3.0.0"
info:
  title: "AI Agent Integration"
  version: "1.0.0"
  description: "Integration between Example API and AI Agent"
servers:
  - url: "https://api.example.com/v1"
    description: "Production Environment"
paths:
  /orders:
    get:
      summary: Retrieve order details
      parameters:
        - in: query
          name: order_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: integer
          example: 101
Use an editor that handles .yml files like Visual Studio Code. This will help you with the indentations

​
Choosing Parameter Locations

Parameters tell your API what data you’re sending. They can live in paths, queries, or headers.

​
Path Parameters

Used for identifying specific resources directly in the URL. Example: 
/orders/{order_id}

parameters:
  - in: path
    name: order_id
    required: true
    schema:
      type: string
    description: The order ID to retrieve.

​
Query Parameters

Used for filtering or adding optional details. Example: 
/orders?status=shipped

parameters:
  - in: query
    name: status
    required: false
    schema:
      type: string
    description: Filter orders by status.

​
Header Parameters

Used for authentication or metadata. Example: 
Authorization: Bearer <token>
Authentication headers don’t go inside your schema in Watermelon — they’re added separately under Authentication Settings when creating the Action.

​
Defining Responses

Your schema must include response definitions for key status codes. Each tells the AI Agent what kind of reply to expect from the API.
Status CodeMeaningRequired?
200Successful response
400Bad request (missing or invalid parameter)Recommended
404Not foundRecommended
500Server errorRecommended
Example: 
responses:
  '200':
    description: Successful response with order details
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Order'
  '400':
    description: Invalid request
  '404':
    description: Order not found
  '500':
    description: Server error

​
Common YAML Mistakes

Small syntax errors can make your schema invalid. Here’s what to watch for:
MistakeDescriptionExample
Wrong indentationYAML is sensitive to spaces — use 2 spaces, no tabs info:<br> title: test
Type mismatchWrong data type for a fieldtype: string for a number
Missing quotesSpecial characters need quotes’3.0.0’ not 3.0.0
Missing required fieldsMissing openapi, info, or paths
Inconsistent namingDifferent field names in paths and components
Enums or examples not matching actual dataExample data should reflect real structure
Test your schema in Swagger Editor before uploading — it catches indentation and type errors instantly.

​
Validation Flow in Watermelon

​
How to Validate

  1. In your Action setup, click Validate Schema.
  2. Watermelon checks:
    • Syntax validity
    • Required fields
    • Correct parameter structure
    • Supported OpenAPI version (3.0+)
Writing Validating Schema

​
What happens Next

  1. Valid Schema: You’ll see the available actions listed automatically. They’re now ready to use.
  2. Invalid Schema: You’ll get an error message with:
    • The line number
    • The column number
    • The error type (e.g., missing field, bad indentation)
Copy the YAML into Swagger Editor, fix the error, and paste it back into Watermelon.

​
Quick Checklist Before You Publish

CheckDescription
✔ OpenAPI versionUse at least 3.0.0
✔ Info sectionIncludes title, version, description
✔ ServersURL(s) defined correctly
✔ PathsEach path has summary, parameters, responses
✔ ComponentsAll references resolved with examples
✔ IndentationTwo spaces per level, no tabs
✔ Validation passedSchema tested in Watermelon
✔ Responses realistic200, 400, 404, 500 all defined