How python-openapi/openapi-spec-validator works
Project type and purpose
• This is an open-source Python library/tool that provides:
• A CLI (and Docker image) for validating OpenAPI specs (v2.0, v3.0.x, v3.1)
• A pre-commit hook integration
• A core Python package (openapi_spec_validator) exposing a programmatic API
• Primary use case: take an OpenAPI document (YAML/JSON), parse it, detect its version, validate it against the corresponding specification schema, and report compliance errors.
File–structure highlights
• Top level
• .github/, docs/, tests/, CI & publishing configs, Dockerfile, Makefile
• Core package: openapi_spec_validator/
• readers.py – read file or STDIN, return spec dict + base URI
• versions/ – version‐detection & dispatch (finders.py, shortcuts.py)
• resources/schemas/ – embedded JSON Schema files for each OpenAPI version
• validation/ – validation engine: keyword validators, proxies, registries, caches
• exceptions.py – all custom exception types
• shortcuts.py – convenience API (e.g. high-level validate())
• Tests: tests/integration/… exercising end-to-end CLI and library calls
Architecture summary
• Main components:
A. Input layer
– CLI entrypoint (__main__.py)
– Pre-commit hook integration (entrypoint via console_scripts)
– Docker wrapper
B. Reader
– Accepts filepath or STDIN
– Parses YAML/JSON → Python dict
– Resolves relative $ref bases
C. Version dispatcher
– Inspects openapi or swagger field
– Selects the right version verifier
D. Validation engine
– Loads JSON Schema from resources/schemas/<version>/schema.json
– Uses jsonschema (and internal helpers) with:
• validation.validators (keyword‐by‐keyword rules)
• validation.proxies & decorators (plugin/registry pattern)
• validation.caches (to dedupe repeated sub‐schema resolves)
– Emits successes or raises OpenAPIValidationError exceptions
E. Shortcuts & API
– validate() function that wraps reader + dispatcher + engine
– Exposes Python API for embedding in other tools
F. External interfaces
– Pre-commit hook YAML invoking CLI
– Docker image in container registry
– CI workflows for publishing/test
Final checklist
• All major components and subcomponents represented
• Schemas and validator plugins shown as inputs to the engine
• API (shortcuts) clearly separate from CLI
• External integration points (pre-commit, Docker) illustrated