{"id":2196,"library":"prance","title":"Prance","description":"Prance is a Python library that provides parsers for Swagger/OpenAPI 2.0 and 3.0 API specifications. It validates specifications using backends like `openapi_spec_validator`, `swagger_spec_validator`, or `flex`, and additionally resolves JSON references, including non-URI file paths. The current version is 25.4.8.0, and it follows a Calendar Versioning (CalVer) release cadence.","status":"active","version":"25.4.8.0","language":"python","source_language":"en","source_url":"https://github.com/RonnyPfannschmidt/prance","tags":["OpenAPI","Swagger","parser","validation","API specification"],"install":[{"cmd":"pip install prance","lang":"bash","label":"Basic Installation"},{"cmd":"pip install prance[osv,icu,cli]","lang":"bash","label":"Recommended (with OpenAPI validator, ICU, and CLI)"}],"dependencies":[{"reason":"One of the validation backends, recommended with `[osv]` extra.","package":"openapi-spec-validator","optional":true},{"reason":"An older validation backend, available with `[ssv]` extra.","package":"swagger-spec-validator","optional":true},{"reason":"A validation backend.","package":"flex","optional":true},{"reason":"For improved Unicode handling, available with `[icu]` extra. Requires system-level 'libicu-dev' or 'libicu-devel' installation.","package":"PyICU","optional":true},{"reason":"Required for Command Line Interface (CLI) functionality, available with `[cli]` extra.","package":"click","optional":true},{"reason":"Used for JSON reference resolution since version 25.04.08.0.","package":"referencing","optional":false}],"imports":[{"note":"The primary parser for specs with resolved references.","symbol":"ResolvingParser","correct":"from prance import ResolvingParser"},{"note":"For parsing specs without resolving references.","symbol":"BaseParser","correct":"from prance import BaseParser"}],"quickstart":{"code":"from prance import ResolvingParser\nimport os\n\n# Example OpenAPI/Swagger spec content (YAML format for demonstration)\n# In a real scenario, this would be loaded from a file or URL\nspec_content = \"\"\"\nopenapi: 3.0.0\ninfo:\n  title: Sample API\n  version: 1.0.0\npaths:\n  /items:\n    get:\n      summary: Get all items\n      responses:\n        '200':\n          description: A list of items\n\"\"\"\n\n# Create a dummy spec file for the example\nwith open('sample_spec.yaml', 'w') as f:\n    f.write(spec_content)\n\ntry:\n    # Initialize the parser with the path to your spec file\n    parser = ResolvingParser('sample_spec.yaml')\n\n    # The fully resolved specification is available as a dictionary\n    resolved_spec = parser.specification\n    print(f\"API Title: {resolved_spec['info']['title']}\")\n    print(f\"API Version: {resolved_spec['info']['version']}\")\n    print(\"Specification parsed successfully.\")\n\n    # Example with a URL (requires internet access)\n    # parser = ResolvingParser('http://petstore.swagger.io/v2/swagger.json')\n    # resolved_spec = parser.specification\n    # print(f\"Petstore API Title: {resolved_spec['info']['title']}\")\n\nfinally:\n    # Clean up the dummy spec file\n    if os.path.exists('sample_spec.yaml'):\n        os.remove('sample_spec.yaml')","lang":"python","description":"This quickstart demonstrates how to use `ResolvingParser` to load an OpenAPI/Swagger specification from a file (or URL) and access its fully resolved dictionary representation."},"warnings":[{"fix":"Upgrade Python environment to a supported version (e.g., 3.10 or newer, preferably 3.11+ for latest Prance).","message":"Prance version 25.04.08.0 dropped support for Python 3.8 and 3.9. It now supports Python 3.11, 3.12, and 3.14. Earlier, Python 2.7 and 3.4 support was removed in versions prior to 0.17.0.","severity":"breaking","affected_versions":"25.04.08.0 and later for 3.8/3.9 removal; 0.17.0 and later for 2.7/3.4 removal"},{"fix":"Review code that directly manipulates internal resolver components. Test thoroughly after upgrading.","message":"Version 25.04.08.0 migrated its underlying JSON reference resolution engine from `jsonschema` to `referencing`. While the public API is generally stable, advanced users directly interacting with resolver internals might experience breaking changes.","severity":"breaking","affected_versions":"25.04.08.0 and later"},{"fix":"Install Prance with the appropriate extra dependencies for your desired validation backend (e.g., `prance[osv]` for OpenAPI 3.0+ validation) and other features (e.g. `[icu]` for better Unicode handling, `[cli]` for command line tools).","message":"Prance's validation backends (`openapi-spec-validator`, `swagger-spec-validator`, `flex`) are optional dependencies. For full functionality and recommended usage, install with extras like `pip install prance[osv,icu,cli]`. If no backend is installed, validation might be limited or fail.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure any custom handling or generation of OpenAPI/Swagger specs uses the official `yaml` mimetype.","message":"Version 25.04.08.0 switched the preferred YAML mimetype from `x-yaml` to the official `yaml` form. While older forms might still be handled, it's best to use the official mimetype.","severity":"deprecated","affected_versions":"25.04.08.0 and later"},{"fix":"If strict JSON validation for HTTP status codes is required, explicitly set `backend='openapi-spec-validator'` or `backend='swagger-spec-validator'` during parser initialization, and ensure that backend is installed.","message":"As of version 0.8, Prance defaults to `flex` as the validation backend if available. Note that `flex` accepts integer status codes despite them not being valid JSON, which might lead to less strict validation than other backends. You can explicitly specify a backend in the parser constructor (e.g., `ResolvingParser(..., backend='openapi-spec-validator')`).","severity":"gotcha","affected_versions":"0.8 and later"}],"env_vars":null,"search_vec":"'2.0':12 '25.4.8.0':46 '3.0':14 'addit':32 'api':15,60 'backend':21 'cadenc':55 'calendar':51 'calver':53 'current':43 'file':40 'flex':30 'follow':49 'includ':36 'json':34 'librari':6 'like':22 'non':38 'non-uri':37 'openapi':23,56 'parser':9,58 'path':41 'pranc':1,2 'provid':8 'python':5 'refer':35 'releas':54 'resolv':33 'spec':24,27 'specif':16,19,61 'swagger':26,57 'swagger/openapi':11 'uri':39 'use':20 'valid':18,25,28,59 'version':44,52","created_at":"2026-04-09T18:47:37.374824+00:00","updated_at":"2026-04-16T18:08:00.618815+00:00","problems":[{"fix":"Install the library using pip: `pip install prance`","cause":"The 'prance' library is not installed in the Python environment being used, or the environment is not correctly activated/configured.","error":"ModuleNotFoundError: No module named 'prance'"},{"fix":"Ensure the OpenAPI/Swagger specification file is valid YAML or JSON, and check it against an online validator. Examine the full traceback for more specific details from the underlying validation backend.","cause":"The provided OpenAPI/Swagger specification file is invalid, malformed, or contains errors that prevent 'prance' from parsing or validating it. This can also be caused by the validation backend (e.g., openapi-spec-validator) raising an error.","error":"prance.ValidationError: Could not parse specifications!"},{"fix":"Verify that all '$ref' pointers correctly point to existing files or valid paths within the specification. Ensure relative paths are correct and that 'prance' has access to referenced files.","cause":"'prance' could not resolve a '$ref' reference within the OpenAPI/Swagger specification. This often happens if the referenced file or path within the file does not exist or is inaccessible.","error":"prance.util.url.ResolutionError: Unresolvable JSON pointer: '...'"},{"fix":"This specific error was reported in an old GitHub issue and might be resolved in newer versions. If encountered, ensure the input specification is valid and try updating the 'prance' library to the latest version (`pip install --upgrade prance`). If using the CLI, ensure the file is correctly formatted (YAML/JSON) and accessible.","cause":"This typically occurs when 'prance' tries to perform a string decoding operation on an object that is already a dictionary, suggesting an issue with the input spec or how it's being processed by the CLI or an internal function expecting a byte string.","error":"AttributeError: 'dict' object has no attribute 'decode'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"26.7.19.0","cli_name":"prance","cli_version":"Traceback (most recent call last):","type":"library","homepage":null,"github":"https://github.com/RonnyPfannschmidt/prance","docs":null,"changelog":null,"pypi":"https://pypi.org/project/prance/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","serialization","testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}