kong-service-schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/api-evangelist/kong/blob/main/json-schema/kong-service-schema.json",
  "title": "Kong Gateway Service",
  "description": "A Service object represents an upstream API or microservice that Kong Gateway proxies requests to. Services are the core entities used to configure the upstream URL that incoming requests are forwarded to. Each Service can have multiple Routes associated with it.",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "The unique identifier (UUID) of the Service, auto-generated by Kong upon creation.",
      "readOnly": true
    },
    "name": {
      "type": "string",
      "description": "An optional unique human-readable name for the Service. Used for identification and as an alternative to the UUID when referencing the Service in the Admin API.",
      "pattern": "^[a-zA-Z0-9.\\-_~]+$",
      "maxLength": 128
    },
    "protocol": {
      "type": "string",
      "description": "The protocol used to communicate with the upstream. Accepted values are http, https, grpc, grpcs, tcp, tls, udp, ws, and wss.",
      "enum": [
        "http",
        "https",
        "grpc",
        "grpcs",
        "tcp",
        "tls",
        "udp",
        "ws",
        "wss"
      ],
      "default": "http"
    },
    "host": {
      "type": "string",
      "description": "The host of the upstream server. This can be a hostname or an IP address. Note that the host value is case-sensitive."
    },
    "port": {
      "type": "integer",
      "description": "The upstream server port.",
      "default": 80,
      "minimum": 0,
      "maximum": 65535
    },
    "path": {
      "type": ["string", "null"],
      "description": "The path to be used in requests to the upstream server. This is prepended to the path specified in the incoming request.",
      "pattern": "^/.*"
    },
    "retries": {
      "type": "integer",
      "description": "The number of retries to execute upon failure to proxy. Zero means no retries.",
      "default": 5,
      "minimum": 0
    },
    "connect_timeout": {
      "type": "integer",
      "description": "The timeout in milliseconds for establishing a connection to the upstream server.",
      "default": 60000,
      "minimum": 0
    },
    "write_timeout": {
      "type": "integer",
      "description": "The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server.",
      "default": 60000,
      "minimum": 0
    },
    "read_timeout": {
      "type": "integer",
      "description": "The timeout in milliseconds between two successive read operations for receiving a response from the upstream server.",
      "default": 60000,
      "minimum": 0
    },
    "url": {
      "type": "string",
      "format": "uri",
      "description": "Shorthand attribute to set protocol, host, port, and path at once. This field is write-only and is not returned in GET responses.",
      "writeOnly": true
    },
    "tags": {
      "type": ["array", "null"],
      "description": "An optional set of strings associated with the Service for grouping and filtering. Each tag must be composed of printable ASCII characters.",
      "items": {
        "type": "string",
        "maxLength": 128,
        "pattern": "^[\\x20-\\x7E]+$"
      },
      "maxItems": 20,
      "uniqueItems": true
    },
    "client_certificate": {
      "type": ["object", "null"],
      "description": "Certificate to be used as client certificate while TLS handshaking to the upstream server. Referenced by UUID of a Certificate entity.",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "The UUID of the Certificate entity."
        }
      },
      "required": ["id"],
      "additionalProperties": false
    },
    "tls_verify": {
      "type": ["boolean", "null"],
      "description": "Whether to enable verification of upstream server TLS certificate. If set to null, the Nginx default is respected."
    },
    "tls_verify_depth": {
      "type": ["integer", "null"],
      "description": "Maximum depth of chain while verifying upstream server TLS certificate. If set to null, the Nginx default is respected.",
      "minimum": 0
    },
    "ca_certificates": {
      "type": ["array", "null"],
      "description": "Array of CA Certificate object UUIDs that are used to build the trust store while verifying upstream server TLS certificate.",
      "items": {
        "type": "string",
        "format": "uuid"
      }
    },
    "enabled": {
      "type": "boolean",
      "description": "Whether the Service is active. If set to false, the proxy behavior will act as if any Routes attached to it do not exist.",
      "default": true
    },
    "created_at": {
      "type": "integer",
      "description": "Unix epoch timestamp (in seconds) of when the Service entity was created.",
      "readOnly": true
    },
    "updated_at": {
      "type": "integer",
      "description": "Unix epoch timestamp (in seconds) of when the Service entity was last updated.",
      "readOnly": true
    }
  },
  "required": ["host"],
  "additionalProperties": false,
  "examples": [
    {
      "id": "9748f662-7711-4a90-8186-dc02f10eb0f5",
      "name": "example-service",
      "protocol": "http",
      "host": "httpbin.org",
      "port": 80,
      "path": "/anything",
      "retries": 5,
      "connect_timeout": 60000,
      "write_timeout": 60000,
      "read_timeout": 60000,
      "tags": ["example", "httpbin"],
      "enabled": true,
      "created_at": 1422386534,
      "updated_at": 1422386534
    }
  ]
}