{"id":10102,"library":"pyjsg","title":"Python JSON Schema Grammar Interpreter","description":"pyjsg (Python JSON Schema Grammar interpreter) is a library that allows defining JSON schemas as Python classes and validating data against these generated structures. It provides tools to convert JSON Schema definitions into Python objects, facilitating type-safe data handling and validation within Python applications. The current stable version is 0.12.3, with releases occurring as features and bug fixes are implemented, typically not on a fixed schedule.","status":"active","version":"0.12.3","language":"en","source_language":"en","source_url":"https://github.com/hsolbrig/pyjsg","tags":["json","schema","grammar","validation","data-modeling"],"install":[{"cmd":"pip install pyjsg","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"JSG","correct":"from pyjsg.jsg import JSG"},{"symbol":"JSG_DUMP","correct":"from pyjsg.jsg import JSG_DUMP"},{"symbol":"JSG_LOAD","correct":"from pyjsg.jsg import JSG_LOAD"},{"symbol":"JSGValidate","correct":"from pyjsg.validate import JSGValidate"}],"quickstart":{"code":"from pyjsg.jsg import JSG, JSG_DUMP\nfrom pyjsg.validate import JSGValidate\n\n# Define a JSON Schema using pyjsg decorators\n@JSG(\n    jsg_name=\"Person\",\n    jsg_uri=\"http://example.com/Person.jsg\",\n    jsg_description=\"A simple person schema\"\n)\nclass Person:\n    name: str\n    age: int\n    isStudent: bool = False # Optional with default\n\n# Example data\nvalid_person_data = {\"name\": \"Alice\", \"age\": 30}\ninvalid_person_data = {\"name\": \"Bob\", \"age\": \"twenty\"}\n\n# Create a validator instance\nvalidator = JSGValidate(Person)\n\n# Validate valid data\ntry:\n    validated_person = validator.validate(valid_person_data)\n    print(f\"Valid person: {validated_person}\")\n    # Access validated data as a pyjsg object\n    print(f\"Name: {validated_person.name}, Age: {validated_person.age}, Is Student: {validated_person.isStudent}\")\n    print(f\"Dumped valid person: {JSG_DUMP(validated_person)}\")\nexcept Exception as e:\n    print(f\"Validation failed for valid data: {e}\")\n\n# Validate invalid data\ntry:\n    validator.validate(invalid_person_data)\n    print(\"Invalid person data somehow passed validation.\")\nexcept Exception as e:\n    print(f\"Validation correctly failed for invalid data: {e}\")","lang":"python","description":"This quickstart defines a simple 'Person' JSON Schema using `pyjsg` decorators, creates a validator, and demonstrates validating both valid and invalid data against it. It also shows how to access the validated data as a Python object and dump it back to a dictionary."},"warnings":[{"fix":"Review `pyjsg`'s supported JSON Schema features and adjust your schema accordingly. Consider breaking down complex schemas or using `pyjsg` for the core data structures and a more generic validator for auxiliary constraints.","message":"pyjsg interprets a subset of JSON Schema. Complex or non-standard JSON Schemas may not translate directly into `pyjsg` Python classes or validate as expected.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always pin `pyjsg` to an exact version in `requirements.txt` (e.g., `pyjsg==0.12.3`). Review release notes carefully when upgrading. Consult the latest documentation for updated API usage.","message":"As a 0.x.x library, `pyjsg` may introduce breaking changes in minor versions (e.g., 0.11 to 0.12). API signatures, especially around schema definition and validation, can change.","severity":"breaking","affected_versions":"0.x.x series"},{"fix":"Work with the `pyjsg` generated Python objects directly when possible. If you need to manipulate raw dictionaries, ensure they conform to the schema and re-validate or re-instantiate through the `pyjsg` class if you intend to continue using `pyjsg`'s type safety.","message":"`pyjsg` generates Python classes from schemas. Direct manipulation of the raw `dict` output from `JSG_DUMP` or `JSG_LOAD` may lose type safety or fail validation if not re-instantiated through `pyjsg` classes.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Refactor your schema to use `properties` or `additionalProperties` where possible, or handle `patternProperties` validation outside of `pyjsg`.","cause":"The JSON Schema keyword `patternProperties` or similar advanced features are not directly supported by `pyjsg`'s class generation mechanism.","error":"pyjsg.jsg.JSGException: Unknown type or attribute in schema: 'patternProperties'"},{"fix":"Ensure your input data's types strictly adhere to the types specified in your `pyjsg` schema (e.g., `int`, `str`, `bool`). Convert data to the correct type before validation.","cause":"Input data does not match the expected type defined in the `pyjsg` schema for a specific field.","error":"pyjsg.validate.ValidationFailed: Value '...' does not conform to schema '...': Path: '$.age'. Expected type int, got str."},{"fix":"Check if the field exists (e.g., `hasattr(obj, 'field')`) or ensure your schema defines all necessary fields and their optionality/defaults. Accessing non-existent fields without defaults will raise an `AttributeError`.","cause":"Attempting to access a field on a `pyjsg` object that was not part of the original validated input and doesn't have a default value in the schema.","error":"AttributeError: 'Person' object has no attribute 'missing_field'"}]}