Kong Gateway’s declarative configuration approach is powerful, but it opens the door to subtle routing mistakes that can break your API in production. One of the most common issues I’ve recently encountered is malformed route paths: missing path arrays, empty strings, or accidentally defining paths as strings instead of arrays. These errors often slip through manual reviews and only surface when traffic starts failing.

To catch these configuration errors early in our CI pipeline, I built a custom ruleset that enforces proper route path structure before deployment.

The Ruleset

# Kong Route Path Validation Ruleset
# This ruleset validates that Kong routes have properly configured paths to prevent
# routing issues and conflicts. It ensures all routes have valid, non-empty paths
# that can be used for proper request routing.

rules:
  # Rule 1: Ensure paths field exists
  # Purpose: Validates that every route has a 'paths' field defined
  # Catches: Routes missing the paths field entirely
  route-must-have-paths:
    description: "Routes must have a paths field"
    given: $.services[*].routes[*]
    severity: error
    then:
      function: truthy
      field: paths
   
  # Rule 2: Validate paths field content and structure
  # Purpose: Ensures paths is a proper array with valid path strings
  # Schema validation breakdown:
  #   - type: array          -> paths must be an array, not string/object
  #   - minItems: 1          -> array must contain at least one path
  #   - items.type: string   -> each path must be a string
  #   - items.pattern        -> each path must match the regex pattern
  #
  # Regex Pattern: "^\\S+.*$"
  #   - ^          -> Start of string
  #   - \\S+       -> One or more non-whitespace characters (required)
  #   - .*         -> Followed by any characters (optional)
  #   - $          -> End of string
  #
  # This pattern ensures paths:
  #   - Cannot be empty strings: "" (fails \\S+)
  #   - Cannot be whitespace-only: " ", "\t", "\n" (fails \\S+)
  #   - Must start with non-whitespace character
  #   - Can contain spaces after the first character: "/api/v1 test" (valid)
  route-paths-validation:
    description: "Routes must have valid non-empty paths array with non-empty path values"
    given: $.services[*].routes[*]
    severity: error
    then:
      function: schema
      field: paths
      functionOptions:
        schema:
          type: array
          minItems: 1
          items:
            type: string
            pattern: "^\\S+.*$"

What It Catches

This ruleset validates two critical aspects of Kong route configuration:

Missing Paths Field:

  • Routes that completely omit the paths field
  • Routes with paths set to null or undefined

Invalid Paths Content:

  • Empty arrays: paths: []
  • Empty strings: paths: [""]
  • Whitespace-only strings: paths: [" "], paths: ["\t"]
  • Mixed valid/invalid paths: paths: ["", "/api"]
  • Incorrect data types: paths: "/api/v1" (string instead of array)

Examples

✅ Valid Configurations:

# Single path
paths: ["/api/v1"]

# Multiple paths
paths: ["/api", "/v2"]

# Path with spaces (after non-whitespace)
paths: ["/api/v1 test"]

❌ Invalid Configurations:

# Missing paths field entirely
routes:
  - name: "route-without-paths"
    methods: ["GET"]
    # No paths field - FAILS

# Empty array
paths: []

# Empty string
paths: [""]

# Whitespace-only
paths: [" "]
paths: ["\t"]

# Wrong data type (string instead of array)
paths: "/api/v1"

# Mixed valid/invalid
paths: ["", "/api"]

Usage

You can lint your Kong deck config using:

deck file lint -s kong.yaml ruleset.yaml

Simple, powerful, and CI-friendly. This approach helps catch configuration errors early in your development pipeline, preventing routing issues before they reach production environments.