Pulse
      Back to home
      1. Help Center
      2. Pulse

      Understanding and Writing Schemas

      To create an Action you have to add a schema to the action. In this article we will explain what a schema is and provide guidance on how to write a schema.

      What is a Schema?

      An OpenAPI schema, also known as an OpenAPI specifcation or Swagger file, is a structured way to describe the interface of an API, detailing its endpoints, operations, parameters, and responses. It serves as an instruction manual for interacting with the API, defining how to communicate with it and what to expect in response. 

      Writing a Schema

      Below is a basic example of an Schema in YAML format, compliant with OpenAPI version 3.0.0, including the key components you will often use:

      openapi: 3.0.0
      info:
        title: Example API
        description: This is an example of an OpenAPI specification.
        version: "1.0.0"
      servers:
        - url: https://exampleapi.com/
      paths:
        /items:
          get:
            summary: List of items
            description: Retrieves a list of items.
            responses:
              '200':
                description: A list of items.
                content:
                  application/json:
                    schema:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: "Item 1"
          post:
            summary: Create an item
            description: Creates a new item.
            requestBody:
              required: true
              content:
                application/json:
                  schema:
                    type: object
                    properties:
                      name:
                        type: string
                        example: "New Item"
            responses:
              '201':
                description: Successfully created a new item.
      components:
        schemas:
          Item:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string

      Key Components of an OpenAPI Schema

      1. openapi: Specifies the version of the OpenAPI specification being used. The schema must be at least OpenAPI version 3.0.0 compliant.
      2. info: Contains basic information about the API, such as title, description, and version.
      3. servers: Lists servers where the API is available, including base URLs.
      4. paths: Defines available endpoints and HTTP methods for communication with the API. Each path specifies operations and parameters.
      5. responses: Describes possible responses after making requests to an endpoint.
      6. components/schemas: Allows you to define models used throughout your API, aiding in reusability and organization.

      Validating the Schema

      Before using the schema for your AI Action, it's essential to validate it to ensure it meets the necessary standards and is free from errors. Click 'Validate' to see if your schema is validated. If it is not, you will see the errors below and you can correct them. 

      Once the schema passes validation, the available actions will show underneath. These actions represent the functionalities defined in your schema and are ready to be used in your chatbot. Testing these actions ensures that your chatbot can accurately respond to user inquiries and perform the desired tasks.