{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/kubernetes-services/main/json-schema/kubernetes-services-schema.json",
  "title": "Kubernetes Services Resource",
  "description": "JSON Schema for Kubernetes networking resources including Service, Ingress, IngressClass, EndpointSlice, NetworkPolicy, GatewayClass, Gateway, HTTPRoute, and GRPCRoute. Covers the core v1, networking.k8s.io/v1, discovery.k8s.io/v1, and gateway.networking.k8s.io/v1 API groups.",
  "type": "object",
  "required": ["apiVersion", "kind", "metadata"],
  "properties": {
    "apiVersion": {
      "type": "string",
      "description": "API group and version for this resource.",
      "examples": [
        "v1",
        "networking.k8s.io/v1",
        "discovery.k8s.io/v1",
        "gateway.networking.k8s.io/v1"
      ]
    },
    "kind": {
      "type": "string",
      "description": "Resource type identifier.",
      "enum": [
        "Service",
        "Endpoints",
        "EndpointSlice",
        "Ingress",
        "IngressClass",
        "NetworkPolicy",
        "GatewayClass",
        "Gateway",
        "HTTPRoute",
        "GRPCRoute",
        "TCPRoute",
        "TLSRoute"
      ]
    },
    "metadata": {
      "$ref": "#/$defs/ObjectMeta"
    },
    "spec": {
      "type": "object",
      "description": "Desired state specification. Structure varies by resource kind."
    },
    "status": {
      "type": "object",
      "description": "Observed status. Populated by the system."
    }
  },
  "$defs": {
    "ObjectMeta": {
      "type": "object",
      "description": "Standard Kubernetes object metadata present on all resources.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Unique resource name within the namespace.",
          "maxLength": 253,
          "pattern": "^[a-z0-9][a-z0-9\\-\\.]*[a-z0-9]$"
        },
        "namespace": {
          "type": "string",
          "description": "Namespace scoping the resource. Empty for cluster-scoped resources.",
          "maxLength": 63,
          "pattern": "^[a-z0-9][a-z0-9\\-]*[a-z0-9]$"
        },
        "uid": {
          "type": "string",
          "format": "uuid",
          "description": "Unique identifier generated by the server."
        },
        "resourceVersion": {
          "type": "string",
          "description": "Opaque server-side version string used for optimistic concurrency."
        },
        "generation": {
          "type": "integer",
          "minimum": 0,
          "description": "Sequence number incremented on spec changes."
        },
        "creationTimestamp": {
          "type": "string",
          "format": "date-time",
          "description": "RFC 3339 timestamp of resource creation."
        },
        "deletionTimestamp": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp when the resource is scheduled for deletion."
        },
        "labels": {
          "type": "object",
          "description": "Key-value label pairs for identification and selection.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "annotations": {
          "type": "object",
          "description": "Non-identifying metadata used by controllers and tools.",
          "additionalProperties": {
            "type": "string"
          }
        }
      }
    },
    "ServicePort": {
      "type": "object",
      "description": "A port mapping in a Service, translating from a service port to a pod target port.",
      "required": ["port"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Port name, required for multi-port services.",
          "maxLength": 15,
          "pattern": "^[a-z][a-z0-9\\-]*[a-z0-9]?$"
        },
        "port": {
          "type": "integer",
          "minimum": 1,
          "maximum": 65535,
          "description": "Port number the Service exposes."
        },
        "targetPort": {
          "description": "Port number or named port on the pod.",
          "oneOf": [
            {"type": "integer", "minimum": 1, "maximum": 65535},
            {"type": "string"}
          ]
        },
        "protocol": {
          "type": "string",
          "enum": ["TCP", "UDP", "SCTP"],
          "description": "Network protocol. Defaults to TCP.",
          "default": "TCP"
        },
        "nodePort": {
          "type": "integer",
          "minimum": 30000,
          "maximum": 32767,
          "description": "Node-level port for NodePort and LoadBalancer service types."
        },
        "appProtocol": {
          "type": "string",
          "description": "Application-layer protocol hint. Examples: http, https, h2c."
        }
      }
    },
    "ServiceSpec": {
      "type": "object",
      "description": "Desired state for a Service resource, defining port mappings, pod selector, and exposure type.",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["ClusterIP", "NodePort", "LoadBalancer", "ExternalName"],
          "description": "Service type controlling how the service is exposed.",
          "default": "ClusterIP"
        },
        "selector": {
          "type": "object",
          "description": "Label selector for pods receiving traffic from this service.",
          "additionalProperties": {"type": "string"}
        },
        "ports": {
          "type": "array",
          "description": "List of port mappings exposed by the service.",
          "items": {"$ref": "#/$defs/ServicePort"}
        },
        "clusterIP": {
          "type": "string",
          "description": "Internal cluster IP. 'None' for headless services."
        },
        "externalName": {
          "type": "string",
          "description": "External DNS name. Only for ExternalName type services."
        },
        "externalTrafficPolicy": {
          "type": "string",
          "enum": ["Cluster", "Local"],
          "description": "Traffic routing policy for external requests."
        },
        "sessionAffinity": {
          "type": "string",
          "enum": ["None", "ClientIP"],
          "description": "Session affinity mode.",
          "default": "None"
        },
        "loadBalancerSourceRanges": {
          "type": "array",
          "description": "CIDR ranges allowed to reach the load balancer.",
          "items": {"type": "string"}
        },
        "ipFamilyPolicy": {
          "type": "string",
          "enum": ["SingleStack", "PreferDualStack", "RequireDualStack"],
          "description": "Dual-stack IP family policy."
        }
      }
    },
    "IngressSpec": {
      "type": "object",
      "description": "Desired state for an Ingress resource defining HTTP/HTTPS routing rules.",
      "properties": {
        "ingressClassName": {
          "type": "string",
          "description": "Name of the IngressClass selecting the controller."
        },
        "defaultBackend": {
          "$ref": "#/$defs/IngressBackend"
        },
        "tls": {
          "type": "array",
          "description": "TLS configuration for HTTPS termination.",
          "items": {
            "type": "object",
            "properties": {
              "hosts": {
                "type": "array",
                "description": "Hostnames covered by the TLS certificate.",
                "items": {"type": "string"}
              },
              "secretName": {
                "type": "string",
                "description": "Secret containing the TLS certificate and key."
              }
            }
          }
        },
        "rules": {
          "type": "array",
          "description": "List of host-based routing rules.",
          "items": {
            "type": "object",
            "properties": {
              "host": {
                "type": "string",
                "description": "FQDN to match for this rule."
              },
              "http": {
                "type": "object",
                "required": ["paths"],
                "properties": {
                  "paths": {
                    "type": "array",
                    "description": "Path-to-backend mappings.",
                    "minItems": 1,
                    "items": {
                      "type": "object",
                      "required": ["pathType", "backend"],
                      "properties": {
                        "path": {
                          "type": "string",
                          "description": "URL path to match.",
                          "pattern": "^/"
                        },
                        "pathType": {
                          "type": "string",
                          "enum": ["Exact", "Prefix", "ImplementationSpecific"],
                          "description": "Path matching strategy."
                        },
                        "backend": {
                          "$ref": "#/$defs/IngressBackend"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "IngressBackend": {
      "type": "object",
      "description": "Backend service or resource reference for Ingress routing.",
      "properties": {
        "service": {
          "type": "object",
          "description": "Service backend reference.",
          "required": ["name", "port"],
          "properties": {
            "name": {
              "type": "string",
              "description": "Name of the backend Service."
            },
            "port": {
              "type": "object",
              "description": "Port on the backend Service.",
              "properties": {
                "number": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 65535,
                  "description": "Numeric port number."
                },
                "name": {
                  "type": "string",
                  "description": "Named port defined in the Service."
                }
              }
            }
          }
        }
      }
    },
    "NetworkPolicySpec": {
      "type": "object",
      "description": "Desired state for a NetworkPolicy defining which pods can communicate.",
      "required": ["podSelector"],
      "properties": {
        "podSelector": {
          "$ref": "#/$defs/LabelSelector"
        },
        "policyTypes": {
          "type": "array",
          "description": "Whether ingress, egress, or both policy types apply.",
          "items": {
            "type": "string",
            "enum": ["Ingress", "Egress"]
          }
        },
        "ingress": {
          "type": "array",
          "description": "Allowed inbound traffic rules.",
          "items": {
            "type": "object",
            "properties": {
              "from": {
                "type": "array",
                "description": "Allowed traffic sources.",
                "items": {"$ref": "#/$defs/NetworkPolicyPeer"}
              },
              "ports": {
                "type": "array",
                "description": "Ports on which inbound traffic is allowed.",
                "items": {"$ref": "#/$defs/NetworkPolicyPort"}
              }
            }
          }
        },
        "egress": {
          "type": "array",
          "description": "Allowed outbound traffic rules.",
          "items": {
            "type": "object",
            "properties": {
              "to": {
                "type": "array",
                "description": "Allowed traffic destinations.",
                "items": {"$ref": "#/$defs/NetworkPolicyPeer"}
              },
              "ports": {
                "type": "array",
                "description": "Ports to which outbound traffic is allowed.",
                "items": {"$ref": "#/$defs/NetworkPolicyPort"}
              }
            }
          }
        }
      }
    },
    "NetworkPolicyPeer": {
      "type": "object",
      "description": "Traffic source or destination specification in a network policy rule.",
      "properties": {
        "podSelector": {
          "$ref": "#/$defs/LabelSelector"
        },
        "namespaceSelector": {
          "$ref": "#/$defs/LabelSelector"
        },
        "ipBlock": {
          "type": "object",
          "description": "CIDR-based peer for traffic from/to IP ranges.",
          "required": ["cidr"],
          "properties": {
            "cidr": {
              "type": "string",
              "description": "CIDR range to match."
            },
            "except": {
              "type": "array",
              "description": "CIDR ranges to exclude from the block.",
              "items": {"type": "string"}
            }
          }
        }
      }
    },
    "NetworkPolicyPort": {
      "type": "object",
      "description": "Port and protocol specification in a network policy rule.",
      "properties": {
        "protocol": {
          "type": "string",
          "enum": ["TCP", "UDP", "SCTP"],
          "description": "Network protocol. Defaults to TCP."
        },
        "port": {
          "description": "Port number or named port to match.",
          "oneOf": [
            {"type": "integer", "minimum": 1, "maximum": 65535},
            {"type": "string"}
          ]
        },
        "endPort": {
          "type": "integer",
          "minimum": 1,
          "maximum": 65535,
          "description": "End of a port range when specifying port ranges."
        }
      }
    },
    "EndpointSliceSpec": {
      "type": "object",
      "description": "Data fields for an EndpointSlice resource tracking pod IPs and readiness.",
      "required": ["addressType", "endpoints"],
      "properties": {
        "addressType": {
          "type": "string",
          "enum": ["IPv4", "IPv6"],
          "description": "IP address type of all endpoints in this slice."
        },
        "endpoints": {
          "type": "array",
          "description": "List of individual endpoint entries.",
          "maxItems": 1000,
          "items": {
            "type": "object",
            "required": ["addresses"],
            "properties": {
              "addresses": {
                "type": "array",
                "description": "IP addresses for this endpoint.",
                "minItems": 1,
                "maxItems": 100,
                "items": {"type": "string", "format": "ipv4"}
              },
              "conditions": {
                "type": "object",
                "description": "Readiness conditions for this endpoint.",
                "properties": {
                  "ready": {
                    "type": "boolean",
                    "description": "Whether this endpoint is ready to accept traffic."
                  },
                  "serving": {
                    "type": "boolean",
                    "description": "Whether this endpoint can serve requests (even while terminating)."
                  },
                  "terminating": {
                    "type": "boolean",
                    "description": "Whether this endpoint is gracefully terminating."
                  }
                }
              },
              "nodeName": {
                "type": "string",
                "description": "Node hosting this endpoint."
              },
              "zone": {
                "type": "string",
                "description": "Availability zone of this endpoint."
              },
              "hostname": {
                "type": "string",
                "description": "DNS hostname for per-pod DNS records in headless services."
              }
            }
          }
        },
        "ports": {
          "type": "array",
          "description": "Network ports shared by all endpoints in this slice.",
          "maxItems": 100,
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Port name matching the Service port name."
              },
              "port": {
                "type": "integer",
                "minimum": 1,
                "maximum": 65535,
                "description": "Port number."
              },
              "protocol": {
                "type": "string",
                "enum": ["TCP", "UDP", "SCTP"],
                "description": "Network protocol."
              },
              "appProtocol": {
                "type": "string",
                "description": "Application-layer protocol hint."
              }
            }
          }
        }
      }
    },
    "GatewaySpec": {
      "type": "object",
      "description": "Desired state for a Gateway API Gateway resource defining traffic listeners.",
      "required": ["gatewayClassName", "listeners"],
      "properties": {
        "gatewayClassName": {
          "type": "string",
          "description": "Name of the GatewayClass this Gateway instantiates."
        },
        "listeners": {
          "type": "array",
          "description": "Network listeners accepting traffic for this Gateway.",
          "minItems": 1,
          "items": {
            "type": "object",
            "required": ["name", "protocol", "port"],
            "properties": {
              "name": {
                "type": "string",
                "description": "Unique name for this listener.",
                "maxLength": 253
              },
              "protocol": {
                "type": "string",
                "enum": ["HTTP", "HTTPS", "TLS", "TCP", "UDP"],
                "description": "Network protocol this listener accepts."
              },
              "port": {
                "type": "integer",
                "minimum": 1,
                "maximum": 65535,
                "description": "Port number for this listener."
              },
              "hostname": {
                "type": "string",
                "description": "Hostname this listener matches. Supports wildcard prefix."
              },
              "allowedRoutes": {
                "type": "object",
                "description": "Controls which routes can attach to this listener.",
                "properties": {
                  "namespaces": {
                    "type": "object",
                    "properties": {
                      "from": {
                        "type": "string",
                        "enum": ["All", "Same", "Selector"],
                        "description": "Namespace scope for route attachment."
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "HTTPRouteSpec": {
      "type": "object",
      "description": "Desired state for an HTTPRoute defining HTTP traffic routing rules.",
      "properties": {
        "parentRefs": {
          "type": "array",
          "description": "Gateway listeners this route attaches to.",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Gateway name."
              },
              "namespace": {
                "type": "string",
                "description": "Gateway namespace."
              },
              "sectionName": {
                "type": "string",
                "description": "Specific listener name on the Gateway."
              }
            }
          }
        },
        "hostnames": {
          "type": "array",
          "description": "Hostnames to match for routing. Supports wildcard prefix.",
          "items": {"type": "string"}
        },
        "rules": {
          "type": "array",
          "description": "HTTP routing rules evaluated in order.",
          "items": {
            "type": "object",
            "properties": {
              "matches": {
                "type": "array",
                "description": "HTTP match conditions (OR'd between items).",
                "items": {
                  "type": "object",
                  "properties": {
                    "path": {
                      "type": "object",
                      "description": "Path match condition.",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": ["Exact", "PathPrefix", "RegularExpression"]
                        },
                        "value": {"type": "string"}
                      }
                    },
                    "headers": {
                      "type": "array",
                      "description": "Header match conditions (AND'd).",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {"type": "string"},
                          "value": {"type": "string"},
                          "type": {"type": "string", "enum": ["Exact", "RegularExpression"]}
                        }
                      }
                    },
                    "method": {
                      "type": "string",
                      "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"],
                      "description": "HTTP method to match."
                    }
                  }
                }
              },
              "backendRefs": {
                "type": "array",
                "description": "Backend services to forward traffic to.",
                "items": {
                  "type": "object",
                  "required": ["name", "port"],
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "Backend Service name."
                    },
                    "namespace": {
                      "type": "string",
                      "description": "Backend Service namespace."
                    },
                    "port": {
                      "type": "integer",
                      "minimum": 1,
                      "maximum": 65535,
                      "description": "Backend Service port."
                    },
                    "weight": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 1000000,
                      "description": "Relative traffic weight for proportional routing."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "LabelSelector": {
      "type": "object",
      "description": "Label selector used in NetworkPolicy peer matching and other selection contexts.",
      "properties": {
        "matchLabels": {
          "type": "object",
          "description": "Exact label key-value pairs that must match.",
          "additionalProperties": {"type": "string"}
        },
        "matchExpressions": {
          "type": "array",
          "description": "Set-based requirements.",
          "items": {
            "type": "object",
            "required": ["key", "operator"],
            "properties": {
              "key": {"type": "string", "description": "Label key."},
              "operator": {
                "type": "string",
                "enum": ["In", "NotIn", "Exists", "DoesNotExist"],
                "description": "Relationship operator."
              },
              "values": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Values for In/NotIn operators."
              }
            }
          }
        }
      }
    }
  }
}