Define a REST API schema

Specify the expected data structure for requests or responses within a REST API by defining a schema.

Before you begin

Role required: web_service_admin

About this task

Schemas are records that define the structure and format of request and response bodies and headers for a REST API in the OpenAPI 3.0.1 format. When you define a schema in the ServiceNow AI Platform, the schema is used to define the structure of requests and responses within the associated REST API. The schema data for the requests and responses is then available in the exportable OpenAPI specification for the API. For more information about exporting OpenAPI specifications, see Export to OpenAPI specification.

The following procedure describes the process for manual schema definition. For details about automatically generating request schema definitions in non-production instances, see Automatically generate API request definitions.

Procedure

1. Create a REST Schema in one of the following ways.

   Option	Procedure
   Navigate through a scripted REST API record	Navigate to All > System Web Services > Scripted REST Services > Scripted REST APIs. Select a scripted REST API record. In the Schemas related list, select New.
   Navigate directly to a new REST Schema record	Navigate to All > Filter and enter sys_ws_schema.form. In the API field, select or enter the API to associate with the schema.

2. In the Name field, enter a name for the schema.
3. In the Schema field, define the data type and structure of the new schema using the OpenAPI version 3.0.1 format.
   For example, the following entry specifies that the schema is an object that contains a first name. The first name is a string data type.

   { "type": "object", "properties": { "firstName": { "type": "string" } } }

4. Select an OpenAPI version.
5. In the Description field, summarize the expected structure of the new schema.
6. Select Submit.

What to do next

Define additional schemas as needed. Use the schemas to specify the expected structure and format in a REST request or response. For more information, see Define an API resource request structure or Define an API resource response structure.