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 :
Section Purpose openapi Defines the OpenAPI version info Describes your Action servers Lists API base URLs paths Lists available endpoints and their parameters components Defines 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: 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: parameters: - in: query name: status required: false schema: type: string description: Filter orders by status. 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 Code Meaning Required? 200 Successful response 400 Bad request (missing or invalid parameter) Recommended 404 Not found Recommended 500 Server error Recommended
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:
Mistake Description Example Wrong indentation YAML is sensitive to spaces — use 2 spaces, no tabs Type mismatch Wrong data type for a field type: string for a number Missing quotes Special characters need quotes ’3.0.0’ not 3.0.0 Missing required fields Missing openapi, info, or paths Inconsistent naming Different field names in paths and components Enums or examples not matching actual data Example 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
In your Action setup, click Validate Schema .
Watermelon checks:
Syntax validity
Required fields
Correct parameter structure
Supported OpenAPI version (3.0+)
What happens Next
Valid Schema: You’ll see the available actions listed automatically. They’re now ready to use.
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
Check Description ✔ OpenAPI version Use at least 3.0.0 ✔ Info section Includes title, version, description ✔ Servers URL(s) defined correctly ✔ Paths Each path has summary, parameters, responses ✔ Components All references resolved with examples ✔ Indentation Two spaces per level, no tabs ✔ Validation passed Schema tested in Watermelon ✔ Responses realistic 200, 400, 404, 500 all defined
