# Oracle Integration Specifications (OIS) 1.0.0
See our article, Setting Oracle Integration Standards (opens new window) for an overview of OIS.
Fields denoted by * are for documentation purposes and not used by the oracle node.
The OAS equivalents given are used to automatically populate OIS fields. These prepopulated fields are expected to be reviewed and customized by the integrating party.
All URLs are absolute (i.e., relative URLs (opens new window) are not supported).
{
"oisFormat": "1.0.0",
"title": "myOisTitle",
"version": "1.2.3",
"apiSpecifications": {
...
},
"endpoints": [
...
]
}
2
3
4
5
6
7
8
9
10
11
# 1. oisFormat
(Required) The OIS format version followed while generating the specifications.
# 2. title
(Required) The OIS title. Title field is at most 64 characters, can only include alphanumeric characters, hyphens, underscores and whitespaces.
OAS equivalent: info.title
# 3. version
(Required) The version for this specific OIS.
# 4. apiSpecifications
(Required) An object specifying the API with the following fields:
{
"servers": [
{
"url": "https://myapi.com/api/v1"
}
],
"components": {
"securitySchemes": {
"mySecurityScheme1": {
"type": "apiKey",
"name": "X-MY-API-KEY",
"in": "query"
}
}
},
"security": {
"mySecurityScheme1": []
},
"paths": {
"/myPath": {
"get": {
"parameters": [
{
"name": "myParameter",
"in": "query"
}
]
}
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# 4.1. servers
(Required) An array of objects containing the base URL of the API. Only one object (i.e., base URL) is allowed in the array. Applies to all operations.
OAS equivalent: servers.0 (raise warning during conversion if servers has multiple elements)
# 4.2. components
(Required) An object where security schemes can be found under securitySchemes.{securitySchemeName} with the following elements:
# 4.2.1. type
(Required) The type of the security scheme.
Allowed values: apiKey, http
OAS equivalent: components.securitySchemes.{securitySchemeName}.type
# 4.2.2. name
(Required if scheme is not http) The name of the security scheme variable.
OAS equivalent: components.securitySchemes.{securitySchemeName}.name
# 4.2.3. in
(Required) The location of the security scheme variable.
Allowed values: query, header, cookie
OAS equivalent: components.securitySchemes.{securitySchemeName}.in
# 4.2.4. scheme
(Required if security scheme type is http) The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235 (opens new window).
Allowed values: The values used SHOULD be registered in the IANA Authentication Scheme registry (opens new window).
We support basic and bearer.
OAS equivalent: components.securitySchemes.{securitySchemeName}.scheme
# 4.3. security
(Required) An object containing all security schemes that need to be used to access the API.
Applies to all operations.
Unlike in OAS, security cannot be a list.
Each security scheme maps to an empty list as:
"security": {
"mySecurityScheme1": []
}
2
3
OAS equivalent: security, or security.0 if security is a list (raise warning during conversion if security is a list with multiple elements)
# 4.4. paths
(Required) An object where operations can be found under {path}.{method} with the following elements:
# 4.4.1. parameters
(Required) A list of operation parameters, each with the following fields:
# 4.4.1.1. name
(Required) The name of the parameter.
OAS equivalent: paths.{path}.{method}.parameters.{#}.name
# 4.4.1.2. in
(Required) The location of the parameter.
Allowed values: query, header, path, cookie
OAS equivalent: paths.{path}.{method}.parameters.{#}.in
When integrating a POST method, define the body parameters with in: query. Airnode will convert all query types into the requestBody. Note that only the non-nested application/json content-type is supported.
# 5. endpoints
(Required) A list of objects, each specifying an oracle endpoint with the following fields:
nameoperationfixedOperationParametersreservedParametersparameterssummary*description*externalDocs*
[
{
"name": "convertToUsd",
"operation": {
"path": "/myPath",
"method": "get"
},
"fixedOperationParameters": [
{
"operationParameter": {
"name": "to",
"in": "query"
},
"value": "USD"
}
],
"reservedParameters": [
{
"name": "_type",
"fixed": "int256"
},
{
"name": "_path",
"default": "data.0.price"
},
{
"name": "_times"
},
{
"name": "_relay_metadata",
"default": "v1"
}
],
"parameters": [
{
"name": "f",
"default": "EUR",
"operationParameter": {
"name": "from",
"in": "query"
}
}
]
}
]
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
# 5.1. name
(Required) The name of the endpoint, must be unique in OIS.
OAS equivalent: paths.{path}.{method}.operationId of the corresponding operation
# 5.2. operation
(Required) An object that refers to an operation defined in apiSpecifications.paths, has the following elements:
# 5.2.1. path
(Required) The path of the operation.
OAS equivalent: The {path} parameter in the paths.{path}.{method} for the respective operation
# 5.2.2. method
(Required) The method of the operation.
Allowed values: get, post
OAS equivalent: The {method} parameter in the paths.{path}.{method} for the respective operation
# 5.3. fixedOperationParameters
(Required) A list of objects specifying fixed operation parameters. While required, the fixedOperationParameters array can be left empty. Each object has the following elements:
# 5.3.1. operationParameter
(Required) An object that refers to an operation parameter, has the following elements:
# 5.3.2. value
(Required) The value to be used for the respective operation parameter that cannot be overridden by the requester.
# 5.4. reservedParameters
(Optional) A list of objects that specify reserved endpoint parameters that do not map to operation parameters, but used for special purposes by the oracle node. Each object has the following elements:
# 5.4.1. name
(Required) The name of the reserved parameter.
Always starts with _.
Allowed values: _type, _path, _times, _relay_metadata
# 5.4.2. fixed
(Optional) The fixed (i.e., non-overrideable) value for the reserved parameter.
# 5.4.3. default
(Optional) The default value for the reserved parameter. Used when no value is provided.
# 5.5. parameters
(Optional) A list of objects that specify endpoint parameters that map to operation parameters. Each object has the following elements:
# 5.5.1. operationParameter
(Required) An object that refers to an operation parameter, has the following elements:
# 5.5.2. name
(Required) The name of the endpoint parameter.
Is not allowed to start with _.
OAS equivalent: paths.{path}.{method}.parameters.{#}.name of corresponding operation parameter
# 5.5.3. default
(Optional) The default value for the endpoint parameter. Used when no value is provided.
OAS equivalent: paths.{path}.{method}.parameters.{#}.default of corresponding operation parameter
# 5.5.4. description*
(Optional) A description of what the endpoint parameter does.
OAS equivalent: paths.{path}.{method}.parameters.{#}.description of the corresponding operation parameter
# 5.5.5. required*
(Optional) If the endpoint parameter is required, is a boolean value.
OAS equivalent: paths.{path}.{method}.parameters.{#}.required of the corresponding operation parameter
# 5.5.6. example*
(Optional) The example value to be used in test calls.
OAS equivalent: paths.{path}.{method}.parameters.{#}.example of the corresponding operation parameter
# 5.6. summary*
(Optional) A one sentence summary of what the endpoint does.
OAS equivalent: paths.{path}.{method}.summary of corresponding operation
# 5.7. description*
(Optional) A more detailed description of what the endpoint does.
OAS equivalent: paths.{path}.{method}.description of corresponding operation
# 5.8. externalDocs*
(Optional) URL to external documentation for the endpoint.
OAS equivalent: paths.{path}.{method}.externalDocs of corresponding operation