@jarenjs/json 0.9.2 → 0.34.0

package/schemas/jaren-query.llm-profile.schema.json

@@ -0,0 +1,619 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jarenjs.dev/schemas/jaren-query/0.1/llm-profile",
+  "title": "Jaren JSON Query format 0.1 (LLM profile)",
+  "description": "LLM-profile relaxation of the canonical grammar for provider structured-output subsets that do not enforce patternProperties, propertyNames or asserted formats. Every canonical-valid document validates here; the reverse is NOT guaranteed - always validate generated documents against the canonical schema locally before compiling. Structural grammar of Jaren JSON Query documents (see packages/json/docs/QUERY-FORMAT.md). This schema is structural validation only: the compiler remains authoritative for semantic rules it cannot express - FLWOR clause keys apply in the fixed semantic order $for, $let, $as, $where, $groupby, $orderby, $count, $return regardless of JSON key order; variable scoping, duplicate-binding detection, external-parameter collection and $as name binding are compiler rules (JQ0005/JQ0007); variable-rooted path strings are only head-checked here (full RFC 9535 segment grammar is JQ0004); embedded JSON Schema literals are taken verbatim and never meta-validated here (the type-test compiler is authoritative, JQ0008/JQ0009); per-argument runtime typing is JQ2xxx. Authored in a draft-neutral keyword subset; the draft-07 twin is a mechanical derivation.",
+  "allOf": [
+    {
+      "$ref": "#/$defs/queryDocument"
+    }
+  ],
+  "$defs": {
+    "queryDocument": {
+      "description": "A query document is either the version envelope or a bare expression (a bare RFC 9535 JSONPath string is the degenerate query).",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/versionEnvelope"
+        },
+        {
+          "$ref": "#/$defs/expression"
+        }
+      ]
+    },
+    "versionEnvelope": {
+      "description": "Top-level version envelope. Only recognized at the top level of a query document.",
+      "type": "object",
+      "properties": {
+        "$query": {
+          "const": "0.1"
+        },
+        "$expr": {
+          "$ref": "#/$defs/expression"
+        }
+      },
+      "required": [
+        "$query",
+        "$expr"
+      ],
+      "additionalProperties": false
+    },
+    "expression": {
+      "description": "Any expression per the encoding rules: scalars are literals, strings split on the leading '$', arrays are array constructors, objects partition into map constructors (no $-prefixed key) and operator phrases (all keys $-prefixed).",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/scalarLiteral"
+        },
+        {
+          "$ref": "#/$defs/stringExpression"
+        },
+        {
+          "$ref": "#/$defs/arrayConstructor"
+        },
+        {
+          "$ref": "#/$defs/objectExpression"
+        }
+      ]
+    },
+    "scalarLiteral": {
+      "description": "Numbers, booleans and null are literal items.",
+      "type": [
+        "null",
+        "boolean",
+        "number"
+      ]
+    },
+    "stringExpression": {
+      "description": "Rule 2: a string starting with '$' is a query expression ('$$' escapes a literal); any other string is a literal.",
+      "type": "string",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/literalString"
+        },
+        {
+          "$ref": "#/$defs/escapedStringLiteral"
+        },
+        {
+          "$ref": "#/$defs/absolutePathString"
+        },
+        {
+          "$ref": "#/$defs/variablePathString"
+        }
+      ]
+    },
+    "literalString": {
+      "description": "A string that does not start with '$' denotes itself.",
+      "type": "string",
+      "pattern": "^([^$]|$)"
+    },
+    "escapedStringLiteral": {
+      "description": "A string starting with '$$' denotes the literal string with one leading '$' dropped.",
+      "type": "string",
+      "pattern": "^\\$\\$"
+    },
+    "absolutePathString": {
+      "description": "An absolute RFC 9535 JSONPath query rooted at the input document: '$' alone or starting '$.', '$[' or '$..'. The json-path format asserts the full RFC 9535 grammar where format assertion is enabled (format is annotation-only by default from draft 2020-12). (LLM profile: the 'json-path' format assertion is relaxed here; the canonical schema enforces it)",
+      "type": "string",
+      "pattern": "^\\$($|[.\\[])"
+    },
+    "variablePathString": {
+      "description": "A variable-rooted path: '$name' with name matching [A-Za-z_][A-Za-z0-9_]*, optionally followed by RFC 9535 segments. The pattern checks the head; the json-path-segments format asserts the full segment grammar where format assertion is enabled (the compiler enforces it either way, JQ0004). (LLM profile: the 'json-path-segments' format assertion is relaxed here; the canonical schema enforces it)",
+      "type": "string",
+      "pattern": "^\\$[A-Za-z_][A-Za-z0-9_]*($|[.\\[])"
+    },
+    "arrayConstructor": {
+      "description": "An array in expression position constructs an array; element results are concatenated per XQuery sequence flattening.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/expression"
+      }
+    },
+    "objectExpression": {
+      "description": "Rule 1: objects partition by $-prefixed keys. A mixed object matches neither branch and is invalid (JQ0001).",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/mapConstructor"
+        },
+        {
+          "$ref": "#/$defs/constPhrase"
+        },
+        {
+          "$ref": "#/$defs/mapPhrase"
+        },
+        {
+          "$ref": "#/$defs/callPhrase"
+        },
+        {
+          "$ref": "#/$defs/flworPhrase"
+        },
+        {
+          "$ref": "#/$defs/somePhrase"
+        },
+        {
+          "$ref": "#/$defs/everyPhrase"
+        },
+        {
+          "$ref": "#/$defs/unaryOperatorPhrase"
+        },
+        {
+          "$ref": "#/$defs/binaryOperatorPhrase"
+        },
+        {
+          "$ref": "#/$defs/variadicOperatorPhrase"
+        },
+        {
+          "$ref": "#/$defs/nonEmptyVariadicOperatorPhrase"
+        },
+        {
+          "$ref": "#/$defs/conditionalArityOperatorPhrase"
+        },
+        {
+          "$ref": "#/$defs/stringJoinPhrase"
+        },
+        {
+          "$ref": "#/$defs/geohashPhrase"
+        },
+        {
+          "$ref": "#/$defs/ternaryOperatorPhrase"
+        },
+        {
+          "$ref": "#/$defs/replacePhrase"
+        },
+        {
+          "$ref": "#/$defs/schemaOperatorPhrase"
+        }
+      ]
+    },
+    "mapConstructor": {
+      "description": "An object with no $-prefixed key: keys are literal member names, values are expressions. Use $map or $const for member names that start with '$'. (LLM profile: a member-name constraint is relaxed here; the canonical schema enforces it)",
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/expression"
+      }
+    },
+    "constPhrase": {
+      "description": "Quote: the value is returned verbatim, nothing inside is evaluated.",
+      "type": "object",
+      "properties": {
+        "$const": true
+      },
+      "required": [
+        "$const"
+      ],
+      "additionalProperties": false
+    },
+    "mapPhrase": {
+      "description": "General map constructor for computed keys or keys starting with '$'. Each entry is a [keyExpr, valueExpr] pair; keyExpr must evaluate to a single string at runtime (JQ2004); later pairs win on duplicate keys.",
+      "type": "object",
+      "properties": {
+        "$map": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/mapEntry"
+          }
+        }
+      },
+      "required": [
+        "$map"
+      ],
+      "additionalProperties": false
+    },
+    "mapEntry": {
+      "description": "One [keyExpr, valueExpr] pair of a $map phrase.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/expression"
+      },
+      "minItems": 2,
+      "maxItems": 2
+    },
+    "callPhrase": {
+      "description": "A registered trusted host function call: ['name', ...argument expressions]. The name must be registered at compile time (options.functions, JQ0010); sequences cross the boundary as arrays, a returned undefined is the empty sequence, a throwing function is JQ2010.",
+      "type": "object",
+      "properties": {
+        "$call": {
+          "type": "array",
+          "minItems": 1,
+          "prefixItems": [
+            {
+              "type": "string",
+              "minLength": 1
+            }
+          ],
+          "items": {
+            "$ref": "#/$defs/expression"
+          }
+        }
+      },
+      "required": [
+        "$call"
+      ],
+      "additionalProperties": false
+    },
+    "flworPhrase": {
+      "description": "FLWOR phrase. Clauses apply in the fixed semantic order $fold, $for, $let, $as, $where, $groupby, $orderby, $count, $return regardless of JSON key order (D7); interleavings are expressed by nesting phrases. $return is required, plus at least one of $fold/$for/$let. With $fold the phrase evaluates to the final accumulator instead of the collected $return sequence.",
+      "type": "object",
+      "properties": {
+        "$fold": {
+          "$ref": "#/$defs/foldBinding"
+        },
+        "$for": {
+          "$ref": "#/$defs/forBindings"
+        },
+        "$let": {
+          "$ref": "#/$defs/bindingMap"
+        },
+        "$as": {
+          "$ref": "#/$defs/asClause"
+        },
+        "$where": {
+          "$ref": "#/$defs/expression"
+        },
+        "$groupby": {
+          "$ref": "#/$defs/bindingMap"
+        },
+        "$orderby": {
+          "$ref": "#/$defs/orderBySpec"
+        },
+        "$count": {
+          "$ref": "#/$defs/variableName"
+        },
+        "$return": {
+          "$ref": "#/$defs/expression"
+        }
+      },
+      "required": [
+        "$return"
+      ],
+      "anyOf": [
+        {
+          "required": [
+            "$for"
+          ]
+        },
+        {
+          "required": [
+            "$let"
+          ]
+        },
+        {
+          "required": [
+            "$fold"
+          ]
+        }
+      ],
+      "additionalProperties": false
+    },
+    "foldBinding": {
+      "description": "The $fold accumulator: exactly one variable name mapped to the accumulator's initial value, evaluated once in the enclosing scope before the tuple stream starts. $return then names the accumulator's next value per surviving tuple. (LLM profile: a member-name constraint is relaxed here; the canonical schema enforces it)",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "additionalProperties": {
+        "$ref": "#/$defs/expression"
+      }
+    },
+    "variableName": {
+      "type": "string",
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+    },
+    "forBindings": {
+      "description": "Iteration bindings: variable name to source expression or extended $in binding. Bindings nest left-to-right in document key order and may be correlated; key-order-hostile producers should nest phrases instead. (LLM profile: a member-name constraint is relaxed here; the canonical schema enforces it)",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "$ref": "#/$defs/forSource"
+      }
+    },
+    "forSource": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/expression"
+        },
+        {
+          "$ref": "#/$defs/extendedForBinding"
+        }
+      ]
+    },
+    "extendedForBinding": {
+      "description": "Extended $for binding. $in is the source; $at binds the 0-based (D6) position variable; $allowing-empty emits one tuple with the variable bound to the empty sequence (position -1) when the source yields no tuple; $window with $size, and optionally $step, iterates tumbling or sliding windows instead of items. Only $in is structurally required: the compiler rejects $size/$step without $window, and $window without $size (JQ0003).",
+      "type": "object",
+      "properties": {
+        "$in": {
+          "$ref": "#/$defs/expression"
+        },
+        "$at": {
+          "$ref": "#/$defs/variableName"
+        },
+        "$allowing-empty": {
+          "type": "boolean"
+        },
+        "$window": {
+          "enum": [
+            "tumbling",
+            "sliding"
+          ]
+        },
+        "$size": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "$step": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "required": [
+        "$in"
+      ],
+      "additionalProperties": false
+    },
+    "bindingMap": {
+      "description": "Variable name to expression map, used by $let, $groupby and quantifier bindings. (LLM profile: a member-name constraint is relaxed here; the canonical schema enforces it)",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "$ref": "#/$defs/expression"
+      }
+    },
+    "orderBySpec": {
+      "description": "A single key spec or a major-to-minor list of key specs. An array value is by specification ALWAYS a list of key specs, so the single form excludes arrays; write a single array-constructor key as {\"$key\": [...]}.",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/singleOrderByKey"
+        },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/orderByKey"
+          },
+          "minItems": 1
+        }
+      ]
+    },
+    "singleOrderByKey": {
+      "description": "A key spec in non-list position: any non-array expression, or the explicit {$key, $dir, $empty} form.",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/scalarLiteral"
+        },
+        {
+          "$ref": "#/$defs/stringExpression"
+        },
+        {
+          "$ref": "#/$defs/objectExpression"
+        },
+        {
+          "$ref": "#/$defs/orderByKeySpec"
+        }
+      ]
+    },
+    "orderByKey": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/expression"
+        },
+        {
+          "$ref": "#/$defs/orderByKeySpec"
+        }
+      ]
+    },
+    "orderByKeySpec": {
+      "description": "Explicit order key: direction defaults to 'asc', empty-sequence placement to 'least'. A $collation names a registered pure compare function (options.collations, JQ0010) applied to string keys; the default stays code-point order.",
+      "type": "object",
+      "properties": {
+        "$key": {
+          "$ref": "#/$defs/expression"
+        },
+        "$dir": {
+          "enum": [
+            "asc",
+            "desc"
+          ]
+        },
+        "$empty": {
+          "enum": [
+            "least",
+            "greatest"
+          ]
+        },
+        "$collation": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "$key"
+      ],
+      "additionalProperties": false
+    },
+    "somePhrase": {
+      "description": "Existential quantifier: true iff some binding tuple satisfies the EBV of $satisfies; short-circuits.",
+      "type": "object",
+      "properties": {
+        "$some": {
+          "$ref": "#/$defs/bindingMap"
+        },
+        "$satisfies": {
+          "$ref": "#/$defs/expression"
+        }
+      },
+      "required": [
+        "$some",
+        "$satisfies"
+      ],
+      "additionalProperties": false
+    },
+    "everyPhrase": {
+      "description": "Universal quantifier: true iff every binding tuple satisfies the EBV of $satisfies; short-circuits.",
+      "type": "object",
+      "properties": {
+        "$every": {
+          "$ref": "#/$defs/bindingMap"
+        },
+        "$satisfies": {
+          "$ref": "#/$defs/expression"
+        }
+      },
+      "required": [
+        "$every",
+        "$satisfies"
+      ],
+      "additionalProperties": false
+    },
+    "unaryOperatorPhrase": {
+      "description": "Operators whose value is a single operand expression. (LLM profile: a member-name constraint is relaxed here; the canonical schema enforces it)",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "additionalProperties": {
+        "$ref": "#/$defs/expression"
+      }
+    },
+    "binaryOperatorPhrase": {
+      "description": "Operators whose value is an array of exactly two operand expressions. (LLM profile: a member-name constraint is relaxed here; the canonical schema enforces it)",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "$ref": "#/$defs/expression"
+        },
+        "minItems": 2,
+        "maxItems": 2
+      }
+    },
+    "variadicOperatorPhrase": {
+      "description": "Variadic operators accepting zero or more operand expressions. (LLM profile: a member-name constraint is relaxed here; the canonical schema enforces it)",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "$ref": "#/$defs/expression"
+        }
+      }
+    },
+    "nonEmptyVariadicOperatorPhrase": {
+      "description": "Variadic operators requiring at least one operand expression. (LLM profile: a member-name constraint is relaxed here; the canonical schema enforces it)",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "$ref": "#/$defs/expression"
+        },
+        "minItems": 1
+      }
+    },
+    "conditionalArityOperatorPhrase": {
+      "description": "Operators taking two or three operand expressions: $if [cond, then, else?], $substring [str, start, len?], $subsequence [seq, start, len?], $date-add / $date-sub [date, duration] or [date, amount, unit]. (LLM profile: a member-name constraint is relaxed here; the canonical schema enforces it)",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "$ref": "#/$defs/expression"
+        },
+        "minItems": 2,
+        "maxItems": 3
+      }
+    },
+    "geohashPhrase": {
+      "description": "$geohash [value] or [value, precision]: a GeoJSON value as a base-32 cell string. Precision is an integer from 1 to 12 (default 9); a value that is not a bare position is represented by its centroid.",
+      "type": "object",
+      "properties": {
+        "$geohash": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/expression"
+          },
+          "minItems": 1,
+          "maxItems": 2
+        }
+      },
+      "required": [
+        "$geohash"
+      ],
+      "additionalProperties": false
+    },
+    "stringJoinPhrase": {
+      "description": "$string-join [seq, separator?]: one or two operand expressions.",
+      "type": "object",
+      "properties": {
+        "$string-join": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/expression"
+          },
+          "minItems": 1,
+          "maxItems": 2
+        }
+      },
+      "required": [
+        "$string-join"
+      ],
+      "additionalProperties": false
+    },
+    "ternaryOperatorPhrase": {
+      "description": "Operators whose value is an array of exactly three operand expressions: $date-diff [from, to, unit]. (LLM profile: a member-name constraint is relaxed here; the canonical schema enforces it)",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "$ref": "#/$defs/expression"
+        },
+        "minItems": 3,
+        "maxItems": 3
+      }
+    },
+    "replacePhrase": {
+      "description": "$replace [input, pattern, replacement]: exactly three operand expressions (I-Regexp has no flags argument, D5).",
+      "type": "object",
+      "properties": {
+        "$replace": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/expression"
+          },
+          "minItems": 3,
+          "maxItems": 3
+        }
+      },
+      "required": [
+        "$replace"
+      ],
+      "additionalProperties": false
+    },
+    "schemaLiteral": {
+      "description": "A JSON Schema literal, taken verbatim - never interpreted as a query expression, so JSON Schema's $-prefixed keywords ($ref, $defs, ...) do not collide with Rule 1. Deliberately unconstrained (a true schema is draft-neutral by definition): embedded schemas are not meta-validated by this artifact; the consumer's type-test compiler is authoritative (JQ0009)."
+    },
+    "schemaOperatorPhrase": {
+      "description": "Schema operators $valid/$assert: [expr, schema] - exactly two elements, an operand expression and a verbatim JSON Schema literal. Tuple validation is outside the draft-neutral subset, so both positions validate uniformly as schema literals here; the operand position is normalized as an ordinary expression by the compiler (JQ0xxx). (LLM profile: a member-name constraint is relaxed here; the canonical schema enforces it)",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "$ref": "#/$defs/schemaLiteral"
+        },
+        "minItems": 2,
+        "maxItems": 2
+      }
+    },
+    "asClause": {
+      "description": "The $as clause: variable-name to JSON Schema literal members, applied per tuple after $for/$let binding and before $where. Each name must be bound by the same phrase's $for (including $at names) or $let - a compiler rule (JQ0005); each binding validates per item at runtime (JQ2008). (LLM profile: a member-name constraint is relaxed here; the canonical schema enforces it)",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "$ref": "#/$defs/schemaLiteral"
+      }
+    }
+  }
+}