{"id":21455510,"url":"https://github.com/hookdeck/simple-json-match","last_synced_at":"2025-10-15T17:55:45.781Z","repository":{"id":55276730,"uuid":"315776659","full_name":"hookdeck/simple-json-match","owner":"hookdeck","description":"Lightweight, no dependencies library to evaluate match with a JSON document values with a simple JSON based  syntax.","archived":false,"fork":false,"pushed_at":"2024-10-23T12:14:23.000Z","size":168,"stargazers_count":7,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-09T22:35:59.286Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hookdeck.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-24T23:24:25.000Z","updated_at":"2024-10-23T12:14:28.000Z","dependencies_parsed_at":"2022-08-14T19:02:59.476Z","dependency_job_id":null,"html_url":"https://github.com/hookdeck/simple-json-match","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/hookdeck/simple-json-match","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hookdeck%2Fsimple-json-match","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hookdeck%2Fsimple-json-match/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hookdeck%2Fsimple-json-match/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hookdeck%2Fsimple-json-match/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hookdeck","download_url":"https://codeload.github.com/hookdeck/simple-json-match/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hookdeck%2Fsimple-json-match/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264664517,"owners_count":23646399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-23T05:12:27.836Z","updated_at":"2025-10-15T17:55:40.751Z","avatar_url":"https://github.com/hookdeck.png","language":"TypeScript","readme":"# simple-json-match\n\n[slack-badge]: https://img.shields.io/badge/Slack-Hookdeck%20Developers-blue?logo=slack\n\n[![slack-badge]](https://join.slack.com/t/hookdeckdevelopers/shared_invite/zt-yw7hlyzp-EQuO3QvdiBlH9Tz2KZg5MQ)\n\n`simple-json-match` library to evaluate match a JSON document values with a simple syntax.\n\nIt was designed to be used within [hookdeck.com](https://hookdeck.com) filtering engine and provides for a simple method for users to input their desired filter.\n\nThis is not a full schema validation library like `json-schema` instead its goal is to provide a simple straitforward syntax to evalute match between values rather then type.\n\n# Install\n\n```\nnpm install simple-json-match\n```\n\n```\nyarn add simple-json-match\n```\n\nTypescript definitions are provided within the package.\n\n# Getting Started\n\n`simple-match-json` exports a single method to evaluate the match between a JSON document and the input schema.\n\n```js\nimport matchJSONToSchema from 'simple-json-match';\n\nconst product = {\n  id: 123,\n  title: 'A product',\n};\n\nconst schema = {\n  id: 123,\n};\n\nmatchJSONToSchema(product, schema); // true\n```\n\n# Supported Types\n\nmatchJSONToSchema supports raw `string` `boolean` `number` or `null` and the library Schema JSON syntax.\n\n```js\nmatchJSONToSchema(true, true); // true\n```\n\n```js\nmatchJSONToSchema(true, false); // false\n```\n\n```js\nmatchJSONToSchema({ test: true }, { test: false }); // false\n```\n\n# Schema Syntax\n\nJSON filter supports matching on any value (`string` `number` `boolean` `null`), on nested objects and on arrays.\n\n### Simple primitives\n\nSimple primitive are `string`, `number`, `boolean` or `null` that will be matched if equal.\n\n```js\nconst product = {\n  type: 'order/created',\n  order: {\n    id: 123,\n  },\n};\n\nconst schema = {\n  type: 'order/created',\n};\n\nmatchJSONToSchema(product, schema); // true\n```\n\n### Nested Objects\n\nJust like normal JSON, objects can be nested\n\n```js\nconst product = {\n  product: {\n    title: 'A product',\n    inventory: 0,\n  },\n};\n\nconst schema = {\n  product: {\n    inventory: 0,\n  },\n};\n\nmatchJSONToSchema(product, schema); // true\n```\n\n### Arrays\n\nArrays are always matched partially. It's effectively the same as `contains`\n\n```js\nconst product = {\n  product: {\n    title: 'Gift Card',\n    tags: ['gift', 'something'],\n  },\n};\n\nconst schema = {\n  product: {\n    tags: 'gift',\n  },\n};\n\nmatchJSONToSchema(product, schema); // true\n```\n\nYou can also match multiple items (they must all be contained)\n\n```js\nconst product = {\n  product: {\n    title: 'Gift Card',\n    tags: ['gift', 'something', 'another'],\n  },\n};\n\nconst schema = {\n  product: {\n    tags: ['gift', 'something'],\n  },\n};\n\nmatchJSONToSchema(product, schema); // true\n```\n\nOr even nested objects\n\n```js\nconst order = {\n  order: {\n    id: 123,\n    items: [\n      {\n        id: 456,\n        title: 'My product',\n      },\n    ],\n  },\n};\n\nconst schema = {\n  order: {\n    items: {\n      id: 456,\n    },\n  },\n};\n\nmatchJSONToSchema(order, schema); // true\n```\n\n### Operators\n\nSometimes you need more than simple a `equal` matching. Our syntax support different operators to allow for more complex matching strategies.\n\nOperators can be used as an object instead of the matching primitive (value)\n\n```js\nconst product = {\n  product: {\n    title: 'A product',\n    inventory: 5,\n  },\n};\n\nconst schema = {\n  product: {\n    inventory: {\n      $lte: 10,\n    },\n  },\n};\n\nmatchJSONToSchema(product, schema); // true\n```\n\n#### All operators\n\n| Operator    | Supported Type                           | Description                   |\n| ----------- | ---------------------------------------- | ----------------------------- |\n| $eq         | `any`                                    | Equal (or deep equal)         |\n| $neq        | `any`                                    | Not Equal (or deep not equal) |\n| $gte        | `string`,`number`                        | Greater than or equal to      |\n| $gt         | `string`,`number`                        | Greater than                  |\n| $lte        | `string`,`number`                        | Less than or equal to         |\n| $lt         | `string`,`number`                        | Less than                     |\n| $in         | `string`,`number`,`string[]`, `number[]` | Contains                      |\n| $nin        | `string`,`number`,`string[]`, `number[]` | Does not contain              |\n| $startsWith | `string`,`string[]`                      | Starts with text              |\n| $endsWith   | `string`,`string[]`                      | Ends with text                |\n| $exist      | `boolean`                                | Undefined or not undefined    |\n| $or         | `array`                                  | Array of conditions to match  |\n| $and        | `array`                                  | Array of conditions to match  |\n| $ref        | \u0026lt;field\u0026gt;                            | Reference a field             |\n| $not        | Valid syntax                             | Negation                      |\n\n### $or / $and Operator\n\nThe reference `$or` and `$and` are special operator to evaluate match with an array of conditions. For the match to be true, only one of the condition needs to match. The array of condition can contain any other valid schema supported.\n\n```js\nconst product = {\n  product: {\n    title: 'A product',\n    inventory: 5,\n  },\n};\n\nconst schema = {\n  product: {\n    inventory: {\n      $or: [1, 5],\n    },\n  },\n};\n\nmatchJSONToSchema(product, schema); // true\n```\n\n```js\nconst exmaple = {\n  \"hello\": \"world\"\n}\n\nconst schema = {\n  $or: [\n    {  \"hello\": \"johny\"}\n    {  \"hello\": \"mark\"},\n  ]\n}\n\nmatchJSONToSchema(example, schema); // false\n\n```\n\n### References\n\nThe refrence `$ref` is a special operator to reference other values in your JSON input when evaluating match. The reference input must be a `string` representing the value path. For example using this JSON input:\n\n```js\nconst example = {\n  type: 'example',\n  nested_object: {\n    hello: 'world'\n    array: [1, 2, 3]\n  }\n};\n\nconst ref1 = 'type' // example\nconst ref2 = 'type.nested_object.hello' // world\nconst ref3 = 'type.nested_object.array[1]' // 1\nconst ref3 = 'type.nested_object.array[$index]' // 1,2 or 3 depending on the current index\n```\n\n```js\nconst product = {\n  updated_at: '2020-04-20',\n  created_at: '2020-04-20',\n};\n\nconst schema = {\n  updated_at: {\n    $ref: 'created_at',\n  },\n};\n\nmatchJSONToSchema(product, schema); // true\n```\n\nYou can also reference the current array index instead of a specific index with `$index`. You can have multiple `$index` in your reference if you are dealing with nested arrays.\n\n```js\nconst input = {\n  variants: [\n    { updated_at: '2020-05-20', created_at: '2020-04-20' },\n    { updated_at: '2020-04-20', created_at: '2020-04-20' },\n  ],\n};\n\nconst schema = {\n  variants: {\n    updated_at: {\n      $ref: 'variants[$index].created_at',\n    },\n  },\n};\n\nmatchJSONToSchema(product, schema); // true\n```\n\nA reference can also be used in conjuction with other operators\n\n```js\nconst product = {\n  inventory: 0,\n  old_inventory: 10,\n};\n\nconst schema = {\n  inventory: {\n    $lte: { $ref: 'old_inventory' },\n  },\n};\n\nmatchJSONToSchema(product, schema); // true\n```\n\n### $exist operator\n\n`$exist` requires a field to be undefined when false and array, number, object, string, boolean or null when true.\n\n```js\nconst product = {\n  inventory: 0,\n};\n\nconst schema = {\n  old_inventory: {\n    $exist: false,\n  },\n};\n```\n\n### Negation operator\n\n`$not` negation of the schema.\n\n```js\nconst product = {\n  inventory: 0,\n};\n\nconst schema = {\n  $not: {\n    inventory: 1,\n  },\n};\n```\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhookdeck%2Fsimple-json-match","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhookdeck%2Fsimple-json-match","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhookdeck%2Fsimple-json-match/lists"}