# python-openapi/openapi-spec-validator architecture

> Architecture diagram of the GitHub repository python-openapi/openapi-spec-validator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/python-openapi/openapi-spec-validator
- Repository: https://github.com/python-openapi/openapi-spec-validator

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input Layer
    subgraph "Input Layer"
        direction TB
        CLI["CLI Entrypoint"]:::io
        Hook["Pre-commit Hook"]:::io
        Docker["Docker Wrapper"]:::io
    end

    %% Core Pipeline
    subgraph "Core Library" 
        direction TB
        Reader["Reader"]:::core
        Dispatcher["Version Dispatcher"]:::core
        Engine["Validation Engine"]:::core

        Reader -->|"spec dict"| Dispatcher
        Dispatcher -->|"version info"| Engine

        subgraph "Validation Engine Internals"
            direction TB
            Schemas["JSON Schemas"]:::resource
            Validators["Keyword Validators"]:::core
            Proxies["Proxy Adapters"]:::core
            Decorators["Plugin Registry"]:::core
            Caches["Caching Layer"]:::core
            Protocols["Protocols & Types"]:::core
            Exceptions["Engine Exceptions"]:::core

            Schemas --> Engine
            Validators --> Engine
            Proxies --> Engine
            Decorators --> Engine
            Caches --> Engine
            Protocols --> Engine
            Exceptions --> Engine
        end
    end

    %% API Surface
    Shortcuts["Shortcuts & Public API"]:::api

    %% External Flow
    CLI --> Reader
    Hook --> Reader
    Docker --> Reader
    Engine -->|"result or exception"| Shortcuts

    %% Tests & Docs
    subgraph "Supporting Components"
        direction TB
        Tests["Integration Tests"]:::test
        Docs["Documentation (Sphinx)"]:::test
    end

    Tests --> Shortcuts
    Docs --- Shortcuts

    %% Click Events
    click CLI "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/__main__.py"
    click Hook "https://github.com/python-openapi/openapi-spec-validator/blob/master/.pre-commit-hooks.yaml"
    click Docker "https://github.com/python-openapi/openapi-spec-validator/tree/master/Dockerfile"
    click Reader "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/readers.py"
    click Dispatcher "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/versions/finders.py"
    click Dispatcher "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/versions/shortcuts.py"
    click Dispatcher "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/versions/consts.py"
    click Dispatcher "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/versions/datatypes.py"
    click Dispatcher "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/versions/exceptions.py"
    click Caches "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/validation/caches.py"
    click Decorators "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/validation/decorators.py"
    click Exceptions "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/validation/exceptions.py"
    click Validators "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/validation/keywords.py"
    click Proxies "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/validation/proxies.py"
    click Decorators "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/validation/registries.py"
    click Protocols "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/validation/protocols.py"
    click Protocols "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/validation/types.py"
    click Validators "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/validation/validators.py"
    click Schemas "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/resources/schemas/v2.0/schema.json"
    click Schemas "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/resources/schemas/v3.0/schema.json"
    click Schemas "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/resources/schemas/v3.0.0/schema.json"
    click Schemas "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/resources/schemas/v3.1/schema.json"
    click Exceptions "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/exceptions.py"
    click Shortcuts "https://github.com/python-openapi/openapi-spec-validator/blob/master/openapi_spec_validator/shortcuts.py"
    click Tests "https://github.com/python-openapi/openapi-spec-validator/tree/master/tests/integration/"

    %% Styles
    classDef io fill:#FFD58A,stroke:#333,stroke-width:1px
    classDef core fill:#8FD175,stroke:#333,stroke-width:1px
    classDef resource fill:#75D8FF,stroke:#333,stroke-width:1px
    classDef api fill:#FF7E79,stroke:#333,stroke-width:1px
    classDef test fill:#D3D3D3,stroke:#333,stroke-width:1px
```
