Creating OpenAPI Schemas for custom GPTs

Note

This article is a supplement to the tutorials to create GPTs with actions. Visit it here: Creating GPT Actions

For the purpose of GPT Actions, OpenAPI schemas help define the functionality of each action. These schemas are very flexible and can help make API calls through GPT Actions consistent.

Regardless of how much or little experience or familiarity you have with these schemas, the structure is very similar across services. For the end of facilitating the schema creation/formatting process, OpenAI published a GPT to help. You can interact with it here: Actions GPT.

As you work with the Actions GPT and have a spec to work with, you will want to be familiar with the structure of these schemas to make further modifications.

How to use Actions GPT

When you think of the service that you want to connect to your GPT, keep in mind that all you are doing is creating functions that connect to the service API. So, to get started, find the API documentation for the service you want to connect to your GPT.

Once you have found the API documentation for the service you want to integrate (it will be even better if you find the exact endpoints), you can create OpenAPI schemas with Actions GPT with a prompt as simple as "Create a spec for this API: <<URL>>".For API endpoints that are highly customizable with many parameters, you can simplify the spec by including the specific functionality that you are expecting from the GPT calling an endpoint.

The Actions GPT will create a spec that can be used for the custom GPT action. Once generated, it can be modified as desired. Below is a sample schema that we will use for demonstration purposes. Scroll to the bottom of the code block for annotations.

openapi: 3.1.0
info:
  title: Book Info API
  description: API for retrieving information about books by ID, with support for language and edition filters.
  version: 1.0.0

servers:
  - url: https://api.bookinfo.com/v1
    description: Main production server

paths:
  /books/{bookId}:
    get:
      operationId: getBookById
      summary: Retrieve information about a specific book.
      description: Returns details about a book based on its ID. Supports language and edition filters.
      parameters:
        - name: bookId
          in: path
          required: true
          description: The unique identifier for the book.
          schema:
            type: string
        - name: lang
          in: query
          required: true
          description: The language in which to return the book information.
          schema:
            type: string
            enum: [en, es, fr, de]
        - name: edition
          in: query
          required: false
          description: Specific edition to retrieve.
          schema:
            type: string
      responses:
        '200':
          description: Book found and returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The book's unique identifier.
                  title:
                    type: string
                  author:
                    type: string
                  language:
                    type: string
                  edition:
                    type: string
        '404':
          description: Book not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Book not found

servers >> url: base url for api service
paths >> path: API endpoint that the GPT action will call. To get the full url for the api call, combine the url in server with the path in paths. In this example, the full url for this path is https://api.bookinfo.com/v1/books/{bookId}
paths >> path >> get: type of request for the API call. If a specific path (annotation 2) can be called with both GET and POST methods, the structure of each request will be created under the corresponding request type.
get >> operationId: Name for action. Each API endpoint will have a different name, which the GPT will use to identify it
parameters: list of parameters that the GPT will populate based on the user prompt.
Each parameter can be described with the following attributes:
- in (path or query): if path, the parameter MUST be present in the path (annotation 2). if query, the parameter will not be present in the path.
- required (true or false): indicates the GPT if the parameter should always be populated for each call or not.
- description: a description of the parameter (optional).
- schema > type (string or integer or number): helps the GPT know what kind of parameter it is.
responses: the response codes and description for each one

Helpful tips

There are things you can do to help offload some of the "guesswork" from the user prompts the GPT will have to analyze. This will ensure that API calls are consistent and don't break.

Don't make the model fill arguments you already know: Depending on the paths that your GPT uses, there might be a case where you want it to always call a specific resource defined by a specific parameter. In the books example above, say that you want your GPT to always get information about a specific book. If the bookId for this book was 12345, then you could:
- Replace the parameter from the schema and hardcode the bookId.
- Add a default attribute in the parameters section of the schema and hardcode the bookId there.
Add formatting instructions to parameters: If you want the parameter to be populated in a specific format, include format below type in the parameter schema. Examples of values for the format attribute are date and float.
Enumerate available parameter values: If the parameter will always accept only from a defined set of options, set the appropriate type and add an enum attribute below, providing the available options in square brackets (see example above).

POST requests

POST requests need a requestBody. ActionsGPT can also help create the requestBody structure. Below is an example of a spec with a requestBody for a GPT Action that updates a Sharepoint List by adding rows to it based on the user prompt. Keep in mind that for this particular resource, the properties in the body needed to be contained within a fields object, which is why the fields property is provided and all the other properties are contained within.

openapi: 3.1.0
info:
  title: Microsoft Graph List Items API
  description: API for retrieving and adding list items in a SharePoint list via Microsoft Graph.
  version: '1.0'
servers:
  - url: https://graph.microsoft.com/v1.0
    description: Microsoft Graph API production endpoint
paths:
  /sites/{site-id}/lists/{list-id}/items:
    post:
      operationId: createListItem
      summary: Add an item to a SharePoint list
      description: Creates a new item in the specified SharePoint list within a site.
      parameters:
        - name: site-id
          in: path
          required: true
          description: The unique identifier or URL-encoded site name for the SharePoint site.
          schema:
            type: string
        - name: list-id
          in: path
          required: true
          description: The unique identifier or name of the SharePoint list.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fields:
                  type: object
                  description: Key-value pairs of the fields to be set in the list item.
                  properties:
                    Title:
                      type: string
                      description: Name for list item.
                    url:
                      type: string
                      description: domain url for list item.
                    requested_by:
                      type: string
                      description: person requesting the new domain to be added.
                    description:
                      type: string
                      description: description or short reason for this request.
      responses:
        '201':
          description: Item created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The unique identifier of the created list item.
                  fields:
                    type: object
                    description: The fields of the created list item.
        '400':
          description: Bad request, possibly due to incorrect body data.
        '401':
          description: Unauthorized, authentication required.
        '403':
          description: Forbidden, insufficient permissions.
        '404':
          description: Site or list not found.

requestBody: where the definition of the body begins
properties: lists the properties, type, and description that will be included in the body

Use the help of the Actions GPT to help build these schemas.

As you build your OpenAPI schema, if there are errors, the GPT builder will indicate what they are when you paste the schema in the configuration for your GPT Action. Locate the errors and fix them with your newfound knowledge of OpenAPI schemas, or use Actions GPT as your debugging companion.

Tip

For support creating your OpenAPI schema and a custom GPT with actions, reach out to ai-committee@byu.edu.