{"id":15814461,"url":"https://github.com/mufeedvh/okjson","last_synced_at":"2025-04-01T18:31:02.075Z","repository":{"id":57448495,"uuid":"476006302","full_name":"mufeedvh/okjson","owner":"mufeedvh","description":"A fast, simple, and pythonic JSON Schema Validator.","archived":false,"fork":false,"pushed_at":"2023-08-22T21:09:44.000Z","size":90,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-04-14T09:04:36.801Z","etag":null,"topics":["json","jsonschema","jsonschema-python-library","jsonschema-validator","schema","security","validation","validation-library"],"latest_commit_sha":null,"homepage":"","language":"Python","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/mufeedvh.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}},"created_at":"2022-03-30T18:34:37.000Z","updated_at":"2023-06-30T21:37:52.000Z","dependencies_parsed_at":"2022-09-18T12:30:55.387Z","dependency_job_id":"95adefce-b757-46bf-83ad-7a10ea45f3a4","html_url":"https://github.com/mufeedvh/okjson","commit_stats":{"total_commits":15,"total_committers":1,"mean_commits":15.0,"dds":0.0,"last_synced_commit":"c613354dd06cda7ffec5f7fe80b18ff28b7eb530"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mufeedvh%2Fokjson","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mufeedvh%2Fokjson/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mufeedvh%2Fokjson/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mufeedvh%2Fokjson/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mufeedvh","download_url":"https://codeload.github.com/mufeedvh/okjson/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246386587,"owners_count":20768847,"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":["json","jsonschema","jsonschema-python-library","jsonschema-validator","schema","security","validation","validation-library"],"created_at":"2024-10-05T04:40:37.410Z","updated_at":"2025-04-01T18:31:01.772Z","avatar_url":"https://github.com/mufeedvh.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n    \u003ch1\u003e{ \u003ccode\u003eokjson\u003c/code\u003e }\u003c/h1\u003e\n    \u003cp\u003eA fast, simple, and pythonic JSON Schema Validator\u003c/p\u003e\n    \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e • \u003ca href=\"#install\"\u003eInstall\u003c/a\u003e • \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e • \u003ca href=\"#benchmarks\"\u003eBenchmarks\u003c/a\u003e • \u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\n\u003c/div\u003e\n\n## Install\n\n```\n$ pip install okjson==0.1.1\n```\n\n**⚠️ NOTE:** This library has not been battle-tested, please don't use this in production. yet.\n\n## Features\n\n- **Simplicity:** The schema definition is pythonic in the sense that you can directly specify the expected data type with the corresponding keyword (type hints). This is inspired by the design of [tiangolo/sqlmodel](https://github.com/tiangolo/sqlmodel).\n- **Performance:** Just 250ish lines of simple and optimized code, performs better than the alternatives simply because it does relatively less work. It also uses [orjson](https://github.com/ijl/orjson) under the hood for serialization if you're providing a raw JSON string as input.  (See [Benchmarks](#benchmarks))\n- **Composability:** You can write your own validation function for values, all it has to do is return `True` on a valid input just like the `regex` example below. (See [Usage](#every-feature-in-a-single-example))\n- **Options:** The `max_size_in_bytes` option allows you to prevent processing large payloads (in web/network scenarios) and you can opt out of data type validation with the `loosely_typed` option.\n- **Helpful Error Messages:** The `validate()` function prints out helpful exception messages for easier debugging.\n\n## Usage\n\n### A basic example showing how the library works:\n\nFor simple schemas where you just want to validate if the structure and data type of the values match, use the `is_valid()` method.\n\n```py\nfrom okjson import JSONValidator\n\nschema = { 'name': str, 'age': int }\n\njson_string = '{ \"name\": \"Charly Gordon\", \"age\": 32 }'\n\nassert JSONValidator().is_valid(instance=json_string, schema=schema)\n```\n\n### Every feature in a single example:\n\nFor any schema that includes inner dictonaries/lists or cusom validation functions, use the `validate()` method instead. This method also has well defined error messages for each exception cases.\n\n**Tip:** Just like how the regex match function is utilized in this example, you can compose any function, all that's required is that it returns `True` if it passes the validation.\n\n```py\nfrom okjson import JSONValidator\nfrom typing import Union\n\nimport re\nemail_regex = re.compile(r'\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b')\n\nschema = {\n    'email': email_regex.match, # the value of `email` should match to the compiled email regex above\n    'password': str, # password is of type `str`\n    'user': {\n        'token': str, # token is of type `str`\n        'badges': [str], # this list can only contain `str` elements\n        'values': [Union[str, float]] # this list can contain both `str` and `float` elements\n    }\n}\n\njson_string = \"\"\"\n{\n    \"email\": \"test@mail.com\",\n    \"password\": \"hunter2\",\n    \"user\": {\n        \"token\": \"d08f46c929b5098b61105fdf6e24d014\",\n        \"badges\": [\"OG\"],\n        \"values\": [\"test\", 69.420]\n    }\n}\n\"\"\"\n\nassert JSONValidator().validate(instance=json_string, schema=schema)\n```\n\n### Validating against a large schema:\n\nGot a large schema to make? Just call the `create_schema()` function on a valid JSON file that follows the desired schema.\n\n**⚠️ NOTE:** This currently does not validate nested dictionaries!\n\n```py\nfrom okjson import JSONValidator\n\n# a valid/expected format of JSON\nexpected_valid_json = open('tests/twitter.json', 'r').read()\n\n# create a schema with it\nexpected_valid_schema = JSONValidator().create_schema(expected_valid_json)\n\n# validate `instances` with the created schema\nassert JSONValidator().validate(instance=expected_valid_json, schema=expected_valid_schema)\n```\n\n### Extra options for validation:\n\n```py\nassert JSONValidator(\n    max_size_in_bytes=1000, # payload shouldn't exceed 1000 bytes\n    loosely_typed=False # types should be checked (strongly typed)\n).validate(instance=json_string, schema=schema)\n```\n\n**What's the difference between methods `is_valid()` and `validate()`?**\n\nThe `is_valid()` function only checks for the schema structure for correctness thus faster than `validate()`. The `validate()` function checks the schema structure along with the configurable options and handles exceptions with verbose error messages. There is no drastic performance difference betwen the two. Both are significantly fast in comparison to other schema validation libraries.\n\n**NOTE:** You can also pass in the result of `json.loads()` for the `instance` value instead of the raw JSON string.\n\n## Benchmarks\n\n\u003e **NOTE:** This is not an \"apples to apples\" comparison since this library works entirely differently to that of the ones in comparison here. Both of the other libraries are an implementation of the [JSON Schema Specification](https://json-schema.org/). However, this library serves the exact same purpose with a simpler solution with more composability (callable custom functions for example) and performance benefits.\n\n```\n$ python3 benchmarks/benchmarks.py\n[-] Basic Bench okjson `is_valid()` 1000 runs: 0.004736766999485553\n[-] Basic Bench okjson `validate()` 1000 runs: 0.007322061999730067\n[-] Basic Bench jsonschema 1000 runs: 1.4104747559995303\n[-] Basic Bench fastjsonschema 1000 runs: 0.5503115159999652\n\nokjson is 116x faster than fastjsonschema\nfastjsonschema is 2x faster than jsonschema\n\n[-] okjson `is_valid()` example 1000 runs: 0.0018266600000060862\n[-] okjson `validate()` example 1000 runs: 0.0020380820005811984\n[-] jsonschema example 1000 runs: 1.1857670320005127\n[-] fastjsonschema example 1000 runs: 0.3467409430004409\n\nokjson is 189x faster than fastjsonschema\nfastjsonschema is 3x faster than jsonschema\n```\n\n## Contribution\n\nWays to contribute:\n\n- Suggest a feature\n- Report a bug\n- Fix something and open a pull request\n- Help me document the code\n- Spread the word\n\n## License\n\nLicensed under the MIT License, see \u003ca href=\"https://github.com/mufeedvh/okjson/blob/master/LICENSE\"\u003eLICENSE\u003c/a\u003e for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmufeedvh%2Fokjson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmufeedvh%2Fokjson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmufeedvh%2Fokjson/lists"}