Create a custom connector with an OpenAPI extension
Article
One way to create custom connectors for Azure Logic Apps, Microsoft Power Automate, or Microsoft Power Apps is to provide an OpenAPI definition file, which is a language-agnostic, machine-readable document that describes your API's operations and parameters. Along with OpenAPI's out-of-the-box functionality, you can also include the following OpenAPI extensions when you create custom connectors for Logic Apps and Power Automate:
Applies to: Operations
Recommended: Use sentence case for summary.
Example: "When an event is added to calendar" or "Send an email"
JSON
"actions" {
"Send_an_email": {
/// Other action properties here...
"summary": "Send an email",
/// Other action properties here...
}
},
x-ms-summary
Specifies the title for an entity.
Applies to: Parameters, response schema
Recommended: Use title case for x-ms-summary.
Example: "Calendar ID", "Subject", "Event Description"
JSON
"actions" {
"Send_an_email": {
/// Other action properties here...
"parameters": [{
/// Other parameters here...
"x-ms-summary": "Subject",
/// Other parameters here...
}]
}
},
description
Specifies a verbose explanation about the operation's functionality or an entity's format and function.
Applies to: Operations, parameters, response schema
Recommended: Use sentence case for description.
Example: "This operation is triggered when a new event is added to the calendar", "Specify the subject of the mail"
JSON
"actions" {
"Send_an_email": {
"description": "Specify the subject of the mail",
/// Other action properties here...
}
},
x-ms-visibility
Specifies the user-facing visibility for an entity.
Possible values: important, advanced, and internal
Applies to: Operations, parameters, schemas
important operations and parameters are always shown to the user first.
advanced operations and parameters are hidden under an additional menu.
internal operations and parameters are hidden from the user.
Note
For parameters that are internal and required, you must provide default values.
Example: The See more and Show advanced options menus are hiding advanced operations and parameters.
JSON
"actions" {
"Send_an_email": {
/// Other action properties here...
"parameters": [{
"name": "Subject",
"type": "string",
"description": "Specify the subject of the mail",
"x-ms-summary": "Subject",
"x-ms-visibility": "important",
/// Other parameter properties here...
}]
/// Other action properties here...
}
},
x-ms-api-annotation
Used for versioning and life cycle management of an operation.
Applies to: Operations
family—A string denoting the operation family folder.
revision—An integer denoting the revision number.
replacement—An object containing the replacement API information and operations.
When used on the operation level, this is used to identify that the operation supports chunking upload and/or static chunk size, and can be provided by the user.
Applies to: Operations
chunkTransfer—A Boolean value to indicate whether chunk transfer is supported.
JSON
"x-ms-capabilities": {
"chunkTransfer": true
}
x-ms-trigger
Identifies whether the current operation is a trigger that produces a single event. The absence of this field means this is an action operation.
Applies to: Operations
single—Object response
batch—Array response
JSON
"x-ms-trigger": "batch"
x-ms-trigger-hint
A description of how to fire an event for a trigger operation.
Applies to: Operations
JSON
"x-ms-trigger-hint": "To see it work, add a task in Outlook."
x-ms-notification-content
Contains a schema definition of a webhook notification request. This is the schema for a webhook payload posted by external services to the notification URL.
Identifies in a Boolean value whether a webhook notification URL should be placed in this parameter/field for a webhook registration operation.
Applies to: Parameters/input fields
JSON
"x-ms-notification-url": true
x-ms-url-encoding
Identifies whether the current path parameter should be double URL-encoded double or single URL-encoded single. The absence of this field indicates single encoding.
Applies to: Path parameters
JSON
"x-ms-url-encoding": "double"
Use dynamic values
Dynamic values are a list of options for the user to select input parameters for an operation.
Applies to: Parameters
How to use dynamic values
Note
A path string is a JSON pointer that doesn't contain the leading forward slash. So, this is a JSON pointer: /property/childProperty, and this is a path string: property/childProperty.
There are two ways to define dynamic values:
Use x-ms-dynamic-values
Name
Required
Description
operationId
Yes
The operation that returns the values.
parameters
Yes
An object that provides the input parameters that are required to invoke a dynamic-values operation.
value-collection
No
A path string that evaluates to an array of objects in the response payload. If value-collection isn't specified, the response is evaluated as an array.
value-title
No
A path string in the object inside value-collection that refers to the value's description.
value-path
No
A path string in the object inside value-collection that refers to the parameter value.
JSON
"x-ms-dynamic-values": {
"operationId": "PopulateDropdown",
"value-path": "name",
"value-title": "properties/displayName",
"value-collection": "value",
"parameters": {
"staticParameter": "<value>",
"dynamicParameter": {
"parameter": "<name of the parameter to be referenced>"
}
}
}
Note
It's possible to have ambiguous parameter references when using dynamic values. For instance, in the following definition of an operation, the dynamic values reference the field id, which is ambiguous from the definition because it's not clear whether it references the parameter id or the property requestBody/id.
There's no way to reference parameters unambiguously. This feature might be provided in the future. If you want your operation to take advantage of any new updates, add the new extension x-ms-dynamic-list along with x-ms-dynamic-values. Also, if your dynamic extension references properties within parameters, you have to add the new extension x-ms-dynamic-list along with x-ms-dynamic-values. The parameter references that point to properties must be expressed as path strings.
parameters—This property is an object where each input property of the dynamic operation being called is defined with either a static value field or a dynamic reference to the source operation's property. Both of these options are defined in the following.
value—This is the literal value to be used for the input parameter. In the following example, the input parameter of the operation GetDynamicList operation named version is defined by using a static value of 2.0.
parameterReference—This is the full parameter reference path, starting with the parameter name followed by the path string of the property to be referenced. For example, the input property of the operation GetDynamicList named property1, which is under the parameter destinationInputParam1, is defined as a dynamic reference to a property named property1 under parameter sourceInputParam1 of the source operation.
If you want to reference any property that's marked as internal with a default value, you have to use the default value as a static value in the definition here, instead of parameterReference. The default value from the list isn't used if it's defined by using parameterReference.
Name
Required
Description
operationId
Yes
The operation that returns the list.
parameters
Yes
An object that provides the input parameters required to invoke a dynamic list operation.
itemsPath
No
A path string that evaluates to an array of objects in the response payload. If itemsPath isn't provided, the response is evaluated as an array.
itemTitlePath
No
A path string in the object inside itemsPath that refers to the value's description.
itemValuePath
No
A path string in the object inside itemsPath that refers to the item's value.
With x-ms-dynamic-list, use parameter references with the path string of the property you're referencing. Use these parameter references for both the key and the value of the dynamic operation parameter reference.
The dynamic schema indicates that the schema for the current parameter or response is dynamic. This object invokes an operation that's defined by the value in this field, dynamically discovers the schema, and displays the appropriate user interface for collecting user input or shows the available fields.
Applies to: Parameters, responses
This image shows how the input form changes, based on the item that the user selects from the list:
This image shows how the outputs change, based on the item that the user selects from the dropdown list. In this version, the user selects Cars:
In this version, the user selects Food:
How to use dynamic schema
Note
A path string is a JSON pointer that doesn't contain the leading forward slash. So, this is a JSON pointer: /property/childProperty, and this is a path string: property/childProperty.
There are two ways to define dynamic schema:
x-ms-dynamic-schema:
Name
Required
Description
operationId
Yes
The operation that returns the schema.
parameters
Yes
An object that provides the input parameters that are required to invoke a dynamic-schema operation.
value-path
No
A path string that refers to the property that has the schema. If not specified, the response is assumed to contain the schema in the root object's properties. If specified, the successful response must contain the property. For an empty or undefined schema, this value should be null.
There might be ambiguous references in the parameters. For instance, in the following definition of an operation, the dynamic schema references a field named query, which can't be deterministically understood from the definition—whether it's referencing the parameter object query or the string property query/query.
There's no way to reference parameters unambiguously. This feature might be provided in the future. If you want your operation to take advantage of any new updates, add the new extension x-ms-dynamic-properties along with x-ms-dynamic-schema. Also, if your dynamic extension references properties within parameters, you have to add the new extension x-ms-dynamic-properties along with x-ms-dynamic-schema. The parameter references that point to properties must be expressed as path strings.
parameters—This property is an object where each input property of the dynamic operation being called is defined with either a static value field or a dynamic reference to the source operation's property. Both of these options are defined in the following.
value—This is the literal value to be used for the input parameter. In the following example, the input parameter of the GetDynamicSchema operation named version is defined with a static value of 2.0.
parameterReference—This is the full parameter reference path, starting with the parameter name followed by the path string of the property to be referenced. For example, the input property of the operation GetDynamicSchema named property1, which is under the parameter destinationInputParam1, is defined as a dynamic reference to a property named property1 under parameter sourceInputParam1 of the source operation.
If you want to reference any property that's marked as internal with a default value, you have to use the default value as a static value in the definition here, instead of parameterReference. The default value from the schema isn't used if it's defined by using parameterReference.
Name
Required
Description
operationId
Yes
The operation that returns the schema.
parameters
Yes
An object that provides the input parameters that are required to invoke a dynamic-schema operation.
itemValuePath
No
A path string that refers to the property that has the schema. If not specified, the response is assumed to contain the schema in the root object. If specified, the successful response must contain the property. For an empty or undefined schema, this value should be null.
With x-ms-dynamic-properties, parameter references can be used with the path string of the property to be referenced, both for the key and the value of the dynamic operation parameter reference.
We greatly appreciate feedback on issues with our connector platform, or new feature ideas. To provide feedback, go to Submit issues or get help with connectors and select your feedback type.