A newer release of the API3 Technical documentation is available.

📂 Reference > Specifications

# Oracle Integration Specifications (OIS) 1.0.0

Table of Contents

The Oracle Integration Specification (OIS) is based on Open API specification (OAS) (opens new window), but there are some differences, so be sure to read our documentation when working on your OIS file.

OAS

It is not recommended to refer to OAS for help while creating your OIS object. OIS only borrows formatting practices from OAS. Everything needed to create an OIS object is in these docs.

See the 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 (opens new window) equivalents are given as reference to assist in the populating of OIS fields. The OIS fields should be reviewed and customized by the integrating party.
All URLs are absolute (i.e., relative URLs (opens new window) are not supported).

# OIS Object Summary

An OIS has five fields.

apiSpecifications describe the API's operations which are mapped to the endpoints that Airnode exposes on-chain.

{
  "oisFormat": "1.0.0",
  "title": "myOisTitle",
  "version": "1.2.3",
  "apiSpecifications": {
    ...
  },
  "endpoints": [
    ...
  ]
}

1
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:

// apiSpecifications
{
  "servers": [
    {
      "url": "https://myapi.com/api/v1"
    }
  ],
  "paths": {
    "/myPath": {
      "get": {
        "parameters": [
          {
            "name": "myParameter",
            "in": "query"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "mySecurityScheme1": {
        "type": "apiKey",
        "name": "X-MY-API-KEY",
        "in": "query"
      }
    }
  },
  "security": {
    "mySecurityScheme1": []
  }
}

1
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

# 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. `paths`

(Required) An object where operations can be found under {path}.{method} with the following elements:

parameters

# 4.2.1. `parameters`

(Required) A list of operation parameters, each with the following fields:

name
in

# 4.2.1.1. `name`

(Required) The name of the parameter.

OAS equivalent: paths.{path}.{method}.parameters.{#}.name

# 4.2.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.

# 4.3. `components`

(Required) An object where security schemes can be found under securitySchemes.{securitySchemeName} with the following elements:

# 4.3.1. `type`

(Required) The type of the security scheme.

Allowed values: apiKey, http

OAS equivalent: components.securitySchemes.{securitySchemeName}.type

# 4.3.2. `name`

(Only if type is apiKey) The name of the security scheme variable.

OAS equivalent: components.securitySchemes.{securitySchemeName}.name

# 4.3.3. `in`

(Only if type is apiKey) The location of the security scheme variable.

Allowed values: query, header, cookie

OAS equivalent: components.securitySchemes.{securitySchemeName}.in

# 4.3.4. `scheme`

(Only if 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:

basic and bearer.

OAS equivalent: components.securitySchemes.{securitySchemeName}.scheme

# 4.4. `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": []
}

1
2
3

OAS equivalent: security, or security.0 if security is a list.

Please note:

Currently Airnode reads the security schemes from component.securitySchemes and not security. Using the security field now provides for a smooth transition to future releases of Airnode with regards to security scheme implementation. This will allow assigning of security schemes to individual API operations. Currently security schemes are assign to the entire API.

# 5. `endpoints`

(Required) A list of objects, each specifying an oracle endpoint with the following fields:

// endpoints
[
  {
    "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": "from",
        "default": "EUR",
        "operationParameter": {
          "name": "from",
          "in": "query"
        }
      }
    ],
    "testable": true
  }
]

1
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
46
47

# 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:

name
in

# 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:

name
in

# 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

# 5.9. `testable`

(Optional) Flag that indicates if the endpoint can be tested with the HTTP gateway. The gateway must be enabled.

Allowed values: true, false

← Chain Providers Airnode ABI Specification →

# Oracle Integration Specifications (OIS) 1.0.0

# OIS Object Summary

# 1. oisFormat

# 2. title

# 3. version

# 4. apiSpecifications

# 4.1. servers

# 4.2. paths

# 4.2.1. parameters

# 4.2.1.1. name

# 4.2.1.2. in

# 4.3. components

# 4.3.1. type

# 4.3.2. name

# 4.3.3. in

# 4.3.4. scheme

# 4.4. security

# 5. endpoints

# 5.1. name

# 5.2. operation

# 5.2.1. path

# 5.2.2. method

# 5.3. fixedOperationParameters

# 5.3.1. operationParameter

# 5.3.2. value

# 5.4. reservedParameters

# 5.4.1. name

# 5.4.2. fixed

# 5.4.3. default

# 5.5. parameters

# 5.5.1. operationParameter

# 5.5.2. name

# 5.5.3. default

# 5.5.4. description*

# 5.5.5. required*

# 5.5.6. example*

# 5.6. summary*

# 5.7. description*

# 5.8. externalDocs*

# 5.9. testable