# cveproject/cve-schema architecture

> Architecture diagram of the GitHub repository cveproject/cve-schema, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cveproject/cve-schema
- Repository: https://github.com/cveproject/cve-schema

## Overview

##### Main components
a. Schema Artifacts
- schema/CVE_Record_Format.json (latest schema)
- schema/archive (historical versions)
- schema/imports (shared CVSS definitions)
- schema/tags (tag definitions)
b. Support & Tooling
- support/Python3.x_Validator (D7Validator.py + CVSS JSON)
- support/Node_Validator (build.js, validate.js, dist/cve5validator.js)
- support/CVE_4_to_5_converter (cve4to5up.py, mapping files)
- support/schema2markmap (JS scripts to generate mindmap)
- support/qualityReport (report.js for coverage/quality)
- tools/ (ad hoc scripts like cmdlinejsonvalidator.py, mitre-cna-assignment-info.js)
c. Documentation Pipeline
- schema/docs (HTML, CSS, examples, mindmap)
- schema/archive/vX.X/docs (version-specific docs)
d. CI/CD
- .github/workflows/validate-schema.yml (GitHub Actions schema validation)

##### Relationships & data flows
- Schema files import shared CVSS definitions → feed into validators.
- Python3.x_Validator and Node_Validator consume schema bundles and produce pass/fail reports.
- CVE_4_to_5_converter reads older v4 schemas → outputs v5 schema artifacts.
- schema2markmap reads JSON Schema → emits mindmap HTML.
- qualityReport aggregates test coverage from validators and scripts.
- CI workflow triggers on push/PR → runs all validators, conversion tests, docs build verifications.
- Final artifacts (bundled JSON, HTML docs, mindmaps) published to GitHub Pages or npm.
- External consumers (CVE Services, CNAs, ADPs) pull the released bundled schema and docs.

##### Architectural patterns & design principles
- Monorepo structure grouping schemas, tools, and docs.
- Separation of concerns:
– Data (schemas & imports)
– Validation (Node, Python)
– Conversion (v4→v5)
– Documentation (schema2markmap, static HTML)
- Reuse: shared CVSS definitions imported by all versions.
- Versioning: historical archives alongside the canonical “latest.”
- CI-driven quality gate: GitHub Actions ensures every PR maintains schema validity.

##### Relevant technologies & frameworks
- JSON Schema (draft-07 or later)
- Node.js (build.js, validate.js, schema2markmap)
- Python 3.x (D7Validator)
- GitHub Actions (YAML workflows)
- Static site assets (HTML/CSS for docs and mindmap)
- Perl & custom scripts in tools/ for ad hoc conversions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Schemas
    subgraph "Schema Artifacts"
        direction TB
        LatestSchema["CVE_Record_Format.json"]:::data
        Archives["Historical Schemas (archive/)"]:::data
        Imports["Shared CVSS Definitions (imports/)"]:::data
        Tags["Tag Definitions (tags/)"]:::data
    end

    %% Support & Tooling
    subgraph "Support & Tooling"
        direction TB
        PythonValidator["Python3.x Validator"]:::tool
        NodeValidator["Node.js Validator"]:::tool
        CVEConverter["CVE 4→5 Converter"]:::tool
        Schema2Mindmap["Schema→Mindmap Generator"]:::tool
        QualityReport["Quality Report Aggregator"]:::tool
        MiscTools["Miscellaneous Scripts (tools/)"]:::tool
    end

    %% Documentation Pipeline
    subgraph "Documentation Pipeline"
        direction TB
        CurrentDocs["Current Docs (schema/docs/)"]:::data
        VersionedDocs["Versioned Docs (archive/v5.0/docs/)"]:::data
    end

    %% CI/CD
    subgraph "CI/CD"
        direction TB
        CI["GitHub Actions Workflow"]:::ci
    end

    %% External
    subgraph "External Consumers"
        direction TB
        Consumers["CVE Services / CNAs / ADPs"]:::external
    end

    %% Relationships
    Imports -->|"import definitions"| LatestSchema
    LatestSchema -->|validate| PythonValidator
    LatestSchema -->|validate| NodeValidator
    Archives -->|convert v4→v5| CVEConverter
    LatestSchema -->|generate docs| Schema2Mindmap
    PythonValidator -->|report| QualityReport
    NodeValidator -->|report| QualityReport
    CVEConverter -->|output v5 schema| LatestSchema
    Schema2Mindmap -->|generate HTML/mindmap| CurrentDocs
    Schema2Mindmap -->|generate HTML/mindmap| VersionedDocs
    QualityReport -->|aggregate metrics| CurrentDocs
    QualityReport -->|aggregate metrics| VersionedDocs
    CI -->|trigger validation| PythonValidator
    CI -->|trigger validation| NodeValidator
    CI -->|trigger conversion| CVEConverter
    CI -->|trigger docs build| Schema2Mindmap
    CI -->|trigger quality report| QualityReport
    CurrentDocs -->|"publish artifacts"| Consumers
    VersionedDocs -->|"publish artifacts"| Consumers
    MiscTools -->|ad hoc scripts| QualityReport

    %% Click Events
    click LatestSchema "https://github.com/cveproject/cve-schema/blob/main/schema/CVE_Record_Format.json"
    click Archives "https://github.com/cveproject/cve-schema/tree/main/schema/archive/"
    click Imports "https://github.com/cveproject/cve-schema/tree/main/schema/imports/cvss/"
    click Tags "https://github.com/cveproject/cve-schema/tree/main/schema/tags/"
    click PythonValidator "https://github.com/cveproject/cve-schema/blob/main/schema/support/Python3.x_Validator/D7Validator.py"
    click NodeValidator "https://github.com/cveproject/cve-schema/tree/main/schema/support/Node_Validator/"
    click CVEConverter "https://github.com/cveproject/cve-schema/blob/main/schema/support/CVE_4_to_5_converter/cve4to5up.py"
    click Schema2Mindmap "https://github.com/cveproject/cve-schema/blob/main/schema/support/schema2markmap/index.js"
    click QualityReport "https://github.com/cveproject/cve-schema/blob/main/schema/support/qualityReport/report.js"
    click MiscTools "https://github.com/cveproject/cve-schema/tree/main/tools/"
    click CurrentDocs "https://github.com/cveproject/cve-schema/tree/main/schema/docs/"
    click VersionedDocs "https://github.com/cveproject/cve-schema/tree/main/schema/archive/v5.0/docs/"
    click CI "https://github.com/cveproject/cve-schema/blob/main/.github/workflows/validate-schema.yml"

    %% Styles
    classDef data fill:#D0E6FF,stroke:#005FB8,stroke-width:1px
    classDef tool fill:#DFF2D8,stroke:#27632A,stroke-width:1px
    classDef ci fill:#FFE0B2,stroke:#B35900,stroke-width:1px
    classDef external fill:#F2F2F2,stroke:#666666,stroke-width:1px
```
