{"id":18488322,"url":"https://github.com/mojotech/json-type-validation","last_synced_at":"2025-06-19T05:10:27.307Z","repository":{"id":37752269,"uuid":"119089949","full_name":"mojotech/json-type-validation","owner":"mojotech","description":"TypeScript JSON type validation","archived":false,"fork":false,"pushed_at":"2023-07-14T16:07:32.000Z","size":758,"stargazers_count":156,"open_issues_count":29,"forks_count":14,"subscribers_count":33,"default_branch":"master","last_synced_at":"2025-06-01T08:13:03.882Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/mojotech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-01-26T18:47:48.000Z","updated_at":"2025-02-18T00:32:59.000Z","dependencies_parsed_at":"2024-06-18T13:59:32.035Z","dependency_job_id":"bcbcfcbe-6f0f-42fa-aab5-d13894df0880","html_url":"https://github.com/mojotech/json-type-validation","commit_stats":{"total_commits":85,"total_committers":8,"mean_commits":10.625,"dds":"0.15294117647058825","last_synced_commit":"091844b153c2c17355230efa6d6cf44dce6fb56b"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/mojotech/json-type-validation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mojotech%2Fjson-type-validation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mojotech%2Fjson-type-validation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mojotech%2Fjson-type-validation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mojotech%2Fjson-type-validation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mojotech","download_url":"https://codeload.github.com/mojotech/json-type-validation/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mojotech%2Fjson-type-validation/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259340837,"owners_count":22843058,"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-06T12:51:33.841Z","updated_at":"2025-06-19T05:10:22.277Z","avatar_url":"https://github.com/mojotech.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# JSON Type Validation\n\nA [TypeScript](https://www.typescriptlang.org/) library to perform type checking and validation on untyped JSON data at runtime.\n\nThis library owes thanks to:\n\n- [JsonDecoder](https://github.com/aische/JsonDecoder) by Daniel van den Eijkel\n- [Type-safe JSON Decoder](https://github.com/ooesili/type-safe-json-decoder) by Wesley Merkel\n- The Elm [Json.Decode](http://package.elm-lang.org/packages/elm-lang/core/latest/Json-Decode) API\n\n## Installation\n```\nnpm i @mojotech/json-type-validation\n```\nProjects using `\u003c typescript@3.0.1` will need a polyfill for the `unknown`\ntype, such as [unknown-ts](https://www.npmjs.com/package/unknown-ts).\n\n## Motivation\n\nLet's say we're creating a web app for our pet sitting business, and we've\npicked TypeScript as one of our core technologies. This is a great choice\nbecause the extra stability and type safety that TypeScript provides is really\ngoing to help us market our business.\n\nWe've defined the data we need to track about each client's pet:\n\n```typescript\ninterface Pet {\n  name: string;\n  species: string;\n  age?: number;\n  isCute?: boolean;\n}\n```\n\nAnd we've got some data about current client's pets which is stored as JSON:\n\n```typescript\nconst croc: Pet = JSON.parse('{\"name\":\"Lyle\",\"species\":\"Crocodile\",\"isCute\":true}')\nconst moose: Pet = JSON.parse('{\"name\":\"Bullwinkle\",\"age\":59}')\n```\n\nBut that can't be right -- our data for `moose` is missing information required\nfor the `Pet` interface, but TypeScript compiles the code just fine!\n\nOf course this isn't an issue with TypeScript, but with our own type\nannotations. In TypeScript `JSON.parse` has a return type of `any`, which pushes\nthe responsibility of verifying the type of data onto the user. By assuming that\nall of our data is correctly formed, we've left ourselves open to unexpected\nerrors at runtime.\n\nUnfortunately TypeScript doesn't provide a good built-in way to deal with this\nissue. Providing run-time type information is one of TypeScript's\n[non-goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals#non-goals),\nand our web app is too important to risk using a forked version of TypeScript\nwith that added functionality.\n[Type guards](https://basarat.gitbooks.io/typescript/docs/types/typeGuard.html)\nwork, but are limited in that they circumvent type inference instead of working\nwith it, and can be cumbersome to write.\n\nWith `json-type-validation` we can define decoders that validate untyped json\ninput. Decoders are concise, composable, and typecheck against our defined types\nand interfaces.\n\n```typescript\nimport {Decoder, object, string, optional, number, boolean} from '@mojotech/json-type-validation'\n\nconst petDecoder: Decoder\u003cPet\u003e = object({\n  name: string(),\n  species: string(),\n  age: optional(number()),\n  isCute: optional(boolean())\n})\n```\n\nFinally, we can choose from a number of decoding methods to validate json and\nreport success or failure. When some json input fails validation the decoder\nclearly shows how the data was malformed.\n\n```typescript\nconst lyle: Pet = petDecoder.runWithException(croc)\n\nconst bullwinkle: Pet = petDecoder.runWithException(moose)\n// Throws the exception:\n// `Input: {\"name\":\"Bullwinkle\",\"age\":59}\n//  Failed at input: the key 'species' is required but was not present`\n```\n\n## Documentation\n\n[Documentation](https://github.com/mojotech/json-type-validation/tree/master/docs).\n\n## Building\n\n### With Nix\n\nThere exists some [Nix](https://nixos.org/nix) infrastructure that can be used\nto reproduce a build environment exactly. A helper shell script lives at\n`bin/jtv` that you can use to enter environments for multiple uses.\nYou'll need to follow the directions on the Nix website to install and use the\nNix package manager.\n\n* To enter a shell suitable for building the library run `./bin/jtv\n  build-shell`. This will leave you in the root of the project and automatically\n  install any project and npm dependencies. You can run further yarn commands\n  here.\n* To build the library for distribution and exit you can run `./bin/jtv distribute`.\n* To enter a build shell and run the build process, watching for changes, run\n  `./bin/jtv build-watch`.\n* To run an arbitrary command in a build environment use `./bin/jtv run\n  COMMAND`. For example, `./bin/jtv run yarn test` will run the tests and exit.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmojotech%2Fjson-type-validation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmojotech%2Fjson-type-validation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmojotech%2Fjson-type-validation/lists"}