--- schema_version: "1" id: 49bb881d7f93c07cef4bba78f28b0401fc37166dfdf4d3595ec5e142dd18b02f title: External Services OpenAPI 2.0 Schema collection: admin version: current locale: en-us portal_url: https://docs.salesforce.com/admin/current/en-us/platform/264-0-0/external_services_schema_examples.md canonical_url: https://help.salesforce.com/s/articleView?id=platform.external_services_schema_examples.htm&release=264.0.0&type=5 source_site: help.salesforce.com content_type: documentation content_hash: 2777740e83fb2c6f39e7c0048331fa68f9c697711d68f3c628582c34e81a0e16 description: This section features External Services OpenAPI 2.0 schema examples. products: - Salesforce Platform - Security release: "264" --- # External Services OpenAPI 2.0 Schema This section features External Services OpenAPI 2.0 schema examples. ### Required Editions
Available in: Lightning Experience
Available in: Enterprise, Performance, Unlimited, and Developer Editions
## Example 1: Basic OpenAPI Spec with Request and Response (OAS 2.0) Here’s an example of an API spec that contains a supported JSON schema for OpenAPI 2.0. The parameters (in bold) contain the definition for the `accountId` input. The responses (also in bold) contain the definition for the output, which is `creditRating`. Parameters and responses translate to inputs and outputs, respectively, for your flow actions. `{ "swagger":"2.0", "info":{ "description":"A service for checking credit for an account.", "version":"1.0.0", "title":"Credit Decision", "termsOfService":"http://swagger.io/terms/", "contact":{ "email":"apiteam@swagger.io" }, "license":{ "name":"Apache 2.0", "url":"http://www.apache.org/licenses/LICENSE-2.0.html" } }, "host":"", "paths":{ "/account/lastCreditRating":{ "get":{ "summary":"Evaluates credit rating and decides what payment terms to offer.", "description":"", "consumes":[ "application/json", "application/xml" ], "produces":[ "application/xml", "application/json" ], **"parameters":[{ "in":"body", "name":"body", "description":"Specifies input parameters to calculate payment term", "required":true, "schema":{ "$ref":"#/definitions/accountId" } }], "responses":{ "200":{ "description":"success", "schema":{ "$ref":"#/definitions/creditRating" } }, "405":{ "description":"Invalid input"** } } } } }, "definitions":{ "accountId":{ "type":"object", "properties":{ "accountIdString":{ "type":"string" } }, "xml":{ "name":"accountId" } }, "creditRating":{ "type":"object", "properties":{ "creditRatingString":{ "type":"string" } }, "xml":{ "name":"creditRating" } } } }` ## Example 2: Named Object Schema Reference (OAS 2.0) Basic Setup - For the named credential that your org uses to access the banking system, assign the Bank label and a placeholder URL, such as https://api.example.com. Use example.com because you’ll _paste in_ the schema at registration time, instead of using a URL to point to an API spec. - Register the employee banking system’s external service. Use the Bank name and the Bank named credential, and then copy and paste in the following schema. - The banking system's external service shows two ways to define parameters with object types: a named object type under a “definitions” block or an anonymously declared object type inline. ![Note](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-platform-extend_click-264-0-0-production-enus/5f7d9219-b7b1-4552-8891-f1aba9b289fc/images/icon_note.png) Note The defined or derived parameter object type name, or a property with an object type, must be fewer than 255 characters to be used in Apex or Flow Builder. Here’s a JSON-formatted schema with the named object type defined under the “definitions” block. The phone object type's name is ExternalService\_\_Bank\_Phone in Apex or Flow Builder. `{ "swagger": "2.0", "info": { "title": "bankService", "description": "API description in Markdown.", "version": "1.0.0" }, "host": **"api.example.com"**, "basePath": "/v1", "schemes": [ **"https"** ], **"definitions": {** "User": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "phones":{ "type":"array", "items":{ "type": "object", "$ref": "#/definitions/Phone" } } } }, **"Phone"**:{ "properties":{ "typeofphone":{ "type":"string" }, "phone":{ "type":"string" } } } }, "paths": { "/users/{userId}": { "get": { "summary": "Returns a user by ID.", "parameters": [{ "in": "path", "name": "userId", "required": true, "type": "integer" }], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/User" } } } } }, "/users": { "post": { "summary": "Creates a new user.", "parameters": [{ "in": "body", "name": "user", "schema": { "$ref": "#/definitions/User" } }], "responses": { "200": { "description": "OK" } } } } } }` Here's the same schema, but formatted with YAML. ``` swagger: '2.0' info: title: bankService description: API description in Markdown. version: 1.0.0 host: api.example.com basePath: /v1 schemes: - https definitions: User: properties: id: type: integer name: type: string phones: type: array items: type: object $ref: '#/definitions/Phone' Phone: properties: typeofphone: type: string phone: type: string paths: /users/{userId}: get: summary: Returns a user by ID. parameters: - in: path name: userId required: true type: integer responses: '200': description: OK schema: $ref: '#/definitions/User' /users: post: summary: Creates a new user. parameters: - in: body name: user schema: $ref: '#/definitions/User' responses: '200': description: OK ``` ## Example 3: Nested Anonymous Object Schema (OAS 2.0) Here’s an API spec with a JSON schema with anonymous object types defined inline. The derived phone object type's name is ExternalService\_\_Bank\_getUsers\_OUT\_200\_phones. ![Note](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-platform-extend_click-264-0-0-production-enus/5f7d9219-b7b1-4552-8891-f1aba9b289fc/images/icon_note.png) Note For anonymous object types, Salesforce automatically derives object type names based on the external service, parent operation, operation parameter, parent object, and object property names. The derived name must be fewer than 255 characters. For more information, see "External Service Apex Class Names and Developer Names" in [External Services Considerations](https://help.salesforce.com/s/articleView?id=platform.enhanced_external_services_considerations.htm&release=264.0.0&type=5 "Here are the semantic, service, and usage constraints to keep in mind when integrating your services into External Services."). `{ "swagger": "2.0", "info": { "title": "bankService", "description": "API description in Markdown.", "version": "1.0.0" }, "host": **"api.example.com"**, "basePath": "/v1", "schemes": [ **"https"** ], "paths": { **"/users/{userId}": { ** **"get": {** "summary": "Returns a user by ID.", "parameters": [{ "in": "path", "name": "userId", "required": true, "type": "integer" }], "responses": { **"200": {** "description": "OK", **"schema":** { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "phones": { "type":"array", "items": { "type": "object", "properties": { "typeofphone": { "type":"string" }, "phone": { "type":"string" } } } } } } } } } }, "/users": { "post": { "summary": "Creates a new user.", "parameters": [{ "in": "body", "name": "user", "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "phones": { "type":"array", "items": { "type": "object", "properties": { "typeofphone": { "type":"string" }, "phone": { "type":"string" } } } } } } }], "responses": { "200": { "description": "OK" } } } } } }` ## Example 4: Apex Object Class Naming (OAS 2.0) Here's an API spec registered with the external service name BankingAutomaticTellerMachine. However, the derived object names must be no longer than 255 characters: - ExternalService\_\_BankingAutomaticTellerMachine\_VeryImportantCustomer\_phone - ExternalService\_\_BankingAutomaticTellerMachine\_getBalanceAccountTypeChecking\_OUT\_200 To use Apex or Flow Builder, you must shorten the external service schema name and the schema (shown in Example 5). ![Tip](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-platform-extend_click-264-0-0-production-enus/5f7d9219-b7b1-4552-8891-f1aba9b289fc/images/icon_tip.png) Tip If the derived object name is longer than 255 characters, try one of the following methods to resolve the issue. - Shorten the external service name. - If the object is declared inline under an operation parameter, shorten the operation name by adding an operationId to the schema. - If the object is declared inline under a parent object property, shorten the parent object name in the schema. - Declare the nested object as a top-level object under schema “definitions”. `{ "swagger": "2.0", ... "paths": { "/balance/account/{accountId}/type/checking": { "get": { "parameters": [{ "in": "path", "name": "accountId", "required": true, "type": "integer" }], "responses": { "200": { "schema": { "type": "object", "properties": { "balance": { "type": "integer" }, "owner": { "$ref": "#/definitions/VeryImportantCustomer" } } } } } } } }, "definitions": { "VeryImportantCustomer": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "object", "properties": { "number": { "type": "string" } } } } } } }` ## Example 5: Shortening Apex Object Class Names (OAS 2.0) Here's an example of an API spec with a schema that results in shortened names. It's registered with the shortened name BankAtm. Shorten the external service schema name to BankAtm, the schema object name to VIP and add operationId as getBalance: - ExternalService\_\_BankAtm\_VIP\_phone - ExternalService\_\_BankAtm\_getBalance\_200 `{ "swagger": "2.0", ... "paths": { "/balance/account/{accountId}/type/checking": { "get": { **"operationId": "getBalance",** "parameters": [{ "in": "path", "name": "accountId", "required": true, "type": "integer" }], "responses": { "200": { "schema": { "type": "object", "properties": { "balance": { "type": "integer" }, "owner": { "$ref": "#/definitions/**VIP" ** } } } } } } } }, "definitions": { **"VIP":** { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "object", "properties": { "number": { "type": "string" } } } } } } }` ## Example 6: Inline Arrays (OAS 2.0) Here's an example with an inline array definition. `{ "swagger": "2.0", "host": "Employees.org", "basePath": "/", ... "paths": { "/employees/{employeeId}": { "get": { "operationId": "getEmployee", "parameters": [{ "in": "path", "name": "employeeId", "required": true, "type": "string" }], "responses": { "200": { "schema": { "type": "object", "properties": { "employee": {"$ref": "#/definitions/Employee"}, "manager": {"$ref": "#/definitions/Employee"}, "team": { **"type": "array", "items": {"$ref": "#/definitions/Employee"}** } } } } } } } }, "definitions": { "Employee" : { "type": "object", "properties": { "employeeId": {"type": "string"}, "firstName": {"type": "string"}, "middleName": {"type": "string"}, "lastName": {"type": "string"}, "dateOfHire": {"type": "date"} } } } } }` ## Example 7: HTTP Header Parameters (OAS 2.0) Here’s how a header parameter is declared in an OpenAPI schema. In Apex or Flow, the name “`apiKey`” shows up as a string parameter. Now when you set any string value in Apex or a flow to `apiKey`, it functions as an HTTP parameter when making a callout request. `{ "swagger": "2.0", "info": { "description": "A service for checking credit for an account.", "version": "1.0.0", "title": "Credit Decision", "termsOfService": "http://swagger.io/terms/", "contact": { "email": "apiteam@swagger.io" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, "host": "", "paths": { "/account/lastCreditRating": { "get": { "summary": "Evaluates credit rating and decides what payment terms to offer.", "description": "", "consumes": [ "application/json", "application/xml" ], "produces": [ "application/xml", "application/json" ], "parameters": [{ "name": "body", "description": "Specifies input parameters to calculate payment term", "in": "body", "required": true, "schema": { "$ref": "#/definitions/accountId" } },{ **"name": "apiKey"**, **"description": "Your API Key for calling the credit rating service"**, **"in": "header"**, **"type": "string"** }], "responses": { "200": { "description": "success", "schema": { "$ref": "#/definitions/creditRating" } }, "405": { "description": "Invalid input" } } } } }, "definitions": { "accountId": { "type": "object", "properties": { "accountIdString": { "type": "string" } }, "xml": { "name": "accountId" } }, "creditRating": { "type": "object", "properties": { "creditRatingString": { "type": "string" } }, "xml": { "name": "creditRating" } } } }` ## Example 8: URL Encoded Form Media Type (OAS 2.0) Request and response form data is declared alongside the matching `consumes` and `produces` directives. ```java { "swagger": "2.0", "info": { "description": "Apply here for your next mortgage", "version": "1.0.0", "title": "My Mortgage Buddy", "contact": { "email": "apiteam@swagger.io" } }, "host": "MyMortgageBuddy.org", "basePath": "/mortgages", "paths": { "/apply": { "post": { "operationId": "applyMortgage", "consumes": [ "application/x-www-form-urlencoded; charset=utf-8" ], "produces": [ "application/x-www-form-urlencoded; charset=utf-8" ], "parameters": [{ "description": "Desired mortgage terms", "name": "terms", "in": "formData", "type": "array", "items": { "type": "integer" }, "collectionFormat": "multi", "required": true },{ "description": "Full Name", "name": "fullName", "in": "formData", "type": "string", "required": true },{ "description": "Loan amount", "name": "loanAmount", "in": "formData", "type": "number", "required": true }], "responses": { "200": { "description": "200", "schema": { "type": "object", "properties": { "formApplicationId": { "type": "string" }, "loanOfficerFullName": { "type": "string" } } } } } } } } } ``` ## Example 9: allOf and additionalProperties Schema Directives (OAS 2.0) This JSON schema definition highlights the constructs `allOf` for schema object composition and `additionalProperties` for dictionary values. The sample schema is registered as an external service `MyBank` with named credential `MyBank`. The registration is invoked by a sample flow that accesses the dictionary properties with an Apex invocable action. A flow Apex unit test ties it all together. The schema defines a banking service that gets customer details for a customer ID. - The `Customer` schema object has dictionary properties of type schema object `CreditRating`. In Apex, the class `ExternalService.MyBank_Customer` has property `properties` of type `Map` with the customer’s credit ratings. - Phones and Emails compose their own properties together with the common `allOf` properties from the schema object `Contact.` ``` { "swagger": "2.0", "info": { "title": "myBank", "description": "Sample Banking Service with allOf and additionalProperties schema constructs", "version": "1.0.0" }, "host": "api.mybank.com", "basePath": "/v1", "schemes": [ "https" ], "definitions": { "Customer": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "phones": { "type":"array", "items": { "$ref": "#/definitions/Phone" } }, "emails": { "type": "array", "items": { "$ref": "#/definitions/Email" } } }, "additionalProperties": { "$ref": "#/definitions/CreditRating" }, "required": [ "id", "name" ] }, "Contact": { "type": "object", "properties": { "primary": { "type": "boolean" }, "timeOfDay": { "type": "string" } }, "required": [ "primary" ] }, "Phone": { "allOf": [ { "$ref": "#/definitions/Contact" }, { "type": "object", "properties": { "typeOfPhone": { "type":"string" }, "phoneNumber":{ "type":"string" } } } ] }, "Email": { "allOf": [ { "$ref": "#/definitions/Contact" }, { "type": "object", "properties": { "email": { "type":"string" } } } ] }, "CreditRating": { "type": "object", "properties": { "rating": { "type": "string" }, "score": { "type": "number", "format": "double" } } } }, "paths": { "/customers/{customerId}": { "get": { "summary": "Get the customer by ID.", "parameters": [{ "in": "path", "name": "customerId", "required": true, "type": "integer" }], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/Customer" } } } } } } } ``` To use `allOf` composition and `additionalProperties`, see [For Examples 9: allOf Composition and additionalProperties Use in Flow with Apex Unit Tests](https://help.salesforce.com/s/articleView?id=platform.external_services_examples_using.htm&release=264.0.0&type=5). ## Example 10: allOf and Discriminator Directives (OAS 2.0) To specify a general extensible list of contacts for a customer, the `discriminator` directive can be combined with `allOf` to declare whether a contact is an email or a phone number: ``` { "swagger": "2.0", "info": { "title": "myBank", "description": "Sample Banking Service with allOf and discriminator", "version": "1.0.0" }, "host": "api.mybank.com", "basePath": "/v1", "schemes": [ "https" ], "definitions": { "Customer": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "contacts": { "type":"array", "items": { "$ref": "#/definitions/Contact" } } }, "required": [ "id", "name" ] }, "Contact": { "type": "object", "discriminator": "contactType", "properties": { "contactType": { "type": "string" }, "primary": { "type": "boolean" }, "timeOfDay": { "type": "string" } }, "required": [ "contactType", "primary" ] }, "Phone": { "allOf": [ { "$ref": "#/definitions/Contact" }, { "type": "object", "properties": { "typeOfPhone": { "type":"string" }, "phoneNumber":{ "type":"string" } } } ] }, "Email": { "allOf": [ { "$ref": "#/definitions/Contact" }, { "type": "object", "properties": { "email": { "type":"string" } } } ] } }, "paths": { "/customers/{customerId}": { "get": { "summary": "Get the customer by ID.", "parameters": [{ "in": "path", "name": "customerId", "required": true, "type": "integer" }], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/Customer" } } } } } } } ``` To use composition and polymorphic OpenAPI schema constructs, see [For Examples 10: Polymorphism with allOf and Discriminator](https://help.salesforce.com/s/articleView?id=platform.external_services_examples_using.htm&release=264.0.0&type=5). ## Array Definition (OAS 2.0) External Services supports inline array definitions and referenceable named arrays. List types in External Services are identified by their object element type. Supported Inline Array Definition with Reference to Array Items Definition ```java { "swagger": "2.0", ... "name": "myObjects", "in": "body", "schema": { "type": "array", "items": { "$ref": "#definitions/MyObject" } } ... "definitions": { "MyObject": { "type": "object", "properties": {...} } } } ``` In Apex and Flow Builder, declare a variable for the `myObjects` parameter by marking the variable as a collection and picking its Apex element type `ExternalService__RegistrationName_MyObject`. Inline Array Definition with Inline Array Items Definition ```java { "swagger": "2.0", ... "name": "myObjects", "in": "body", "schema": { "type": "array", "items": { "type": "object", "properties": {...} } } ... "definitions": { ... } } ``` In Apex and Flow Builder, declare a collection variable for the `myObjects` parameter and Apex element type `ExternalService__RegistrationName_OperationName_IN_myObjects`. Referenceable Array Definition with Reference to Array Item Definitions ```java { "swagger": "2.0", ... "name": "myObjects", "in": "body", "schema": { "$ref": "#definitions/MyObjectList" } ... "definitions": { "MyObjectList": { "type": "array", "items": { "$ref": "#definitions/MyObject" } } "MyObject": { "type": "object", "properties": {...} } } } ``` In Apex and Flow Builder, declare a collection variable for the `myObjects` parameter and Apex element type `ExternalService__RegistrationName_MyObject`. Referenceable Array Definition with Inline Array Items Definition ```java { "swagger": "2.0", ... "name": "myObjects", "in": "body", "schema": { "$ref": "#definitions/MyObjectList" } ... "definitions": { "MyObjectList": { "type": "array", "items": { "type": "object", "properties": {...} } } } } ``` In Apex and Flow Builder, declare a collection variable for the `myObjects` parameter and Apex element type `ExternalService__RegistrationName_MyObjectList`. #### See Also - [External Services OpenAPI 3.0 Schema](https://help.salesforce.com/s/articleView?id=platform.external_services_examples_openapi_3_0.htm&release=264.0.0&type=5 "This section features External Services OpenAPI 3.0 schema examples.") - [Using the Schema Examples](https://help.salesforce.com/s/articleView?id=platform.external_services_examples_using.htm&release=264.0.0&type=5 "See how the respective Open API 2.0 and 3.0 examples are implemented with Apex.") - [External Services Considerations](https://help.salesforce.com/s/articleView?id=platform.enhanced_external_services_considerations.htm&release=264.0.0&type=5 "Here are the semantic, service, and usage constraints to keep in mind when integrating your services into External Services.")