Supported OpenAPI (Off-chain Kernel)

The table below explains the OpenAPI schemas that KRNL currently supports.

To read more about OpenAPI, visit this page:

What Is OpenAPI?Swagger Docs

---

Example

Example Schema

{
  "openapi": "3.0.3",
  "info": {
    "title": "Wallet Score Check GET",
    "version": "1.0.0",
    "description": "API for checking the score and status of a wallet address."
  },
  "servers": [
    {
      "url": "https://web2-off-chain.com"
    }
  ],
  "paths": {
    "/wallet-check-get-{wallet_address}": {
      "get": {
        "summary": "Check the score of a wallet address",
        "parameters": [
          {
            "name": "wallet_address",
            "in": "path",
            "required": true,
            "description": "The wallet address to check.",
            "schema": {
              "type": "string",
              "example": "0x1234567890"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "wallet_address": {
                      "type": "string",
                      "example": "0x1234567890"
                    },
                    "score": {
                      "type": "integer",
                      "example": 57
                    },
                    "status": {
                      "type": "string",
                      "example": "pass"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "404": {
            "description": "Wallet not found"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "WalletCheckResponse": {
        "type": "object",
        "properties": {
          "wallet_address": {
            "type": "string"
          },
          "score": {
            "type": "integer"
          },
          "status": {
            "type": "string"
          }
        }
      }
    }
  }
}

---

Important Notes

1. Using AI Tools

One important note here is that if you are generating OpenAPI Specification by using AI, the schema might be misaligned.

Be careful and make sure the schema matches with this guide. This is to avoid paying gas fees for registration of the wrong schema.

2. Single API Endpoint

With KRNL's current architecture, Web APIs that can be registered as off-chain kernels must be single API Endpoint.

3. HTTP Request Method

Currently we only support GET and POST as methods for calling off-chain kernels.

4. JSON

The current architecture of kOS supports only JSON format. YAML is currently supported.

---

There are various approaches to constructing and writing OpenAPI schema specifications. While some schemas are compatible with our technology, others may require small modifications.

While OpenAPI 3.0.x might be eligible, we recommend using OpenAPI version 3.1.x.

Schemata that are not defined in this page may not work with our architecture.

Element	Example	Description
null value	//... "type": "string", "nullable": true //...	This is the only correct way to handle null value on OpenAPI 3.0 Specification. Other methods might be from the older version. There is a caveat when working with null value, please check the "anyOf" section.
anyOf	Check anyOf section	Some cases are supported Click here to read more
oneOf	Check oneOf section	Some cases are supported Click here to read more
allOf	not supported at the moment	-
Enumeration	Check Enum section	Click here to read more

---

anyOf

Supported Schema

When it comes to the schemas that use the "anyOf" element, the KRNL node can support some specific cases.

anyOf with null under "components"

JSON

// ...
"components": {
    "schemas": {
        "Foo": {
            "properties": {
                "address": {
                    "anyOf": [
                    {
                        "type": "string"
                    },
                    {
                        "type": "null"
                    }
                    ],
                }
            }
        }
    }
}
// ...

anyOf with null under "responses"

JSON

// ...
"responses": {
    "200": {
        "description": "Successful response",
        "content": {
            "application/json": {
                "schema": {
                    "type": "object",
                    "properties": {
                        "age": {
                            "anyOf": [
                                {
                                    "type": "integer"
                                },
                                {
                                    "type": "null"
                                }
                            ]
                        }
                    }
                }
            }
        }
    }
}
// ...

Unsupported Schema

anyOf in array of objects and null

JSON

// ...
"responses": {
  "200": {
    "description": "Successful response",
    "content": {
      "application/json": {
        "schema": {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "age": {
                    "anyOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "example": 10
                  },
                  "name": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "example": "robot"
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}
// ...

---

oneOf

Supported Schema

JSON

// ...
"responses": {
  "200": {
    "description": "Successful response",
    "content": {
      "application/json": {
        "schema": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/AlphaResponse"
            },
            {
              "$ref": "#/components/schemas/BetaResponse"
            }
          ]
        }
      }
    }
  }
}
// ...
"components": {
  "schemas": {
    "AlphaResponse": {
      "type": "object",
      "properties": {
        "statustext": {
          "type": "string"
        },
        "good": {
          "type": "boolean"
        }
      }
    },
    "BetaResponse": {
      "type": "object",
      "properties": {
        "numbervalue": {
          "type": "integer"
        }
      }
    }
  }
}
// ...

Unsupported Schema

Discriminator

JSON

// ...
"discriminator": {
  "propertyName": "event_type",
  "mapping": {
    "temperature_alert": "#/components/schemas/TemperatureEvent",
    "motion_detection": "#/components/schemas/MotionEvent",
    "battery_status": "#/components/schemas/BatteryEvent"
  }
},
"oneOf": [
  {
    "$ref": "#/components/schemas/TemperatureEvent"
  },
  {
    "$ref": "#/components/schemas/MotionEvent"
  },
  {
    "$ref": "#/components/schemas/BatteryEvent"
  }
]
// ...

---

Enumeration

Supported Schemas

JSON

// ...
"components": {
    "schemas": {
      "StatusEnum": {
        "enum": [
          "PROCESSING",
          "BULK_PROCESSING",
          "ERROR",
          "DONE"
        ],
        "title": "StatusEnum",
        "type": "string"
      }
  }
}
// ...