{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/kubernetes-operators/main/json-schema/kubernetes-operator-schema.json",
  "title": "Kubernetes Operator Resource",
  "description": "JSON Schema for Kubernetes Operator resources including CustomResourceDefinitions (apiextensions.k8s.io/v1) and Operator Lifecycle Manager resources (CatalogSource, OperatorGroup, Subscription, InstallPlan, ClusterServiceVersion from operators.coreos.com). Covers the complete data model for managing operator lifecycle on Kubernetes clusters.",
  "type": "object",
  "required": ["apiVersion", "kind", "metadata"],
  "properties": {
    "apiVersion": {
      "type": "string",
      "description": "API group and version for this operator resource.",
      "examples": [
        "apiextensions.k8s.io/v1",
        "operators.coreos.com/v1alpha1",
        "operators.coreos.com/v1"
      ]
    },
    "kind": {
      "type": "string",
      "description": "Resource type identifier.",
      "enum": [
        "CustomResourceDefinition",
        "CatalogSource",
        "OperatorGroup",
        "Subscription",
        "InstallPlan",
        "ClusterServiceVersion"
      ]
    },
    "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. For CRDs, must be {plural}.{group}.",
          "maxLength": 253
        },
        "namespace": {
          "type": "string",
          "description": "Namespace of the resource. Empty for cluster-scoped resources.",
          "maxLength": 63
        },
        "uid": {
          "type": "string",
          "format": "uuid",
          "description": "Unique identifier generated by the server."
        },
        "resourceVersion": {
          "type": "string",
          "description": "Opaque server version string 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."
        },
        "labels": {
          "type": "object",
          "description": "Key-value label pairs for selection and organization.",
          "additionalProperties": {"type": "string"}
        },
        "annotations": {
          "type": "object",
          "description": "Non-identifying metadata for tools and controllers.",
          "additionalProperties": {"type": "string"}
        }
      }
    },
    "CRDSpec": {
      "type": "object",
      "description": "Spec for a CustomResourceDefinition registering a new API resource type.",
      "required": ["group", "names", "scope", "versions"],
      "properties": {
        "group": {
          "type": "string",
          "description": "API group for the custom resource. Must be a valid DNS domain.",
          "pattern": "^[a-z][a-z0-9\\-\\.]*[a-z0-9]$",
          "examples": ["example.com", "databases.operator.io"]
        },
        "names": {
          "$ref": "#/$defs/CRDNames"
        },
        "scope": {
          "type": "string",
          "enum": ["Cluster", "Namespaced"],
          "description": "Whether instances are cluster-scoped or namespaced."
        },
        "versions": {
          "type": "array",
          "description": "API versions this CRD serves. At least one required; exactly one must be the storage version.",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/CRDVersion"
          }
        },
        "conversion": {
          "type": "object",
          "description": "Strategy for converting between CRD versions.",
          "properties": {
            "strategy": {
              "type": "string",
              "enum": ["None", "Webhook"],
              "description": "None for no conversion; Webhook for external conversion."
            },
            "webhook": {
              "type": "object",
              "description": "Webhook conversion configuration.",
              "properties": {
                "conversionReviewVersions": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "ConversionReview API versions the webhook understands."
                },
                "clientConfig": {
                  "type": "object",
                  "description": "Connection details for the webhook.",
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "description": "URL of the webhook."
                    },
                    "service": {
                      "type": "object",
                      "description": "In-cluster service reference.",
                      "required": ["name", "namespace"],
                      "properties": {
                        "name": {"type": "string", "description": "Service name."},
                        "namespace": {"type": "string", "description": "Service namespace."},
                        "port": {"type": "integer", "description": "Service port."},
                        "path": {"type": "string", "description": "Service path."}
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "CRDNames": {
      "type": "object",
      "description": "Naming configuration for the custom resource type.",
      "required": ["kind", "plural"],
      "properties": {
        "kind": {
          "type": "string",
          "description": "PascalCase kind name used in API calls and manifests.",
          "pattern": "^[A-Z][A-Za-z0-9]*$"
        },
        "plural": {
          "type": "string",
          "description": "Lowercase plural name used in REST URL paths.",
          "pattern": "^[a-z][a-z0-9]*$"
        },
        "singular": {
          "type": "string",
          "description": "Lowercase singular name for kubectl.",
          "pattern": "^[a-z][a-z0-9]*$"
        },
        "shortNames": {
          "type": "array",
          "description": "Abbreviated names for kubectl.",
          "items": {"type": "string"}
        },
        "listKind": {
          "type": "string",
          "description": "List kind name. Defaults to {kind}List."
        },
        "categories": {
          "type": "array",
          "description": "Groups for kubectl get all and similar commands.",
          "items": {"type": "string"}
        }
      }
    },
    "CRDVersion": {
      "type": "object",
      "description": "A single version of the custom resource API.",
      "required": ["name", "served", "storage"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Version name used in REST path.",
          "pattern": "^v[0-9]+(alpha[0-9]+|beta[0-9]+)?$",
          "examples": ["v1", "v1alpha1", "v1beta1"]
        },
        "served": {
          "type": "boolean",
          "description": "Whether this version is served via the REST API."
        },
        "storage": {
          "type": "boolean",
          "description": "Whether instances are stored using this version. Exactly one version must be true."
        },
        "deprecated": {
          "type": "boolean",
          "description": "Whether this version is deprecated.",
          "default": false
        },
        "deprecationWarning": {
          "type": "string",
          "description": "Custom deprecation warning message.",
          "maxLength": 256
        },
        "schema": {
          "type": "object",
          "description": "OpenAPI v3 validation schema for this version.",
          "properties": {
            "openAPIV3Schema": {
              "type": "object",
              "description": "JSON Schema-compatible OpenAPI v3 schema object."
            }
          }
        },
        "subresources": {
          "type": "object",
          "description": "Optional status and scale subresources.",
          "properties": {
            "status": {
              "type": "object",
              "description": "Enable the /status subresource for separate status updates."
            },
            "scale": {
              "type": "object",
              "description": "Enable the /scale subresource for HPA support.",
              "properties": {
                "specReplicasPath": {
                  "type": "string",
                  "description": "JSON path to the spec replicas field."
                },
                "statusReplicasPath": {
                  "type": "string",
                  "description": "JSON path to the status replicas field."
                },
                "labelSelectorPath": {
                  "type": "string",
                  "description": "JSON path to the status label selector field."
                }
              }
            }
          }
        },
        "additionalPrinterColumns": {
          "type": "array",
          "description": "Columns shown in kubectl get output.",
          "items": {
            "type": "object",
            "required": ["name", "type", "jsonPath"],
            "properties": {
              "name": {
                "type": "string",
                "description": "Column header name."
              },
              "type": {
                "type": "string",
                "enum": ["integer", "number", "string", "boolean", "date"],
                "description": "Column data type."
              },
              "jsonPath": {
                "type": "string",
                "description": "JSON path expression from the object root."
              },
              "format": {
                "type": "string",
                "description": "Optional display format (e.g. date-time)."
              },
              "description": {
                "type": "string",
                "description": "Human-readable column description."
              },
              "priority": {
                "type": "integer",
                "minimum": 0,
                "description": "Display priority. 0 always shown; >0 shown with -o wide."
              }
            }
          }
        }
      }
    },
    "CatalogSourceSpec": {
      "type": "object",
      "description": "Spec for an OLM CatalogSource pointing to an operator registry.",
      "required": ["sourceType", "displayName"],
      "properties": {
        "sourceType": {
          "type": "string",
          "enum": ["grpc", "internal", "configmap"],
          "description": "Type of catalog registry source."
        },
        "image": {
          "type": "string",
          "description": "Container image running the gRPC catalog API."
        },
        "address": {
          "type": "string",
          "description": "gRPC address of an existing catalog registry.",
          "pattern": "^[a-z0-9\\-\\.]+:[0-9]+$"
        },
        "displayName": {
          "type": "string",
          "description": "Human-readable name for the catalog.",
          "minLength": 1,
          "maxLength": 256
        },
        "publisher": {
          "type": "string",
          "description": "Name of the organization publishing this catalog."
        },
        "description": {
          "type": "string",
          "description": "Description of the catalog contents."
        },
        "updateStrategy": {
          "type": "object",
          "description": "How frequently the catalog image is polled for updates.",
          "properties": {
            "registryPoll": {
              "type": "object",
              "properties": {
                "interval": {
                  "type": "string",
                  "description": "Polling interval as a duration string.",
                  "examples": ["10m", "1h", "24h"],
                  "pattern": "^[0-9]+(s|m|h)$"
                }
              }
            }
          }
        }
      }
    },
    "OperatorGroupSpec": {
      "type": "object",
      "description": "Spec for an OLM OperatorGroup defining namespace watch scope for operators.",
      "properties": {
        "targetNamespaces": {
          "type": "array",
          "description": "Namespaces operators in this group may watch. Empty means all namespaces.",
          "items": {
            "type": "string",
            "description": "Namespace name.",
            "pattern": "^[a-z0-9][a-z0-9\\-]*[a-z0-9]$"
          }
        },
        "selector": {
          "type": "object",
          "description": "Label selector for dynamically resolving target namespaces.",
          "properties": {
            "matchLabels": {
              "type": "object",
              "additionalProperties": {"type": "string"}
            }
          }
        }
      }
    },
    "SubscriptionSpec": {
      "type": "object",
      "description": "Spec for an OLM Subscription declaring intent to install and keep current an operator.",
      "required": ["name", "source", "sourceNamespace"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Operator package name in the catalog.",
          "minLength": 1
        },
        "source": {
          "type": "string",
          "description": "Name of the CatalogSource to use."
        },
        "sourceNamespace": {
          "type": "string",
          "description": "Namespace of the CatalogSource."
        },
        "channel": {
          "type": "string",
          "description": "Channel in the operator package to subscribe to.",
          "examples": ["stable", "alpha", "fast", "candidate"]
        },
        "startingCSV": {
          "type": "string",
          "description": "Specific CSV version to begin the subscription at. Example: my-operator.v1.2.3."
        },
        "installPlanApproval": {
          "type": "string",
          "enum": ["Automatic", "Manual"],
          "description": "Whether InstallPlans are approved automatically or require manual approval.",
          "default": "Automatic"
        },
        "config": {
          "type": "object",
          "description": "Configuration overrides applied to the operator's deployment.",
          "properties": {
            "env": {
              "type": "array",
              "description": "Environment variables to add to the operator's deployment.",
              "items": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": {"type": "string"},
                  "value": {"type": "string"}
                }
              }
            },
            "resources": {
              "type": "object",
              "description": "Resource requests and limits for the operator deployment."
            }
          }
        }
      }
    },
    "InstallPlanSpec": {
      "type": "object",
      "description": "Spec for an OLM InstallPlan listing resources to be created during operator installation.",
      "required": ["clusterServiceVersionNames", "approval", "approved"],
      "properties": {
        "clusterServiceVersionNames": {
          "type": "array",
          "description": "List of CSV names to be installed by this plan.",
          "items": {
            "type": "string",
            "description": "CSV name in {package}.{version} format."
          }
        },
        "approval": {
          "type": "string",
          "enum": ["Automatic", "Manual"],
          "description": "Approval mode for this InstallPlan."
        },
        "approved": {
          "type": "boolean",
          "description": "Whether this plan has been approved. Set to true to approve a Manual plan."
        }
      }
    },
    "CSVSpec": {
      "type": "object",
      "description": "Spec for a ClusterServiceVersion representing an installed operator version.",
      "required": ["displayName", "install"],
      "properties": {
        "displayName": {
          "type": "string",
          "description": "Human-readable operator name.",
          "minLength": 1
        },
        "description": {
          "type": "string",
          "description": "Markdown description of the operator."
        },
        "version": {
          "type": "string",
          "description": "Semantic version of the operator.",
          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+([-+][a-zA-Z0-9\\.]+)?$",
          "examples": ["1.0.0", "2.3.1-beta.1"]
        },
        "maturity": {
          "type": "string",
          "enum": ["alpha", "beta", "stable"],
          "description": "Operator maturity level."
        },
        "replaces": {
          "type": "string",
          "description": "CSV name that this version replaces in the upgrade graph."
        },
        "skips": {
          "type": "array",
          "description": "CSV versions that are skipped in the upgrade graph.",
          "items": {"type": "string"}
        },
        "installModes": {
          "type": "array",
          "description": "Namespace installation modes supported by this operator.",
          "items": {
            "type": "object",
            "required": ["type", "supported"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["OwnNamespace", "SingleNamespace", "MultiNamespace", "AllNamespaces"],
                "description": "Install mode type."
              },
              "supported": {
                "type": "boolean",
                "description": "Whether this mode is supported."
              }
            }
          }
        },
        "install": {
          "type": "object",
          "description": "Install strategy for the operator deployment.",
          "required": ["strategy"],
          "properties": {
            "strategy": {
              "type": "string",
              "enum": ["deployment"],
              "description": "Install strategy type. Only 'deployment' is supported."
            },
            "spec": {
              "type": "object",
              "description": "Deployment and RBAC specification.",
              "properties": {
                "deployments": {
                  "type": "array",
                  "description": "Deployment specs for operator pods.",
                  "items": {
                    "type": "object",
                    "required": ["name", "spec"],
                    "properties": {
                      "name": {"type": "string", "description": "Deployment name."},
                      "spec": {"type": "object", "description": "Kubernetes Deployment spec."}
                    }
                  }
                },
                "permissions": {
                  "type": "array",
                  "description": "Namespace-scoped RBAC rules for the operator.",
                  "items": {"$ref": "#/$defs/StrategyPermission"}
                },
                "clusterPermissions": {
                  "type": "array",
                  "description": "Cluster-scoped RBAC rules for the operator.",
                  "items": {"$ref": "#/$defs/StrategyPermission"}
                }
              }
            }
          }
        },
        "customresourcedefinitions": {
          "type": "object",
          "description": "CRDs owned and required by this operator.",
          "properties": {
            "owned": {
              "type": "array",
              "description": "CRDs this operator manages.",
              "items": {"$ref": "#/$defs/CRDDescription"}
            },
            "required": {
              "type": "array",
              "description": "CRDs this operator depends on.",
              "items": {"$ref": "#/$defs/CRDDescription"}
            }
          }
        },
        "minKubeVersion": {
          "type": "string",
          "description": "Minimum Kubernetes version required.",
          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
        }
      }
    },
    "StrategyPermission": {
      "type": "object",
      "description": "RBAC permission set for an operator service account.",
      "required": ["serviceAccountName", "rules"],
      "properties": {
        "serviceAccountName": {
          "type": "string",
          "description": "Service account name to bind the rules to."
        },
        "rules": {
          "type": "array",
          "description": "Policy rules granting access to API resources.",
          "items": {
            "type": "object",
            "properties": {
              "apiGroups": {
                "type": "array",
                "items": {"type": "string"},
                "description": "API groups the rule applies to. Use '' for core group."
              },
              "resources": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Resource types the rule applies to."
              },
              "verbs": {
                "type": "array",
                "items": {"type": "string"},
                "description": "HTTP verbs allowed. Examples: get, list, watch, create, update, patch, delete."
              }
            }
          }
        }
      }
    },
    "CRDDescription": {
      "type": "object",
      "description": "Description of a CRD owned or required by a ClusterServiceVersion.",
      "required": ["name", "version", "kind"],
      "properties": {
        "name": {
          "type": "string",
          "description": "CRD name in {plural}.{group} format."
        },
        "version": {
          "type": "string",
          "description": "API version for this CRD."
        },
        "kind": {
          "type": "string",
          "description": "Kind of the custom resource."
        },
        "displayName": {
          "type": "string",
          "description": "Human-readable display name."
        },
        "description": {
          "type": "string",
          "description": "Description of what this CRD represents."
        },
        "resources": {
          "type": "array",
          "description": "Kubernetes resources managed by this CRD.",
          "items": {
            "type": "object",
            "properties": {
              "version": {"type": "string"},
              "kind": {"type": "string"},
              "name": {"type": "string"}
            }
          }
        },
        "specDescriptors": {
          "type": "array",
          "description": "Descriptors for spec fields shown in the operator UI.",
          "items": {
            "type": "object",
            "properties": {
              "displayName": {"type": "string"},
              "description": {"type": "string"},
              "path": {"type": "string", "description": "JSON path to the field."},
              "x-descriptors": {
                "type": "array",
                "items": {"type": "string"},
                "description": "UI descriptor hints."
              }
            }
          }
        },
        "statusDescriptors": {
          "type": "array",
          "description": "Descriptors for status fields shown in the operator UI.",
          "items": {
            "type": "object",
            "properties": {
              "displayName": {"type": "string"},
              "description": {"type": "string"},
              "path": {"type": "string"},
              "x-descriptors": {
                "type": "array",
                "items": {"type": "string"}
              }
            }
          }
        }
      }
    },
    "Condition": {
      "type": "object",
      "description": "A condition expressing an aspect of current resource state.",
      "required": ["type", "status"],
      "properties": {
        "type": {
          "type": "string",
          "description": "Type of condition."
        },
        "status": {
          "type": "string",
          "enum": ["True", "False", "Unknown"],
          "description": "Status of the condition."
        },
        "reason": {
          "type": "string",
          "description": "Machine-readable reason."
        },
        "message": {
          "type": "string",
          "description": "Human-readable details."
        },
        "lastTransitionTime": {
          "type": "string",
          "format": "date-time",
          "description": "Last transition timestamp."
        },
        "observedGeneration": {
          "type": "integer",
          "description": "Generation at which the condition was last observed."
        }
      }
    }
  }
}