{"id":16717352,"url":"https://github.com/nathanreb/ppx_yojson","last_synced_at":"2025-08-28T12:11:03.637Z","repository":{"id":41953224,"uuid":"151492112","full_name":"NathanReb/ppx_yojson","owner":"NathanReb","description":"OCaml PPX extension for JSON literals and patterns","archived":false,"fork":false,"pushed_at":"2024-03-11T14:23:59.000Z","size":133,"stargazers_count":42,"open_issues_count":2,"forks_count":5,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-04T00:41:22.581Z","etag":null,"topics":["ezjsonm","json","ocaml","ppx-extension","ppx-rewriter","yojson"],"latest_commit_sha":null,"homepage":"","language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NathanReb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-03T23:08:25.000Z","updated_at":"2025-01-19T11:28:56.000Z","dependencies_parsed_at":"2024-03-11T15:45:35.808Z","dependency_job_id":null,"html_url":"https://github.com/NathanReb/ppx_yojson","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/NathanReb/ppx_yojson","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NathanReb%2Fppx_yojson","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NathanReb%2Fppx_yojson/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NathanReb%2Fppx_yojson/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NathanReb%2Fppx_yojson/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NathanReb","download_url":"https://codeload.github.com/NathanReb/ppx_yojson/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NathanReb%2Fppx_yojson/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272496923,"owners_count":24944597,"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","status":"online","status_checked_at":"2025-08-28T02:00:10.768Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["ezjsonm","json","ocaml","ppx-extension","ppx-rewriter","yojson"],"created_at":"2024-10-12T21:31:36.519Z","updated_at":"2025-08-28T12:11:03.589Z","avatar_url":"https://github.com/NathanReb.png","language":"OCaml","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ppx_yojson\n\nPPX extension for JSON literals and patterns. It supports `yojson` and\n`ezjsonm`.\n\nBased on an original idea by [@emillon](https://github.com/emillon).\n\n[![Build Status](https://img.shields.io/endpoint?url=https%3A%2F%2Fci.ocamllabs.io%2Fbadge%2FNathanReb%2Fppx_yojson%2Fmain\u0026logo=ocaml)](https://ocaml.ci.dev/github/NathanReb/ppx_yojson)\n\n## Overview\n\n`ppx_yojson` lets you write `Yojson` or `Ezjsonm` expressions and patterns\nusing ocaml syntax to make your code more concise and readable.\n\nIt rewrites `%yojson` and `%ezjsonm` extension points based on the content of\nthe payload.\n\nFor example you can turn:\n```ocaml\nlet json =\n  `List\n    [ `Assoc\n        [ (\"name\", `String \"Anne\")\n        ; (\"grades\", `List [`String \"A\"; `String \"B-\"; `String \"B+\"]\n        ]\n    ; `Assoc\n        [ (\"name\", `String \"Bernard\")\n        ; (\"grades\", `List [`String \"B+\"; `String \"A\"; `String \"B-\"]\n        ]\n    ]\n```\n\ninto:\n```ocaml\nlet json =\n  [%yojson\n    [ {name = \"Anne\"; grades = [\"A\"; \"B-\"; \"B+\"]}\n    ; {name = \"Bernard\"; grades = [\"B+\"; \"A\"; \"B-\"]}\n    ]\n  ]\n```\n\n## Installation and usage\n\nYou can install `ppx_yojson` using [opam](https://opam.ocaml.org/):\n```\n$ opam install ppx_yojson\n```\n\nIf you're building your library or app with dune, add the following field to\nyour `library`, `executable` or `test` stanza:\n```\n(preprocess (pps ppx_yojson))\n```\n\nYou can now use the `%yojson` or `%ezjsonm` extensions in your code. See the\n[expressions](https://github.com/NathanReb/ppx_yojson#expressions) and\n[patterns](https://github.com/NathanReb/ppx_yojson#patterns) sections for the\ndetailed syntax.\n\n## Syntax\n\n### Expressions\n\nThe expression rewriter supports the following `Yojson` and `Ezjsonm` values:\n- `Null`: `[%yojson None]` or `[%ezjsonm None]`\n- `Bool of bool`: `[%yojson true]` or `[%ezjsonm true]`\n- `Float of float`: `[%yojson 1.2e+10]` or `[%ezjsonm 1.2e+10]`. Note that with\n  `%ezjsonm` all numeric literals are converted to `Float of float`.\n- `Int of int`: `[%yojson 0xff]`. As long as the int literal in the payload fits in an `int`,\n  the `0x`, `0o` and `0b` notations are accepted.\n- `Intlit of string`: `[%yojson 100000000000000000000000000000000]`. For arbitrary long integers.\n  `int64`, `int32` and `nativeint` literals are also rewritten as `Intlit` for consistency with\n  `ppx_deriving_yojson`.\n  `0x`, `0o` and `0b` notations are currently not supported and the rewriter will raise an error.\n- `String of string`: `[%yojson \"abc\"]` or `[%ezjsonm \"abc\"]`\n- `List of json list`: `[%yojson [1; 2; 3]]`. It supports mixed type list as well such as\n  `[\"a\"; 2]`.\n- `A of value list`: `[%ezjsonm [\"a\"; 2]]`\n- `Assoc of (string * json) list`: `[%yojson {a = 1; b = \"b\"}]`\n- `O of (string * value) list`: `[%ezjsonm {a = 1; b = \"b\"}]`\n- Any valid combination of the above\n\nThe resulting expression are not constrained, meaning it works with\n`Yojson.Safe` or `Yojson.Basic` regardless.\n\n#### Anti-quotation\n\nYou can escape regular `Yojson` or `Ezjsonm` expressions within a payload using\n`[%aq json_expr]`. You can use this to insert variables in the payload. For\nexample:\n\n```ocaml\nlet a = `String \"a\"\nlet json = [%yojson { a = [%aq a]; b = \"b\"}]\n```\nis rewritten as:\n```ocaml\nlet a = `String \"a\"\nlet json = `Assoc [(\"a\", a); (b, `String \"b\")]\n```\nNote that the payload in a `%aq` extension should always subtype one of the `Yojson` types.\n\n### Patterns\n\nNote that the pattern extension expects a pattern payload and must thus be invoked as\n`[%yojson? pattern]` or `[%ezjsonm? pattern]`.\n\nThe pattern rewriter supports the following:\n- `Null`, `Bool of bool`, `Float of float`, `Int of int`, `Intlit of string`,\n  `String of string`, `List of json list` with the same syntax as for\n  expressions and will be rewritten to a pattern matching that json value.\n- `Assoc of (string * json) list` and `O of (string * value) list` with the same\n  syntax as for expressions but with a few restrictions. The record pattern in\n  the payload must be closed (ie no `; _}`) and have less than 4 fields. See\n  details below.\n- Var patterns: they are just rewritten as var patterns meaning they will bind\n  to a `Ezjsonm.value`, `Yojson.Safe.json` or whatever `Yojson` type you're\n  using that's compatible with the above.\n- The wildcard pattern: it gets rewritten as, well, a wildcard pattern\n- Any valid combination of the above\n\n#### Record patterns\n\nJson objects fields order doesn't matter so you'd expect the `{a = 1; b = true}` pattern to match\nregardless of the parsed json being `{\"a\": 1, \"b\": true}` or `{\"b\": true, \"a\": 1}`.\n\nSince json objects are represented as lists, the order of the fields in the rewritten pattern does\nmatter.\n\nTo allow you to write such patterns concisely and without having to care for the order of the\nfields, the record pattern is expanded to an or-pattern that matches every permutation of the\n`(string * json) list`. This is the reason of the limitations mentioned in the above list.\nAlso note that there is no limitation on nesting such patterns but you probably want to avoid doing\nthat too much.\n\nThis is provided mostly for convenience. If you want efficient code and/or to handle complex json\nobjects I recommend that you use\n[`ppx_deriving_yojson`](https://github.com/ocaml-ppx/ppx_deriving_yojson) or\n[`ppx_yojson_conv`](https://github.com/janestreet/ppx_yojson_conv) instead.\n\nTo clarify, the following code:\n```ocaml\nlet f = function\n  | [%yojson? {a = 1; b = true}] -\u003e (1, true)\n```\n\nis expanded into:\n```ocaml\nlet f = function\n  | ( `Assoc [(\"a\", `Int 1); (\"b\", `Bool true)]\n    | `Assoc [(\"b\", `Bool true); (\"a\", `Int 1)]\n    ) -\u003e (1, true)\n```\n\n#### Anti-quotation\n\nYou can also escape regular `Ezjsonm` or `Yojson` patterns in `ppx_yojson` pattern\nextensions' payload using `[%aq? json_pat]`. You can use it to further\ndeconstruct a JSON value. For example:\n\n```ocaml\nlet f = function\n  | [%yojson? {a = [%aq? `Int i]} -\u003e i + 1\n```\n\nis expanded into:\n```ocaml\nlet f = function\n  | `Assoc [(\"a\", `Int i)] -\u003e i + 1\n```\n\n### Advanced use\n\n#### Object keys\n\nSome valid JSON object key's name are not valid OCaml record fields. Any\ncapitalized word or OCaml keyword such as `type` or `object`.\n\nYou can still assemble such JSON literals with `ppx_yojson` using a leading\nunderscore in the record field name. It will strip exactly one leading\nunderscore.\n\nFor example, the following:\n```ocaml\nlet json = [%yojson { _type = \"a\"; __object = \"b\"}]\n```\n\nwill be expanded to:\n```ocaml\nlet json = `Assoc [(\"type\", `String \"a\"); (\"_object\", `String \"b\")]\n```\n\nAlternatively, you can attach an `[@as \"key_name\"]` attribute to the relevant\nfield to provide the key to use in the JSON object literal.\n\nThe following:\n```ocaml\nlet json = [%yojson {dummy = \"a\" [@as \"type\"]; some_key = \"b\"}\n```\n\nwill be expanded to:\n```ocaml\nlet json = `Assoc [(\"type\", `String \"a\"); (\"some_key\", `String \"b\")]\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnathanreb%2Fppx_yojson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnathanreb%2Fppx_yojson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnathanreb%2Fppx_yojson/lists"}