{"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":"en","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,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}