@open-predicate/open-predicate 0.6.0

package/open-predicate-schema.json

@@ -0,0 +1,395 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openpredicate.tech/schema/v0.4.0/open-predicate-schema.json",
+  "title": "OpenPredicate — Filter",
+  "description": "A JSON-encoded, SQL-flavoured predicate language for describing the request body of search operations (POST /…/search and QUERY /…). Everything needed to write a correct filter is described here, operator by operator, so one grammar can be shared by every search endpoint in an API: reference this schema from an OpenAPI document, or inline it as the input schema of a search tool. Normative semantics are defined in SPEC.md.",
+  "$comment": "Version 0.4.0. See https://github.com/OpenPredicate/open-predicate",
+
+  "$ref": "#/$defs/Filter",
+
+  "x-profiles": {
+    "core": ["$and", "$or", "$nor", "$not", "$eq", "$ne", "$in", "$nin", "$gt", "$gte", "$lt", "$lte", "$exists", "$isNull", "$unknownAs"],
+    "strings": ["$like", "$nlike", "$ilike", "$nilike", "$startsWith", "$endsWith", "$contains"],
+    "regex": ["$regex", "$flags"],
+    "ranges": ["$between", "$nbetween"],
+    "types": ["$type"],
+    "collections": ["$some", "$every", "$hasAll", "$size"],
+    "refs": ["$field", "$literal"],
+    "text": ["$search"]
+  },
+
+  "$defs": {
+    "Filter": {
+      "title": "Filter",
+      "description": "A predicate over a record. Sibling members are combined with implicit AND: every member must evaluate TRUE for the filter to match. Keys beginning with '$' are reserved for logical operators; a field whose real name begins with '$' is escaped by doubling it ('$$price' means the field '$price').",
+      "type": "object",
+      "minProperties": 1,
+      "properties": {
+        "$and": {
+          "title": "$and",
+          "description": "All of the listed filters must evaluate TRUE.",
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/Filter" }
+        },
+        "$or": {
+          "title": "$or",
+          "description": "At least one of the listed filters must evaluate TRUE.",
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/Filter" }
+        },
+        "$nor": {
+          "title": "$nor",
+          "description": "NOT (a OR b OR …), evaluated under three-valued logic. It is TRUE only when every listed filter is FALSE: if one of them is UNKNOWN the result is UNKNOWN, not TRUE, so a $nor over a nullable field excludes the records whose field is null or absent. See SPEC.md §4.1.",
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/Filter" }
+        },
+        "$not": {
+          "title": "$not",
+          "description": "Negates a filter. Under three-valued logic NOT UNKNOWN is UNKNOWN, not TRUE — so this does not match records whose field is null or absent. Add $unknownAs to the inner constraint to include them. See SPEC.md §4.1.",
+          "$ref": "#/$defs/Filter"
+        }
+      },
+      "patternProperties": {
+        "^(?:[^$]|\\$\\$)": { "$ref": "#/$defs/Constraint" }
+      },
+      "propertyNames": {
+        "$comment": "Deliberately overlaps with patternProperties/additionalProperties above: those two enforce the default grammar, while this is the single named override point. Narrow #/$defs/FieldPath in a bundled copy of this schema to restrict an endpoint to a fixed field set — the narrowing then applies at every nesting level, because Filter recurses through this same $ref. See README §Restricting the queryable field set.",
+        "anyOf": [
+          { "enum": ["$and", "$or", "$nor", "$not"] },
+          { "$ref": "#/$defs/FieldPath" }
+        ]
+      },
+      "additionalProperties": false,
+      "examples": [
+        { "status": "open" },
+        { "department": { "$eq": "sales" }, "age": { "$gte": 18 } },
+        {
+          "$and": [
+            { "department": { "$eq": "sales" } },
+            { "$or": [{ "role": "admin" }, { "role": "manager" }] }
+          ]
+        }
+      ]
+    },
+
+    "FieldPath": {
+      "title": "Field path",
+      "description": "A dotted path to a member of the record: 'a.b.c'. An array element is addressed by index ('items[0]'); to say something about the elements of an array without naming an index, use $some or $every, which quantify explicitly. A literal '.' inside a key is escaped as '\\.'. The default rule is permissive — any non-empty string not beginning with a single '$' — because the set of queryable paths is a property of the resource, not of the language. Full grammar in SPEC.md §3.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?:[^$]|\\$\\$)",
+      "not": {
+        "$comment": "The '[*]' wildcard was removed in v0.4.0; $some and $every replace it. Rejecting it here turns a stale filter into a validation error instead of a path that would be read as a literal key name.",
+        "pattern": "\\[\\*\\]"
+      },
+      "examples": ["name", "address.city", "items[0].sku", "$$internal"]
+    },
+
+    "Constraint": {
+      "title": "Constraint",
+      "description": "The condition applied to one field. Either a scalar shorthand — {\"status\": \"open\"} is exactly {\"status\": {\"$eq\": \"open\"}} — or an object of operators. Arrays and objects are deliberately excluded from the shorthand so that {\"tags\": [\"a\"]} can never be read ambiguously as either $eq or $in.",
+      "anyOf": [
+        { "$ref": "#/$defs/ScalarOrNull" },
+        { "$ref": "#/$defs/ConstraintObject" }
+      ]
+    },
+
+    "ConstraintObject": {
+      "title": "Constraint object",
+      "description": "One or more operators applied to the same field. Sibling operators are combined with implicit AND, so {\"age\": {\"$gt\": 18, \"$ne\": 30}} is a single well-formed constraint.",
+      "type": "object",
+      "minProperties": 1,
+      "dependentSchemas": {
+        "$unknownAs": {
+          "$comment": "$unknownAs is a modifier, not a predicate: it needs at least one operator to modify. Requiring a second member forbids {\"$unknownAs\": true} standing alone.",
+          "minProperties": 2
+        }
+      },
+      "properties": {
+        "$eq": {
+          "title": "$eq",
+          "description": "Field equals the operand. Any JSON value, including null, arrays and objects. A value of a different JSON type is unequal — FALSE, not UNKNOWN.",
+          "$ref": "#/$defs/Operand"
+        },
+        "$ne": {
+          "title": "$ne",
+          "description": "Field does not equal the operand. The negation of $eq under three-valued logic, so this is UNKNOWN — and therefore does not match — when the field is null or absent. Add $unknownAs: true to include those records. See SPEC.md §4.1.",
+          "$ref": "#/$defs/Operand"
+        },
+
+        "$gt": {
+          "title": "$gt",
+          "description": "Field is strictly greater than the operand.",
+          "$ref": "#/$defs/OrderedOperand"
+        },
+        "$gte": {
+          "title": "$gte",
+          "description": "Field is greater than or equal to the operand.",
+          "$ref": "#/$defs/OrderedOperand"
+        },
+        "$lt": {
+          "title": "$lt",
+          "description": "Field is strictly less than the operand.",
+          "$ref": "#/$defs/OrderedOperand"
+        },
+        "$lte": {
+          "title": "$lte",
+          "description": "Field is less than or equal to the operand.",
+          "$ref": "#/$defs/OrderedOperand"
+        },
+
+        "$between": {
+          "title": "$between",
+          "description": "Field falls within [lower, upper], inclusive of both bounds.",
+          "$ref": "#/$defs/Bounds"
+        },
+        "$nbetween": {
+          "title": "$nbetween",
+          "description": "Field falls outside [lower, upper]. The negation of $between under three-valued logic, so it is UNKNOWN when the field is null or absent.",
+          "$ref": "#/$defs/Bounds"
+        },
+
+        "$in": {
+          "title": "$in",
+          "description": "Field equals at least one member of the list. Compares the whole value — it does NOT test membership inside an array-valued field: {\"tags\": {\"$in\": [\"a\"]}} asks whether tags equals \"a\". For array elements quantify explicitly: {\"tags\": {\"$some\": {\"$in\": [\"a\"]}}}.",
+          "$ref": "#/$defs/OperandSet"
+        },
+        "$nin": {
+          "title": "$nin",
+          "description": "Field equals no member of the list. Like $in, compares the whole value rather than array elements. The negation of $in under three-valued logic, so it is UNKNOWN when the field is null or absent.",
+          "$ref": "#/$defs/OperandSet"
+        },
+
+        "$like": {
+          "title": "$like",
+          "description": "SQL LIKE pattern: '%' matches any run of characters, '_' matches exactly one, and '\\' escapes either. Case-sensitive.",
+          "type": "string",
+          "examples": ["%urgent%", "INV-____", "100\\%"]
+        },
+        "$nlike": {
+          "title": "$nlike",
+          "description": "Negated $like, under three-valued logic: UNKNOWN when the field is null, absent or not a string.",
+          "type": "string"
+        },
+        "$ilike": {
+          "title": "$ilike",
+          "description": "Case-insensitive $like. Collation is server-defined; see SPEC.md §5.5.",
+          "type": "string"
+        },
+        "$nilike": {
+          "title": "$nilike",
+          "description": "Negated $ilike, under three-valued logic: UNKNOWN when the field is null, absent or not a string.",
+          "type": "string"
+        },
+        "$startsWith": {
+          "title": "$startsWith",
+          "description": "Field begins with this literal substring. Wildcards are not interpreted.",
+          "type": "string"
+        },
+        "$endsWith": {
+          "title": "$endsWith",
+          "description": "Field ends with this literal substring. Wildcards are not interpreted.",
+          "type": "string"
+        },
+        "$contains": {
+          "title": "$contains",
+          "description": "Field contains this literal substring. String-only — for arrays, quantify over the elements with $some or $every.",
+          "type": "string"
+        },
+
+        "$regex": {
+          "title": "$regex",
+          "description": "Field matches this regular expression (ECMA-262 syntax). Servers SHOULD bound execution time; see SPEC.md §7.",
+          "type": "string",
+          "format": "regex"
+        },
+        "$flags": {
+          "title": "$flags",
+          "description": "Modifiers for $regex: 'i' case-insensitive, 'm' multiline, 's' dot-matches-newline. Only valid alongside $regex.",
+          "type": "string",
+          "pattern": "^[ims]{0,3}$"
+        },
+
+        "$exists": {
+          "title": "$exists",
+          "description": "true if the field is present on the record, even when its value is null; false if absent. Total — never UNKNOWN. Distinct from $isNull — see SPEC.md §4.2.",
+          "type": "boolean"
+        },
+        "$isNull": {
+          "title": "$isNull",
+          "description": "true if the field's value is null (equivalent to {\"$eq\": null}); false if it is non-null (equivalent to {\"$ne\": null}). UNKNOWN only when the path resolves to nothing.",
+          "type": "boolean"
+        },
+        "$type": {
+          "title": "$type",
+          "description": "Field's JSON type. 'integer' matches a number with no fractional part.",
+          "type": "string",
+          "enum": ["string", "number", "integer", "boolean", "object", "array", "null"]
+        },
+
+        "$some": {
+          "title": "$some",
+          "description": "At least one element of the array-valued field satisfies this condition. Supply a Filter for arrays of objects (paths are relative to the element) or a constraint object for arrays of scalars. An element for which the condition is UNKNOWN does not satisfy it, so the quantifier yields TRUE or FALSE over any array — FALSE for an empty one. It is UNKNOWN only when the field is not an array, including when it is null or absent. See SPEC.md §5.8.",
+          "anyOf": [
+            { "$ref": "#/$defs/Filter" },
+            { "$ref": "#/$defs/ConstraintObject" }
+          ],
+          "examples": [{ "qty": { "$gt": 2 } }, { "$in": ["urgent", "p1"] }]
+        },
+        "$every": {
+          "title": "$every",
+          "description": "Every element of the array-valued field satisfies this condition; an element for which it is UNKNOWN does not. TRUE for an empty array, vacuously. UNKNOWN only when the field is not an array, including when it is null or absent — a missing array is not vacuously TRUE. Same operand shape as $some. See SPEC.md §5.8.",
+          "anyOf": [
+            { "$ref": "#/$defs/Filter" },
+            { "$ref": "#/$defs/ConstraintObject" }
+          ],
+          "examples": [{ "status": "settled" }, { "$gte": 0 }]
+        },
+        "$hasAll": {
+          "title": "$hasAll",
+          "description": "The array-valued field contains every member of this list. Quantifies over the operand rather than over the elements, which is why it is not expressible as a $some or $every. Set semantics: multiplicity is ignored. UNKNOWN when the field is not an array.",
+          "$ref": "#/$defs/OperandSet"
+        },
+        "$size": {
+          "title": "$size",
+          "description": "Length of the array-valued field: either an exact count or a nested numeric constraint.",
+          "$ref": "#/$defs/SizeConstraint"
+        },
+
+        "$search": {
+          "title": "$search",
+          "description": "Free-text match against the field. Tokenisation, stemming and relevance are server-defined.",
+          "type": "string",
+          "minLength": 1
+        },
+
+        "$not": {
+          "title": "$not (field-level)",
+          "description": "Negates the constraint on this field. {\"age\": {\"$not\": {\"$gt\": 5}}} is TRUE when age is not greater than 5 and UNKNOWN when age is null or absent.",
+          "$ref": "#/$defs/ConstraintObject"
+        },
+        "$unknownAs": {
+          "title": "$unknownAs",
+          "description": "Resolves UNKNOWN to TRUE or FALSE for this constraint, applied last — after every sibling operator, including a field-level $not. {\"status\": {\"$ne\": \"archived\", \"$unknownAs\": true}} means 'not archived, and count the records where status is null or absent'. A modifier, not a predicate: it needs at least one operator beside it. No-op on $exists, which is already total. See SPEC.md §4.6.",
+          "type": "boolean"
+        }
+      },
+      "dependentRequired": {
+        "$flags": ["$regex"]
+      },
+      "additionalProperties": false,
+      "examples": [
+        { "$eq": "open" },
+        { "$gt": 18, "$ne": 30 },
+        { "$in": ["red", "green"] },
+        { "$regex": "^inv-", "$flags": "i" },
+        { "$ne": "archived", "$unknownAs": true },
+        { "$some": { "$in": ["urgent", "p1"] } }
+      ]
+    },
+
+    "ScalarOrNull": {
+      "title": "Scalar value",
+      "description": "A JSON scalar or null.",
+      "type": ["string", "number", "boolean", "null"]
+    },
+
+    "Operand": {
+      "title": "Operand",
+      "description": "A value to compare against: any JSON value, a reference to another field of the same record, or a $literal-wrapped value.",
+      "anyOf": [
+        { "$ref": "#/$defs/ValueRef" },
+        { "$ref": "#/$defs/LiteralWrapper" },
+        { "$ref": "#/$defs/PlainValue" }
+      ]
+    },
+
+    "OrderedOperand": {
+      "title": "Ordered operand",
+      "description": "A value on which an ordering is defined: a number, or a string compared lexicographically — which for RFC 3339 date, date-time and time strings coincides with chronological order.",
+      "anyOf": [
+        { "type": "number" },
+        { "type": "string" },
+        { "type": "string", "format": "date" },
+        { "type": "string", "format": "date-time" },
+        { "type": "string", "format": "time" },
+        { "$ref": "#/$defs/ValueRef" }
+      ],
+      "examples": [50, "2023-01-01", "2023-01-01T00:00:00Z", { "$field": "cost" }]
+    },
+
+    "ValueRef": {
+      "title": "Field reference",
+      "description": "Compares against another field of the same record rather than a constant: {\"price\": {\"$gt\": {\"$field\": \"cost\"}}} is SQL's WHERE price > cost.",
+      "type": "object",
+      "required": ["$field"],
+      "properties": {
+        "$field": { "$ref": "#/$defs/FieldPath" }
+      },
+      "additionalProperties": false
+    },
+
+    "LiteralWrapper": {
+      "title": "Literal escape",
+      "description": "Forces the wrapped value to be treated as data. Required only when an object operand would otherwise look like a field reference, e.g. {\"$literal\": {\"$field\": \"not-a-reference\"}}.",
+      "type": "object",
+      "required": ["$literal"],
+      "properties": {
+        "$literal": true
+      },
+      "additionalProperties": false
+    },
+
+    "PlainValue": {
+      "title": "Plain value",
+      "description": "Any JSON value that is not an object carrying '$'-prefixed keys. The '$' prefix is reserved for $field and $literal, so plain object operands must not use it.",
+      "if": { "type": "object" },
+      "then": { "type": "object", "propertyNames": { "pattern": "^[^$]" } }
+    },
+
+    "Bounds": {
+      "title": "Bounds",
+      "description": "An inclusive [lower, upper] pair. Both bounds SHOULD be of the same type.",
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 2,
+      "items": { "$ref": "#/$defs/OrderedOperand" },
+      "examples": [[10, 20], ["2023-01-01", "2023-12-31"]]
+    },
+
+    "OperandSet": {
+      "title": "Operand set",
+      "description": "A non-empty list of distinct values. Servers MAY cap its length; see SPEC.md §7.",
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/Operand" },
+      "examples": [["red", "green", "blue"], [1, 2, 3]]
+    },
+
+    "SizeConstraint": {
+      "title": "Size constraint",
+      "description": "An exact array length, or a comparison on that length.",
+      "anyOf": [
+        { "type": "integer", "minimum": 0 },
+        {
+          "type": "object",
+          "minProperties": 1,
+          "properties": {
+            "$eq": { "type": "integer", "minimum": 0 },
+            "$ne": { "type": "integer", "minimum": 0 },
+            "$gt": { "type": "integer", "minimum": 0 },
+            "$gte": { "type": "integer", "minimum": 0 },
+            "$lt": { "type": "integer", "minimum": 0 },
+            "$lte": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        }
+      ],
+      "examples": [3, { "$gte": 1 }]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@open-predicate/open-predicate",
+  "version": "0.6.0",
+  "description": "OpenPredicate — an open standard for JSON-encoded, SQL-flavoured predicates, described by a single JSON Schema: $ref it from OpenAPI, or inline it into an MCP tool's inputSchema.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Christos Gkoros",
+  "contributors": [
+    "OpenPredicate (https://openpredicate.tech)"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OpenPredicate/open-predicate.git"
+  },
+  "homepage": "https://github.com/OpenPredicate/open-predicate#readme",
+  "bugs": {
+    "url": "https://github.com/OpenPredicate/open-predicate/issues"
+  },
+  "keywords": [
+    "open-predicate",
+    "openpredicate",
+    "predicate",
+    "json-schema",
+    "openapi",
+    "query-language",
+    "filter",
+    "search",
+    "mcp",
+    "model-context-protocol",
+    "agents",
+    "llm-tools",
+    "http-query-method"
+  ],
+  "main": "open-predicate-schema.json",
+  "bin": {
+    "open-predicate-generate": "tools/generate-filter-schema.mjs"
+  },
+  "exports": {
+    ".": "./open-predicate-schema.json",
+    "./open-predicate-schema.json": "./open-predicate-schema.json",
+    "./generate": "./tools/generate-filter-schema.mjs"
+  },
+  "files": [
+    "open-predicate-schema.json",
+    "tools/",
+    "SPEC.md",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "generate": "node tools/generate-filter-schema.mjs",
+    "generate:example": "node tools/generate-filter-schema.mjs --config examples/pet.open-predicate.config.json",
+    "example:mcp": "node examples/mcp-server/server.mjs",
+    "example:mcp:demo": "node examples/mcp-server/demo.mjs",
+    "test:experiment": "node --test experiments/filter-to-sql/compile.test.mjs",
+    "experiment": "node experiments/filter-to-sql/run.mjs"
+  },
+  "devDependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}