{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://raw.githubusercontent.com/theizzatbek/gokit/main/schemas/routes.schema.json",
  "title": "fibermap routes.yaml",
  "description": "Schema for fibermap (https://github.com/theizzatbek/gokit/tree/main/fibermap) YAML route trees. Add `# yaml-language-server: $schema=https://raw.githubusercontent.com/theizzatbek/gokit/main/schemas/routes.schema.json` to the top of routes.yaml for editor autocomplete.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "middleware_sets": {
      "description": "Named bundles of middleware refs (plain or factory). May reference other set names; resolved recursively at mount time. Cycles are detected and reported as CodeMiddlewareCycle.",
      "type": "object",
      "additionalProperties": {
        "type": "array",
        "items": { "$ref": "#/definitions/middlewareRef" }
      }
    },
    "groups": {
      "description": "Route tree. Groups can nest arbitrarily; child groups inherit prefix and ancestor middleware chain.",
      "type": "array",
      "items": { "$ref": "#/definitions/group" }
    }
  },
  "definitions": {
    "middlewareRef": {
      "description": "A middleware reference. Scalar string -> plain middleware (RegisterMiddleware). Single-key map {name: [args...]} -> factory call (RegisterMiddlewareFactory).",
      "oneOf": [
        { "type": "string", "description": "Name of a middleware registered via RegisterMiddleware." },
        {
          "type": "object",
          "description": "Factory invocation. Exactly one key (the factory name) whose value is an array of string arguments. The factory is called once per (name, args) tuple at Mount time and cached.",
          "minProperties": 1,
          "maxProperties": 1,
          "additionalProperties": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      ]
    },
    "group": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "prefix": {
          "type": "string",
          "description": "Path prefix appended to the ancestor chain. May be empty."
        },
        "middleware": {
          "type": "array",
          "description": "Middleware refs applied to every route in this group (and nested groups). Order is outermost-first.",
          "items": { "$ref": "#/definitions/middlewareRef" }
        },
        "middleware_set": {
          "type": "string",
          "description": "Name of a set declared in the top-level middleware_sets map. Validated at mount time; CodeUnknownMiddlewareSet on miss."
        },
        "routes": {
          "type": "array",
          "items": { "$ref": "#/definitions/route" }
        },
        "groups": {
          "type": "array",
          "items": { "$ref": "#/definitions/group" }
        }
      }
    },
    "route": {
      "type": "object",
      "additionalProperties": false,
      "required": ["method", "handler"],
      "properties": {
        "method": {
          "type": "string",
          "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"],
          "description": "HTTP method. Uppercase only."
        },
        "path": {
          "type": "string",
          "description": "Fiber path pattern. Supports `:param` and `*` wildcards."
        },
        "handler": {
          "type": "string",
          "description": "Name of a handler registered via RegisterHandler. Required."
        },
        "middleware": {
          "type": "array",
          "description": "Middleware refs appended after the inherited group chain.",
          "items": { "$ref": "#/definitions/middlewareRef" }
        },
        "middleware_set": {
          "type": "string",
          "description": "Name of a set declared in middleware_sets."
        },
        "name": {
          "type": "string",
          "description": "Free-form identifier. Not interpreted by fibermap; surfaced via Engine.Routes() and Walk() for OpenAPI/docs tooling."
        },
        "summary": {
          "type": "string",
          "description": "Short one-line title. Surfaced via Routes()/Walk() — OpenAPI generation maps it to operation.summary."
        },
        "tags": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Free-form labels. Surfaced via Routes()/Walk()."
        },
        "description": {
          "type": "string",
          "description": "Free-form description. Surfaced via Routes()/Walk()."
        },
        "timeout": {
          "type": "string",
          "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)([0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h))*$",
          "description": "Go duration string ('5s', '300ms', '1m30s'). When set, the route is wrapped with Fiber's timeout middleware (NewWithContext): the handler's UserContext deadline is set to this duration, and a returned context.DeadlineExceeded surfaces as 408 Request Timeout. Empty (default) means no per-route timeout."
        },
        "cache": {
          "description": "Enables response caching for this route. Either a scalar duration string (TTL only) or a mapping with finer-grained options. Engine-wide knobs (Storage, KeyBy) are set on Engine via SetCacheDefaults — KeyBy is REQUIRED for user-specific responses or one user's cached body will be served to another.",
          "oneOf": [
            {
              "type": "string",
              "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)([0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h))*$",
              "description": "Scalar form: TTL only (e.g. '30s')."
            },
            {
              "type": "object",
              "additionalProperties": false,
              "required": ["ttl"],
              "properties": {
                "ttl": {
                  "type": "string",
                  "pattern": "^[0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h)([0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h))*$",
                  "description": "Go duration string. Required, > 0."
                },
                "control": {
                  "type": "boolean",
                  "description": "Respect Cache-Control: no-store / no-cache request headers (forwarded to fiber.cache.Config.CacheControl)."
                },
                "headers": {
                  "type": "boolean",
                  "description": "Cache and replay handler-set response headers (forwarded to fiber.cache.Config.StoreResponseHeaders)."
                },
                "vary_header": {
                  "type": "array",
                  "description": "Request headers whose values get folded into the cache key. Two requests with different Accept-Language values keep separate cache entries.",
                  "items": { "type": "string" }
                }
              }
            }
          ]
        }
      }
    }
  }
}