MappingSpec

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "#/components/schemas/MappingSpec",
  "title": "MappingSpec",
  "type": "object",
  "description": "Specification for an Ambassador Mapping",
  "required": [
    "hostname",
    "prefix",
    "service"
  ],
  "properties": {
    "hostname": {
      "type": "string",
      "description": "Hostname to match for this Mapping. Use '*' to match all hostnames.",
      "example": "api.example.com"
    },
    "prefix": {
      "type": "string",
      "description": "URL prefix to match for routing",
      "example": "/api/v1/"
    },
    "prefix_regex": {
      "type": "boolean",
      "description": "Whether the prefix should be interpreted as a regular expression",
      "default": false,
      "example": true
    },
    "prefix_exact": {
      "type": "boolean",
      "description": "Whether the prefix should be matched exactly rather than as a prefix",
      "default": false,
      "example": true
    },
    "service": {
      "type": "string",
      "description": "Target service to route to, in the format service-name.namespace:port or a full URL",
      "example": "my-service.default:8080"
    },
    "rewrite": {
      "type": "string",
      "description": "Prefix rewrite rule applied to the URL before forwarding to the backend service. Set to empty string to disable rewriting.",
      "example": "/"
    },
    "method": {
      "type": "string",
      "description": "HTTP method to match",
      "enum": [
        "GET",
        "POST",
        "PUT",
        "DELETE",
        "PATCH",
        "HEAD",
        "OPTIONS"
      ],
      "example": "GET"
    },
    "method_regex": {
      "type": "boolean",
      "description": "Whether the method value is a regular expression",
      "default": false,
      "example": true
    },
    "headers": {
      "type": "object",
      "description": "HTTP headers that must be present on the request for this Mapping to match. Values can be exact strings or regular expressions.",
      "additionalProperties": {
        "type": "string"
      },
      "example": "example_value"
    },
    "query_parameters": {
      "type": "object",
      "description": "Query parameters that must be present for this Mapping to match",
      "additionalProperties": {
        "type": "string"
      },
      "example": "example_value"
    },
    "host": {
      "type": "string",
      "description": "Deprecated. Use hostname instead.",
      "deprecated": true,
      "example": "example_value"
    },
    "host_regex": {
      "type": "boolean",
      "description": "Deprecated. Whether host is a regular expression.",
      "deprecated": true,
      "example": true
    },
    "timeout_ms": {
      "type": "integer",
      "description": "Request timeout in milliseconds",
      "minimum": 0,
      "example": 30000
    },
    "idle_timeout_ms": {
      "type": "integer",
      "description": "Idle timeout for streaming connections in milliseconds",
      "minimum": 0,
      "example": 10
    },
    "connect_timeout_ms": {
      "type": "integer",
      "description": "Upstream connection timeout in milliseconds",
      "minimum": 0,
      "example": 10
    },
    "cluster_idle_timeout_ms": {
      "type": "integer",
      "description": "Idle timeout for upstream connections in the cluster in milliseconds",
      "minimum": 0,
      "example": 10
    },
    "weight": {
      "type": "integer",
      "description": "Weight for traffic splitting when multiple Mappings match the same prefix. Used in canary deployments.",
      "minimum": 0,
      "maximum": 100,
      "example": 10
    },
    "bypass_auth": {
      "type": "boolean",
      "description": "Whether to bypass the external authentication service for this Mapping",
      "default": false,
      "example": true
    },
    "cors": {
      "$ref": "#/components/schemas/CORSPolicy"
    },
    "retry_policy": {
      "$ref": "#/components/schemas/RetryPolicy"
    },
    "circuit_breakers": {
      "type": "array",
      "description": "Circuit breaker configurations for the upstream cluster",
      "items": {
        "$ref": "#/components/schemas/CircuitBreaker"
      },
      "example": []
    },
    "load_balancer": {
      "$ref": "#/components/schemas/LoadBalancer"
    },
    "labels": {
      "type": "object",
      "description": "Rate limiting labels to apply to requests matching this Mapping. Labels are sent to the rate limiting service for evaluation.",
      "additionalProperties": true,
      "example": "example_value"
    },
    "add_request_headers": {
      "type": "object",
      "description": "Headers to add to the request before forwarding to the upstream",
      "additionalProperties": {
        "type": "string"
      },
      "example": "example_value"
    },
    "add_response_headers": {
      "type": "object",
      "description": "Headers to add to the response before sending to the client",
      "additionalProperties": {
        "type": "string"
      },
      "example": "example_value"
    },
    "remove_request_headers": {
      "type": "array",
      "description": "Header names to remove from the request",
      "items": {
        "type": "string"
      },
      "example": []
    },
    "remove_response_headers": {
      "type": "array",
      "description": "Header names to remove from the response",
      "items": {
        "type": "string"
      },
      "example": []
    },
    "allow_upgrade": {
      "type": "array",
      "description": "Protocols to allow upgrade to, such as websocket",
      "items": {
        "type": "string"
      },
      "example": [
        "websocket"
      ]
    },
    "grpc": {
      "type": "boolean",
      "description": "Whether the upstream service uses gRPC",
      "default": false,
      "example": true
    },
    "enable_ipv4": {
      "type": "boolean",
      "description": "Whether to enable IPv4 DNS lookups for the upstream service",
      "example": true
    },
    "enable_ipv6": {
      "type": "boolean",
      "description": "Whether to enable IPv6 DNS lookups for the upstream service",
      "example": true
    },
    "ambassador_id": {
      "type": "array",
      "description": "List of Ambassador IDs that should apply this Mapping. Used to partition a single Kubernetes cluster among multiple Ambassador instances.",
      "items": {
        "type": "string"
      },
      "example": "500123"
    }
  }
}