{"id":3525,"library":"jsonschema-spec","title":"JSONSchema Spec","description":"jsonschema-spec is a Python library (current version 0.4.5) that provides object-oriented paths for traversing and accessing JSON Schemas. It allows developers to interact with schema elements and their references in a programmatic way, abstracting away raw dictionary manipulation. The library sees active development, with frequent patch releases and minor updates to enhance features and ensure compatibility with related tools.","status":"active","version":"0.4.5","language":"en","source_language":"en","source_url":"https://github.com/p1c2u/jsonschema-spec","tags":["JSON Schema","schema traversal","object-oriented","dereferencing","API specifications"],"install":[{"cmd":"pip install jsonschema-spec","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for JSON Reference (RFC3986) and JSON Pointer (RFC6901) resolution within schemas, enabling dereferencing capabilities. Required version >=0.28.0,<1.0.0.","package":"referencing","optional":false},{"reason":"Provides the underlying pathing and traversal primitives for object-oriented schema access. Required version >=0.5.0,<1.0.0.","package":"pathable","optional":false}],"imports":[{"symbol":"SchemaPath","correct":"from jsonschema_spec import SchemaPath"},{"symbol":"SchemaAccessor","correct":"from jsonschema_spec import SchemaAccessor"}],"quickstart":{"code":"from jsonschema_spec import SchemaPath\n\n# Define a simple JSON Schema\nschema_dict = {\n    \"type\": \"object\",\n    \"properties\": {\n        \"name\": {\"type\": \"string\"},\n        \"age\": {\"type\": \"integer\", \"minimum\": 0}\n    },\n    \"$defs\": {\n        \"Person\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"firstName\": {\"type\": \"string\"},\n                \"lastName\": {\"type\": \"string\"}\n            }\n        }\n    },\n    \"$ref\": \"#/$defs/Person\"\n}\n\n# Create a SchemaPath object from the dictionary\npath = SchemaPath.from_dict(schema_dict)\n\n# Traverse the schema using path-like access\nname_prop_path = path / \"properties\" / \"name\"\nprint(f\"Name property schema: {name_prop_path.get_value()}\")\n# Expected: {'type': 'string'}\n\n# Access a definition using implicit dereferencing\nperson_def_path = path / '$defs' / 'Person'\nprint(f\"Person definition schema: {person_def_path.get_value()}\")\n# Expected: {'type': 'object', 'properties': {'firstName': {'type': 'string'}, 'lastName': {'type': 'string'}}}\n\n# Directly dereference the root '$ref'\ndereferenced_root = path.dereference()\nprint(f\"Dereferenced root schema type: {dereferenced_root.get_value()['type']}\")\n# Expected: object\n\n# Check for keys\nprint(f\"'properties' in root path: {'properties' in path}\")\n# Expected: True\n","lang":"python","description":"This quickstart demonstrates how to create a `SchemaPath` from a dictionary representing a JSON Schema and then traverse it using path-like syntax. It shows accessing properties, definitions, and performing implicit dereferencing."},"warnings":[{"fix":"Upgrade to `jsonschema-spec>=0.4.5`. Review the change log for `0.4.5` and `referencing` library updates, as this fix was introduced to restore compatibility. Adjust custom resolver implementations as per the latest `referencing` API.","message":"The `SchemaAccessor.resolver` interface underwent changes that affected backward compatibility. If you were directly interacting with or extending `SchemaAccessor.resolver` in versions prior to `0.4.5`, your code might break.","severity":"breaking","affected_versions":"<0.4.5"},{"fix":"Enable the cache by setting `resolved_cache_maxsize` when creating `SchemaPath` or `SchemaAccessor` instances. For example: `SchemaPath.from_dict(schema_dict, resolved_cache_maxsize=64)`.","message":"The resolved-path cache, which can significantly improve performance for repeated schema lookups, is disabled by default. For performance-critical applications with frequent schema path traversals, enabling this cache is highly recommended.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always specify the `$schema` keyword in your JSON Schemas to indicate the intended draft version (e.g., `\"$schema\": \"https://json-schema.org/draft/2020-12/schema\"`). Be aware of the specific changes between drafts (e.g., `$recursiveRef` to `$dynamicRef`, `items` array form) when working with schemas from different specifications.","message":"While `jsonschema-spec` provides robust schema traversal, the underlying JSON Schema specification itself has introduced breaking changes between its different drafts (e.g., Draft 2019-09 to Draft 2020-12). These changes can alter the interpretation and validation behavior of schemas, even if `jsonschema-spec` correctly parses the structure.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}