Tune in to Trailblazers Innovate for Salesforce product news,
demos, and latest roadmaps. Register here.
close
Start tracking your progress
Trailhead Home
Trailhead Home

Define a Schema for an External Service

Learning Objectives

After completing this unit, you’ll be able to:

  • Describe the purpose of the schema definition.
  • Explain the elements of a supported External Services schema definition.
  • Name three issues that can cause your schema to fail.

Why Do You Need a Schema Definition?

Whether or not you’re the one who ends up creating a schema definition for your External Services registration, it’s helpful to understand its purpose and how it’s used. Already familiar with defining a schema from a REST-based API? Go ahead and skip to the next section And... What Makes a For a Supported Schema?

Remember our earlier examples —the REST-based API external web service from a payroll app and credit service? Although we have a REST-based bank API, we still need a common, standardized format to describe the structure of our bank’s REST-based API. Enter the API schema definition. Salesforce uses the commonly adopted OpenAPI specification for the description format. 

Your schema definition contains what types of inputs and outputs you can include in the calls, or requests, that your org makes to the external web service. For example, your calls might include ID as numerical input or name as text output.

It also contains the endpoint information and authentication parameters for the REST-based API web services that you can access. (Remember that the endpoint exposes the web services resources that External Services interacts with.) For example, this schema from a fictional bank includes methods for adding and deleting accounts. https://th-external-services.herokuapp.com/accounts/schema

Note

Note

In a real world application, following security best practices, you would include an authentication step before accessing a bank’s API!

Since our schema definition is human-readable, structured data, let’s look at it together.
Here are the basic account operations of our schema:

Operations for path: /accounts/{accountName}
Description
GET
Retrieves an account
POST
Adds an account
PUT
Updates an account
DELETE
Deletes an account

Here’s a code snippet from the schema definition that contains information about a GET method. If you don’t know, a GET method simply retrieves resource information from a web service. This particular GET method retrieves (“gets”) information about an account using the resource path, in this case /accounts/{accountName}, where {accountName} is a specified account. If you look under “parameters”, you can see "name":"accountName". This parameter must match the account name that you specify and is required ("required":true). It should also take the form of a string.


"paths": {
     "/accounts/{accountName}": {
       "get": {
         "operationId": "getAccount",
         "summary": "Retrieves an account",
         "description": "Retrieves the account with specific name",
         "consumes": ["text/plain"],
         "produces": ["application/json"],
         "parameters": [{
           "name": "accountName",
           "in": "path",
           "required": true,
           "type": "string",
           "description": "Name of the account"
        }],
         "responses": {
           "200": {
             "description": "The response when system finds an account with given name",
             "schema": {
               "$ref": "#/definitions/accountDetails"
            }
           },
           "400": {
             "description": "Error response if the account name parameter is
            less than minimum characters",
             "schema": {
               "$ref": "#/definitions/errorModel"
            }
           },
           "404": {
             "description": "Error response if the account is not supported by service or account is not found",
             "schema": {
               "$ref": "#/definitions/errorModel"
            }

Naturally, there’s a lot more to the schema. But you can see that while it’s designed for consumption by External Services, it’s also human-readable. It’s also formatted in a logical way that allows External Services to process the data so that it can surface them as invocable actions in flow.These flow actions are what we later use as inputs and outputs in a flow.

The next steps are to declaratively register your web service. But first, let’s cover the elements that make up a supported schema definition.

And...What Makes for a Valid and Supported Schema?

So now we know what a schema, or more precisely, a schema definition, is all about. But what do we mean by a valid and supported schema? 

There are general schema validation requirements that the OpenAPI specification defines and there are specific External Services schema requirements. External Services can properly support your schema and call your web service when both of these criteria are met.  

A Primer on Schema Validation

Although a schema is human-readable, it must also be machine-readable. It needs to follow a logical structure so that External Services can easily consume it. An incorrectly structured schema means that the external web service can’t communicate (returns error and exception messages) and, ultimately, External Services can’t ingest it. Meeting structural, logical and syntax restrictions is a necessary first-pass of schema validation. The OpenAPI specification defines these general rules and takes the guesswork out of calling an external web service.

Supported External Services Schema 

In addition to general OpenAPI guidelines for schema validation, there are also schema limitations that are specific to External Services. You’ll want to review these requirements before you register your schema with External Services. A supported schema in External Services means that your schema is valid according to the OpenAPI specification and it also adheres to the specific External Service requirements.


Here’s a list of some key requirements for creating an External Services supported schema. For a complete list, see Salesforce Help: Enhanced External Services Considerations

  • Schemas currently support up to 100,000 characters.
  • Supported methods are GET, PATCH, PUT, POST and DELETE
  • Properties include values.
  • Parameters have names.
  • Map and named list data types.
  • MIME type application/json supported.
  • Media types are not supported.
  • Use OpenAPI 2.0 valid JSON schema formats.
  • Try to avoid using string parameters that share the same name as reserved keywords in Apex. 

So let’s delve into the nitty gritty of what a supported schema looks like. This next step sets everything up. It’s a basic, yet critical piece to get right so that tools like Flow Builder can successfully call external web services.

Note

Tip

If you use the open-source framework OpenAPI, you can use the Swagger Editor tool to validate that your schema complies with the OpenAPI specification. If you want to take a short detour, go ahead and copy the schema from https://th-external-services.herokuapp.com/accounts/schema into the Swagger editor. You shouldn’t get any errors.

We covered some concepts about schemas and also some requirements. Want to dig in and get your hands dirty with External Services? Of course you do! We do just that in the next unit. Before moving on, though, let’s review the first two steps we discussed in the first unit.

  1. An external web services provider such, as a credit service, shares its REST-based API: We received this information from our fictional bank.
  2. Based on the specification, the web service provider (like in our bank service example), a developer (or maybe even you) creates a JSON-based schema definition that describes the API: While we didn’t create this schema ourselves, we reviewed the elements of a schema and the requirements to make sure it’s supported. When you work with external web services, you or your developer can define the schema that fits your use case.

Resources