{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://fuegoapp.dev/schemas/query-builder.schema.json",
    "title": "Fuego QueryBuilder — classic query or pipeline",
    "description": "Unified schema accepted by Fuego's query builder. Validates either a classic field/op/value query (produced by Query.serialize()) or a pipeline query (ordered list of processing stages).",
    "oneOf": [
        { "$ref": "#/$defs/classicQuery" },
        { "$ref": "#/$defs/pipeline" }
    ],
    "$defs": {
        "classicQuery": {
            "type": "object",
            "title": "Classic query",
            "description": "Plain JSON object accepted by Query.fromJSON() and produced by Query.serialize()/toJSON().",
            "additionalProperties": false,
            "properties": {
                "mode": {
                    "type": "string",
                    "enum": ["classic"],
                    "default": "classic"
                },
                "offset": {
                    "type": "integer",
                    "minimum": 0
                },
                "limit": {
                    "type": "integer",
                    "minimum": -1,
                    "description": "Use -1 to represent no limit."
                },
                "limitToLast": {
                    "type": "boolean",
                    "default": false
                },
                "orders": {
                    "type": "array",
                    "items": { "$ref": "#/$defs/order" }
                },
                "filters": {
                    "type": "array",
                    "items": { "$ref": "#/$defs/filter" }
                },
                "collectionPath": {
                    "type": "string",
                    "minLength": 1,
                    "pattern": "^[^/]+(/[^/]+/[^/]+)*$",
                    "description": "Relative collection path. Must contain an odd number of path segments, e.g. users or users/{userId}/orders."
                },
                "collectionGroup": {
                    "type": "boolean",
                    "default": false
                },
                "realtime": {
                    "type": "boolean",
                    "default": true
                },
                "readTime": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Point-in-time recovery timestamp in ISO-8601 format."
                },
                "loadDiffs": {
                    "type": "boolean",
                    "description": "Meaningful only when readTime is set."
                },
                "anonymize": {
                    "type": "boolean",
                    "default": false,
                    "description": "Mask sensitive values in returned documents (server-side, read-only view)."
                },
                "selection": {
                    "type": "array",
                    "minItems": 1,
                    "uniqueItems": true,
                    "items": { "$ref": "#/$defs/fieldPath" }
                },
                "startAt": { "$ref": "#/$defs/cursor" },
                "startAfter": { "$ref": "#/$defs/cursor" },
                "endAt": { "$ref": "#/$defs/cursor" },
                "endBefore": { "$ref": "#/$defs/cursor" },
                "findNearest": { "$ref": "#/$defs/findNearest" }
            },
            "allOf": [
                {
                    "not": { "required": ["startAt", "startAfter"] },
                    "description": "Only one start cursor can be active at a time."
                },
                {
                    "not": { "required": ["endAt", "endBefore"] },
                    "description": "Only one end cursor can be active at a time."
                }
            ]
        },

        "pipeline": {
            "type": "object",
            "title": "Pipeline query",
            "description": "An ordered list of processing stages expressing a Firestore Pipeline query.",
            "additionalProperties": false,
            "required": ["stages"],
            "properties": {
                "mode": {
                    "type": "string",
                    "enum": ["pipeline"],
                    "default": "pipeline"
                },
                "stages": {
                    "type": "array",
                    "minItems": 1,
                    "items": { "$ref": "#/$defs/stage" }
                },
                "realtime": {
                    "type": "boolean",
                    "default": true
                },
                "readTime": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Point-in-time recovery timestamp in ISO-8601 format."
                },
                "loadDiffs": {
                    "type": "boolean",
                    "description": "Meaningful only when readTime is set."
                },
                "anonymize": {
                    "type": "boolean",
                    "default": false,
                    "description": "Mask sensitive values in returned documents (server-side, read-only view)."
                }
            }
        },

        "fieldPath": {
            "type": "string",
            "minLength": 1
        },

        "orderDirection": {
            "type": "string",
            "enum": ["asc", "desc"]
        },

        "queryValue": {
            "anyOf": [
                { "type": "string" },
                { "type": "number" },
                { "type": "boolean" },
                { "type": "null" },
                { "$ref": "#/$defs/timestampValue" },
                { "$ref": "#/$defs/geopointValue" },
                { "$ref": "#/$defs/referenceValue" },
                { "$ref": "#/$defs/bytesValue" },
                { "$ref": "#/$defs/vectorValue" },
                { "$ref": "#/$defs/vector32Value" },
                { "$ref": "#/$defs/nanValue" },
                { "$ref": "#/$defs/infinityValue" },
                { "$ref": "#/$defs/placeholderValue" },
                { "$ref": "#/$defs/arrayValue" },
                { "$ref": "#/$defs/mapValue" }
            ]
        },

        "timestampValue": {
            "type": "object",
            "additionalProperties": false,
            "required": ["__time__"],
            "properties": {
                "__time__": {
                    "type": "string",
                    "format": "date-time"
                }
            }
        },

        "geopointValue": {
            "type": "object",
            "additionalProperties": false,
            "required": ["__lat__", "__lng__"],
            "properties": {
                "__lat__": { "type": "number", "minimum": -90, "maximum": 90 },
                "__lng__": { "type": "number", "minimum": -180, "maximum": 180 }
            }
        },

        "referenceValue": {
            "type": "object",
            "additionalProperties": false,
            "required": ["__ref__"],
            "properties": {
                "__ref__": { "type": "string", "minLength": 1 }
            }
        },

        "bytesValue": {
            "type": "object",
            "additionalProperties": false,
            "required": ["__bytes__"],
            "properties": {
                "__bytes__": { "type": "string" },
                "__size__": { "type": "integer", "minimum": -1 },
                "__contentType__": { "type": "string" },
                "__fileType__": { "type": "string" }
            }
        },

        "vectorValue": {
            "type": "object",
            "additionalProperties": false,
            "required": ["__vector__"],
            "properties": {
                "__vector__": { "type": "array", "items": { "type": "number" } },
                "__size__": { "type": "integer", "minimum": 0 }
            }
        },

        "vector32Value": {
            "type": "object",
            "additionalProperties": false,
            "required": ["__vector32__"],
            "properties": {
                "__vector32__": { "type": "array", "items": { "type": "number" } },
                "__size__": { "type": "integer", "minimum": 0 }
            }
        },

        "nanValue": {
            "type": "object",
            "additionalProperties": false,
            "required": ["__nan__"],
            "properties": {
                "__nan__": { "const": true }
            }
        },

        "infinityValue": {
            "type": "object",
            "additionalProperties": false,
            "required": ["__infinity__"],
            "properties": {
                "__infinity__": {
                    "oneOf": [{ "const": true }, { "enum": [1, -1] }]
                }
            }
        },

        "placeholderValue": {
            "type": "object",
            "additionalProperties": false,
            "required": ["__placeholder__"],
            "properties": {
                "__placeholder__": { "type": "string", "minLength": 1 },
                "custom": { "type": "boolean" },
                "format": {
                    "type": "string",
                    "enum": ["ISO", "ISONano", "DateTime", "DateTimeWithoutSeconds", "Date", "Unix", "UnixMilli", "FuegoJSON", "Native"]
                }
            }
        },

        "arrayValue": {
            "type": "array",
            "items": { "$ref": "#/$defs/queryValue" }
        },

        "mapValue": {
            "type": "object",
            "not": {
                "anyOf": [
                    { "required": ["__time__"] },
                    { "required": ["__lat__"] },
                    { "required": ["__lng__"] },
                    { "required": ["__ref__"] },
                    { "required": ["__bytes__"] },
                    { "required": ["__vector__"] },
                    { "required": ["__vector32__"] },
                    { "required": ["__nan__"] },
                    { "required": ["__infinity__"] },
                    { "required": ["__placeholder__"] }
                ]
            },
            "additionalProperties": { "$ref": "#/$defs/queryValue" }
        },

        "operator": {
            "type": "string",
            "enum": [
                "starts-with",
                "between",
                "==",
                "!=",
                "<",
                "<=",
                ">",
                ">=",
                "in",
                "not-in",
                "array-contains",
                "array-contains-any"
            ]
        },

        "order": {
            "type": "object",
            "additionalProperties": false,
            "required": ["field", "dir"],
            "properties": {
                "field": { "$ref": "#/$defs/fieldPath" },
                "dir": { "$ref": "#/$defs/orderDirection" }
            }
        },

        "filter": {
            "oneOf": [
                { "$ref": "#/$defs/filterConstraint" },
                { "$ref": "#/$defs/filtersAnd" },
                { "$ref": "#/$defs/filtersOr" }
            ]
        },

        "filterConstraint": {
            "type": "object",
            "additionalProperties": false,
            "required": ["field", "op", "value"],
            "properties": {
                "field": { "$ref": "#/$defs/fieldPath" },
                "op": { "$ref": "#/$defs/operator" },
                "value": { "$ref": "#/$defs/queryValue" }
            },
            "allOf": [
                {
                    "if": {
                        "properties": { "op": { "enum": ["in", "not-in", "array-contains-any"] } },
                        "required": ["op"]
                    },
                    "then": {
                        "properties": {
                            "value": {
                                "type": "array",
                                "minItems": 1,
                                "items": { "$ref": "#/$defs/queryValue" }
                            }
                        }
                    }
                },
                {
                    "if": {
                        "properties": { "op": { "const": "starts-with" } },
                        "required": ["op"]
                    },
                    "then": {
                        "properties": { "value": { "type": "string" } }
                    }
                },
                {
                    "if": {
                        "properties": { "op": { "const": "between" } },
                        "required": ["op"]
                    },
                    "then": {
                        "properties": {
                            "value": {
                                "type": "array",
                                "minItems": 2,
                                "maxItems": 2,
                                "items": { "$ref": "#/$defs/queryValue" }
                            }
                        }
                    }
                }
            ]
        },

        "filtersAnd": {
            "type": "object",
            "additionalProperties": false,
            "required": ["and"],
            "properties": {
                "and": {
                    "type": "array",
                    "minItems": 1,
                    "items": { "$ref": "#/$defs/filter" }
                }
            }
        },

        "filtersOr": {
            "type": "object",
            "additionalProperties": false,
            "required": ["or"],
            "properties": {
                "or": {
                    "type": "array",
                    "minItems": 1,
                    "items": { "$ref": "#/$defs/filter" }
                }
            }
        },

        "cursor": {
            "anyOf": [
                {
                    "type": "array",
                    "minItems": 1,
                    "items": { "$ref": "#/$defs/cursorValue" }
                },
                { "$ref": "#/$defs/referenceValue" }
            ]
        },

        "cursorValue": {
            "anyOf": [
                { "type": "string" },
                { "type": "number" },
                { "type": "boolean" },
                { "$ref": "#/$defs/timestampValue" },
                { "$ref": "#/$defs/geopointValue" },
                { "$ref": "#/$defs/referenceValue" },
                { "$ref": "#/$defs/bytesValue" }
            ]
        },

        "distanceMeasure": {
            "type": "string",
            "enum": ["cosine", "euclidean", "dot-product"]
        },

        "findNearest": {
            "type": "object",
            "additionalProperties": false,
            "required": ["field", "vector", "measure"],
            "properties": {
                "field": { "$ref": "#/$defs/fieldPath" },
                "vector": {
                    "type": "array",
                    "minItems": 1,
                    "items": { "type": "number" }
                },
                "measure": { "$ref": "#/$defs/distanceMeasure" },
                "distanceThreshold": { "type": "number" },
                "distanceResultField": { "$ref": "#/$defs/fieldPath" }
            }
        },

        "stage": {
            "description": "A single pipeline stage, keyed by its logical name. Every stage may carry an optional free-form 'options' map.",
            "oneOf": [
                {
                    "title": "collection",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["collection"],
                    "properties": {
                        "collection": {
                            "type": "string",
                            "minLength": 1,
                            "description": "Collection path, e.g. 'users' or '/users'. Wire stage name: collection."
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "collectionGroup",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["collectionGroup"],
                    "properties": {
                        "collectionGroup": {
                            "description": "Collection group id, optionally scoped to an ancestor path. Wire stage name: collection_group.",
                            "oneOf": [
                                { "type": "string", "minLength": 1 },
                                {
                                    "type": "object",
                                    "additionalProperties": false,
                                    "required": ["collectionId"],
                                    "properties": {
                                        "collectionId": { "type": "string", "minLength": 1 },
                                        "ancestor": { "type": "string", "minLength": 1 }
                                    }
                                }
                            ]
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "database",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["database"],
                    "properties": {
                        "database": {
                            "type": "object",
                            "additionalProperties": false,
                            "description": "All documents in the database. Wire stage name: database."
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "documents",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["documents"],
                    "properties": {
                        "documents": {
                            "type": "array",
                            "minItems": 1,
                            "description": "Explicit document references. Wire stage name: documents.",
                            "items": {
                                "oneOf": [{ "type": "string", "minLength": 1 }, { "$ref": "#/$defs/referenceValue" }]
                            }
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "literals",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["literals"],
                    "properties": {
                        "literals": {
                            "type": "array",
                            "minItems": 1,
                            "description": "Fixed set of predefined documents. Wire stage name: literals.",
                            "items": {
                                "type": "object",
                                "additionalProperties": { "$ref": "#/$defs/queryValue" }
                            }
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "subcollection",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["subcollection"],
                    "properties": {
                        "subcollection": {
                            "type": "string",
                            "minLength": 1,
                            "description": "Subcollection path used as a subquery source within a parent pipeline. Wire stage name: subcollection."
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "where",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["where"],
                    "properties": {
                        "where": { "$ref": "#/$defs/booleanExpression" },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "select",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["select"],
                    "properties": {
                        "select": {
                            "type": "array",
                            "minItems": 1,
                            "items": { "$ref": "#/$defs/selectable" }
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "addFields",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["addFields"],
                    "properties": {
                        "addFields": {
                            "type": "array",
                            "minItems": 1,
                            "description": "Adds/overwrites fields computed from expressions. Wire stage name: add_fields.",
                            "items": { "$ref": "#/$defs/aliasedExpression" }
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "removeFields",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["removeFields"],
                    "properties": {
                        "removeFields": {
                            "type": "array",
                            "minItems": 1,
                            "description": "Field paths to remove. Wire stage name: remove_fields.",
                            "items": { "$ref": "#/$defs/fieldPath" }
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "distinct",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["distinct"],
                    "properties": {
                        "distinct": {
                            "type": "array",
                            "description": "Fields determining distinctness. Empty array means the whole document. Wire stage name: distinct.",
                            "items": { "$ref": "#/$defs/selectable" }
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "replaceWith",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["replaceWith"],
                    "properties": {
                        "replaceWith": {
                            "description": "Replaces the document with a nested map given by a field path or an expression. Wire stage name: replace_with.",
                            "oneOf": [{ "$ref": "#/$defs/fieldPath" }, { "$ref": "#/$defs/expression" }]
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "sort",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["sort"],
                    "properties": {
                        "sort": {
                            "type": "array",
                            "minItems": 1,
                            "items": { "$ref": "#/$defs/ordering" }
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "limit",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["limit"],
                    "properties": {
                        "limit": { "type": "integer", "minimum": 0 },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "offset",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["offset"],
                    "properties": {
                        "offset": { "type": "integer", "minimum": 0 },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "aggregate",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["aggregate"],
                    "properties": {
                        "aggregate": {
                            "type": "object",
                            "additionalProperties": false,
                            "required": ["accumulators"],
                            "properties": {
                                "accumulators": {
                                    "type": "array",
                                    "minItems": 1,
                                    "items": { "$ref": "#/$defs/aliasedAggregate" }
                                },
                                "groups": {
                                    "type": "array",
                                    "description": "Optional group-by fields or expressions.",
                                    "items": { "$ref": "#/$defs/selectable" }
                                }
                            }
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "union",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["union"],
                    "properties": {
                        "union": {
                            "$ref": "#/$defs/pipeline",
                            "description": "Another root pipeline whose documents are unioned (duplicates kept)."
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "unnest",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["unnest"],
                    "properties": {
                        "unnest": {
                            "type": "object",
                            "additionalProperties": false,
                            "required": ["field", "alias"],
                            "properties": {
                                "field": {
                                    "oneOf": [{ "$ref": "#/$defs/fieldPath" }, { "$ref": "#/$defs/expression" }]
                                },
                                "alias": { "type": "string", "minLength": 1 },
                                "indexField": { "type": "string", "minLength": 1 }
                            }
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "sample",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["sample"],
                    "properties": {
                        "sample": {
                            "type": "object",
                            "additionalProperties": false,
                            "required": ["size", "mode"],
                            "properties": {
                                "size": { "type": "number" },
                                "mode": { "$ref": "#/$defs/sampleMode" }
                            }
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "findNearest",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["findNearest"],
                    "properties": {
                        "findNearest": {
                            "type": "object",
                            "additionalProperties": false,
                            "required": ["field", "vector", "measure"],
                            "properties": {
                                "field": {
                                    "oneOf": [{ "$ref": "#/$defs/fieldPath" }, { "$ref": "#/$defs/expression" }]
                                },
                                "vector": {
                                    "type": "array",
                                    "minItems": 1,
                                    "items": { "type": "number" }
                                },
                                "measure": { "$ref": "#/$defs/pipelineDistanceMeasure" },
                                "limit": { "type": "integer", "minimum": 1 },
                                "distanceField": { "type": "string", "minLength": 1 }
                            }
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "let",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["let"],
                    "properties": {
                        "let": {
                            "type": "array",
                            "minItems": 1,
                            "description": "Defines named variables reusable later via {\"var\": name}. Wire stage name: let.",
                            "items": { "$ref": "#/$defs/aliasedExpression" }
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "search",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["search"],
                    "properties": {
                        "search": {
                            "type": "object",
                            "additionalProperties": false,
                            "description": "Full-text search stage (public preview). Must be the first stage.",
                            "properties": {
                                "query": {
                                    "oneOf": [{ "type": "string" }, { "$ref": "#/$defs/booleanExpression" }]
                                },
                                "addFields": {
                                    "type": "array",
                                    "items": { "$ref": "#/$defs/selectable" }
                                },
                                "sort": {
                                    "type": "array",
                                    "items": { "$ref": "#/$defs/ordering" }
                                },
                                "retrievalDepth": { "type": "integer", "minimum": 1 }
                            }
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "update",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["update"],
                    "properties": {
                        "update": {
                            "type": "object",
                            "additionalProperties": false,
                            "description": "Updates documents flowing through the pipeline (public preview).",
                            "properties": {
                                "transformations": {
                                    "type": "array",
                                    "items": { "$ref": "#/$defs/selectable" }
                                }
                            }
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "delete",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["delete"],
                    "properties": {
                        "delete": {
                            "type": "object",
                            "additionalProperties": false,
                            "description": "Deletes documents flowing through the pipeline (public preview)."
                        },
                        "options": { "$ref": "#/$defs/stageOptions" }
                    }
                },
                {
                    "title": "raw",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["raw"],
                    "properties": {
                        "raw": {
                            "type": "object",
                            "additionalProperties": false,
                            "required": ["name"],
                            "description": "Generic/escape-hatch stage for custom or future stage names.",
                            "properties": {
                                "name": { "type": "string", "minLength": 1 },
                                "args": {
                                    "type": "array",
                                    "items": { "$ref": "#/$defs/expression" }
                                },
                                "options": { "$ref": "#/$defs/stageOptions" }
                            }
                        }
                    }
                }
            ]
        },

        "stageOptions": {
            "type": "object",
            "description": "Free-form named options passed through to the backend stage."
        },

        "expression": {
            "description": "A pipeline expression: a field reference, a constant value, a function call, a variable reference, or a nested pipeline used as a sub-expression.",
            "oneOf": [
                {
                    "title": "field",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["field"],
                    "properties": {
                        "field": { "$ref": "#/$defs/fieldPath" }
                    }
                },
                {
                    "title": "const",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["const"],
                    "properties": {
                        "const": { "$ref": "#/$defs/queryValue" }
                    }
                },
                {
                    "title": "function",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["fn"],
                    "properties": {
                        "fn": { "$ref": "#/$defs/functionName" },
                        "args": {
                            "type": "array",
                            "items": { "$ref": "#/$defs/expression" }
                        }
                    }
                },
                {
                    "title": "variable",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["var"],
                    "properties": {
                        "var": { "type": "string", "minLength": 1 }
                    }
                },
                {
                    "title": "pipeline",
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["pipeline"],
                    "properties": {
                        "pipeline": { "$ref": "#/$defs/pipeline" }
                    }
                }
            ]
        },

        "booleanExpression": {
            "description": "An expression that must evaluate to a boolean (typically a comparison or logical function such as and, or, equal, greater_than, array_contains, like, exists, ...).",
            "$ref": "#/$defs/expression"
        },

        "aliasedExpression": {
            "type": "object",
            "additionalProperties": false,
            "required": ["as", "expr"],
            "properties": {
                "as": { "type": "string", "minLength": 1 },
                "expr": { "$ref": "#/$defs/expression" }
            }
        },

        "selectable": {
            "description": "A field path string (selected/grouped under its own name) or an aliased expression.",
            "oneOf": [{ "$ref": "#/$defs/fieldPath" }, { "$ref": "#/$defs/aliasedExpression" }]
        },

        "ordering": {
            "type": "object",
            "additionalProperties": false,
            "required": ["expr", "dir"],
            "properties": {
                "expr": { "$ref": "#/$defs/expression" },
                "dir": { "$ref": "#/$defs/orderDirection" }
            }
        },

        "aliasedAggregate": {
            "type": "object",
            "additionalProperties": false,
            "required": ["as", "agg"],
            "properties": {
                "as": { "type": "string", "minLength": 1 },
                "agg": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["fn"],
                    "properties": {
                        "fn": { "$ref": "#/$defs/aggregateName" },
                        "args": {
                            "type": "array",
                            "items": { "$ref": "#/$defs/expression" }
                        }
                    }
                }
            }
        },

        "pipelineDistanceMeasure": {
            "type": "string",
            "description": "Pipeline find_nearest distance measure (note: underscore form, distinct from the classic query distanceMeasure).",
            "enum": ["euclidean", "cosine", "dot_product"]
        },

        "sampleMode": {
            "type": "string",
            "enum": ["documents", "percent"]
        },

        "functionName": {
            "description": "Firestore pipeline function wire name. The enum lists the ~128 known functions of the Go SDK v1.22.0 for editor support; any other string is also accepted for forward compatibility.",
            "anyOf": [
                {
                    "enum": [
                        "abs", "add", "and", "array", "array_concat", "array_contains",
                        "array_contains_all", "array_contains_any", "array_filter", "array_first",
                        "array_first_n", "array_get", "array_index_of", "array_index_of_all",
                        "array_last", "array_last_n", "array_length", "array_reverse",
                        "array_slice", "array_transform", "byte_length", "ceil", "char_length",
                        "cmp", "coalesce", "collection_id", "concat", "conditional",
                        "cosine_distance", "current_document", "current_timestamp", "divide",
                        "document_id", "document_matches", "dot_product", "ends_with", "equal",
                        "equal_any", "euclidean_distance", "exists", "exp", "floor",
                        "geo_distance", "get_field", "greater_than", "greater_than_or_equal",
                        "if_absent", "if_error", "if_null", "is_absent", "is_error", "is_type",
                        "join", "length", "less_than", "less_than_or_equal", "like", "ln", "log",
                        "log10", "ltrim", "map", "map_entries", "map_get", "map_keys",
                        "map_merge", "map_remove", "map_set", "map_values", "maximum",
                        "maximum_n", "minimum", "minimum_n", "mod", "multiply", "nor", "not",
                        "not_equal", "not_equal_any", "offset", "or", "parent", "pow", "rand",
                        "reference_slice", "regex_contains", "regex_find", "regex_find_all",
                        "regex_match", "reverse", "round", "rtrim", "score", "split", "sqrt",
                        "starts_with", "storage_size", "string_concat", "string_contains",
                        "string_index_of", "string_repeat", "string_replace_all",
                        "string_replace_one", "string_reverse", "substring", "subtract", "sum",
                        "switch_on", "timestamp_add", "timestamp_diff", "timestamp_extract",
                        "timestamp_subtract", "timestamp_to_unix_micros",
                        "timestamp_to_unix_millis", "timestamp_to_unix_seconds",
                        "timestamp_trunc", "to_lower", "to_upper", "trim", "trunc", "type",
                        "unix_micros_to_timestamp", "unix_millis_to_timestamp",
                        "unix_seconds_to_timestamp", "vector_length", "xor"
                    ]
                },
                { "type": "string", "minLength": 1 }
            ]
        },

        "aggregateName": {
            "type": "string",
            "description": "Aggregate accumulator wire name used inside the aggregate stage.",
            "enum": [
                "count", "count_distinct", "count_if", "sum", "average",
                "minimum", "maximum", "first", "last", "array_agg", "array_agg_distinct"
            ]
        },

        "firestoreTypeName": {
            "type": "string",
            "description": "Type-name vocabulary accepted as the second argument of is_type / returned by the type function. Provided for documentation; not enforced positionally.",
            "enum": [
                "null", "boolean", "string", "int32", "int64", "float64", "number",
                "decimal128", "bytes", "timestamp", "geo_point", "reference", "vector",
                "map", "array", "object_id", "min_key", "max_key"
            ]
        }
    },
    "examples": [
        {
            "__queryId__": "query-1",
            "realtime": true,
            "limitToLast": false,
            "limit": 50,
            "collectionGroup": false,
            "orders": [{ "field": "createdAt", "dir": "desc" }],
            "filters": [
                { "field": "status", "op": "==", "value": "active" },
                {
                    "or": [
                        { "field": "priority", "op": ">=", "value": 3 },
                        {
                            "field": "owner",
                            "op": "==",
                            "value": { "__placeholder__": "query", "custom": false, "format": "Native" }
                        }
                    ]
                }
            ]
        },
        {
            "stages": [
                { "collection": "orders" },
                {
                    "where": {
                        "fn": "and",
                        "args": [
                            { "fn": "equal", "args": [{ "field": "status" }, { "const": "active" }] },
                            { "fn": "greater_than", "args": [{ "field": "amount" }, { "const": 100 }] }
                        ]
                    }
                },
                {
                    "addFields": [
                        {
                            "as": "total",
                            "expr": { "fn": "multiply", "args": [{ "field": "price" }, { "field": "quantity" }] }
                        }
                    ]
                },
                { "sort": [{ "expr": { "field": "createdAt" }, "dir": "desc" }] },
                { "limit": 50 }
            ]
        },
        {
            "stages": [
                { "collection": "orders" },
                {
                    "aggregate": {
                        "accumulators": [
                            { "as": "totalRevenue", "agg": { "fn": "sum", "args": [{ "field": "amount" }] } },
                            { "as": "n", "agg": { "fn": "count" } }
                        ],
                        "groups": ["category"]
                    }
                },
                { "sort": [{ "expr": { "field": "totalRevenue" }, "dir": "desc" }] }
            ]
        },
        {
            "stages": [
                { "collection": "products" },
                {
                    "findNearest": {
                        "field": "embedding",
                        "vector": [0.1, 0.2, 0.3],
                        "measure": "cosine",
                        "limit": 10,
                        "distanceField": "dist"
                    }
                }
            ]
        },
        {
            "stages": [
                { "collection": "events" },
                { "let": [{ "as": "cutoff", "expr": { "const": { "__time__": "2026-01-01T00:00:00Z" } } }] },
                { "where": { "fn": "greater_than", "args": [{ "field": "ts" }, { "var": "cutoff" }] } },
                { "raw": { "name": "custom_stage", "args": [{ "const": 42 }], "options": { "flag": true } } }
            ]
        }
    ]
}
