# json-schema-org/json-schema-spec architecture

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

- Interactive diagram: https://gitdiagram.com/json-schema-org/json-schema-spec
- Repository: https://github.com/json-schema-org/json-schema-spec

## Overview

##### Project Type and Purpose
- This repository is a *documentation and specification build system* for the next set of JSON Schema IETF Internet Drafts.
- It is *not* a runtime application but a *static-site generator* / *doc-pipeline* that:
- Transforms Markdown spec sources into HTML (for the website) and JSON schemas.
- Builds IETF Internet-Draft XML via a Python toolchain.
- Enforces markdown style, link validation, and code highlighting via Remark plugins.

##### High-Level Architecture
A. Source Inputs
- “specs/” directory: Markdown source files, JSON meta files, registry XML.
- “adr/” directory: Architectural decision records.
- Configuration files:
– remarkrc, eslint.config.js, .gitignore, Makefile, package.json, requirements.in.
- Plugin code: “remark/” folder with custom Remark plugins.
B. Build Orchestrators
1. Node.js Toolchain
– package.json scripts (“npm run build -- specs”)
– Uses Remark + rehype pipelines, plus custom plugins to generate:
- HTML files → “web/” folder
- Auxiliary JSON outputs → “specs/output/”
2. Python Toolchain (IETF Internet-Drafts)
– Makefile target “make”
– Creates a .venv, installs xml2rfc (via pip-compile requirements.in)
– Converts XML or Markdown sources into I-D XML RFC drafts
C. Continuous Integration
- GitHub Actions workflows (.github/workflows/ci.yml, etc.)
- Linting, build checks, security checks, minimum open-time bots

##### Key Architectural Patterns
- *Plugin Architecture:* Core markdown engine (Remark) extended via small, focused plugins in “remark/”.
- *Polyglot Build:* Node + Python toolchains, orchestrated by Makefile & npm scripts.
- *Separation of Concerns:*
- Content (specs/, adr/) vs. build logic (remark/, Makefile, package.json) vs. output (web/, specs/output/).
- *Immutable Sources:* Spec sources are immutable Markdown/JSON; outputs are derived artifacts.

##### Components & Interactions (to illustrate
[Source Repo]
|
|— specs/ (Markdown + JSON meta)
|— adr/ (Markdown decisions)
|— remark/ (JS plugins)
|— config files (package.json, Makefile, requirements.in, .remarkrc.js)
|
v
[Node.js Build Process] — loads → remark/ plugins + .remarkrc → processes specs/ →
|
|—> HTML pages → web/
|—> JSON outputs → specs/output/
v
[Python Build Process] — via Makefile → .venv → xml2rfc →
|
|—> IETF Internet-Draft XML artifacts
v
[Artifacts & Deployment]
- HTML in web/ → deployed to json-schema.org
- XML drafts → submitted to IETF or archived
[CI/CD (GitHub Actions)] monitors pushes/PRs, runs lint/build, reports status

##### Essential Elements to Capture
- Clear, hierarchical layering:
1) Source
2) Build orchestration
3) Generated artifacts
4) Deployment / submission
- Labels for key config entry points (Makefile, npm scripts, remarkrc, requirements.in)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source Layer
    subgraph "Source Repositories"
        direction TB
        Spec["specs/"]:::source
        ADR["adr/"]:::source
        remarkDir["remark/"]:::source
        subgraph "Remark Plugins"
            direction TB
            linkTransformer["rehype-link-transformer.js"]:::source
            codeTitles["remark-code-titles.js"]:::source
            headings["remark-headings.js"]:::source
            referenceLinks["remark-reference-links.js"]:::source
            toc["remark-table-of-contents.js"]:::source
        end
        subgraph "Remark Configuration"
            direction TB
            rrcRoot[".remarkrc.js"]:::source
            rrcLint[".remarkrc-lint.js"]:::source
            rrcBuild["specs/.remarkrc-build.js"]:::source
            rrcSpecs["specs/.remarkrc-specs.js"]:::source
            rrcSpecsRoot["specs/.remarkrc.js"]:::source
        end
        subgraph "Node.js Configuration"
            direction TB
            pkg["package.json"]:::source
            lock["package-lock.json"]:::source
            eslintCfg["eslint.config.js"]:::source
        end
        subgraph "Python Configuration"
            direction TB
            mf["Makefile"]:::source
            reqIn["requirements.in"]:::source
            reqTxt["requirements.txt"]:::source
        end
        subgraph "CI Configuration"
            direction TB
            ci1[".github/workflows/ci.yml"]:::ci
            ci2[".github/workflows/minimum-open-time.yml"]:::ci
            ci3[".github/workflows/pr-dependencies.yml"]:::ci
        end
    end

    %% Build Processes
    NodeBuild["Node.js Build Process"]:::build
    PythonBuild["Python Build Process"]:::build
    CI["GitHub Actions CI/CD"]:::ci

    %% Outputs
    HTML["web/ (HTML)"]:::output
    JSONOut["specs/output/ (JSON)"]:::output
    XMLOut["I-D XML Artifacts"]:::output
    DeploymentWeb["json-schema.org deployment"]:::external
    DeploymentIETF["IETF submission/archive"]:::external

    %% Data Flows
    Spec -->|provides markdown/json| NodeBuild
    ADR -->|provides ADR markdown| NodeBuild
    remarkDir -->|loads plugins| NodeBuild
    linkTransformer --> NodeBuild
    codeTitles --> NodeBuild
    headings --> NodeBuild
    referenceLinks --> NodeBuild
    toc --> NodeBuild
    rrcRoot --> NodeBuild
    rrcLint --> NodeBuild
    rrcBuild --> NodeBuild
    rrcSpecs --> NodeBuild
    pkg --> NodeBuild
    lock --> NodeBuild
    eslintCfg --> NodeBuild

    NodeBuild -->|generate HTML| HTML
    NodeBuild -->|generate JSON| JSONOut

    MFTrigger["Makefile target"]:::build --> PythonBuild
    PythonBuild -->|create .venv & run xml2rfc| XMLOut

    HTML --> DeploymentWeb
    XMLOut --> DeploymentIETF

    CI -->|on push/PR| NodeBuild
    CI -->|on push/PR| PythonBuild

    %% Click Events
    click Spec "https://github.com/json-schema-org/json-schema-spec/tree/main/specs/"
    click ADR "https://github.com/json-schema-org/json-schema-spec/tree/main/adr/"
    click remarkDir "https://github.com/json-schema-org/json-schema-spec/tree/main/remark/"
    click linkTransformer "https://github.com/json-schema-org/json-schema-spec/blob/main/remark/rehype-link-transformer.js"
    click codeTitles "https://github.com/json-schema-org/json-schema-spec/blob/main/remark/remark-code-titles.js"
    click headings "https://github.com/json-schema-org/json-schema-spec/blob/main/remark/remark-headings.js"
    click referenceLinks "https://github.com/json-schema-org/json-schema-spec/blob/main/remark/remark-reference-links.js"
    click toc "https://github.com/json-schema-org/json-schema-spec/blob/main/remark/remark-table-of-contents.js"
    click rrcRoot "https://github.com/json-schema-org/json-schema-spec/blob/main/.remarkrc.js"
    click rrcLint "https://github.com/json-schema-org/json-schema-spec/blob/main/.remarkrc-lint.js"
    click rrcBuild "https://github.com/json-schema-org/json-schema-spec/blob/main/specs/.remarkrc-build.js"
    click rrcSpecs "https://github.com/json-schema-org/json-schema-spec/blob/main/specs/.remarkrc-specs.js"
    click rrcSpecsRoot "https://github.com/json-schema-org/json-schema-spec/blob/main/specs/.remarkrc.js"
    click pkg "https://github.com/json-schema-org/json-schema-spec/blob/main/package.json"
    click lock "https://github.com/json-schema-org/json-schema-spec/blob/main/package-lock.json"
    click eslintCfg "https://github.com/json-schema-org/json-schema-spec/blob/main/eslint.config.js"
    click mf "https://github.com/json-schema-org/json-schema-spec/tree/main/Makefile"
    click reqIn "https://github.com/json-schema-org/json-schema-spec/blob/main/requirements.in"
    click reqTxt "https://github.com/json-schema-org/json-schema-spec/blob/main/requirements.txt"
    click ci1 "https://github.com/json-schema-org/json-schema-spec/blob/main/.github/workflows/ci.yml"
    click ci2 "https://github.com/json-schema-org/json-schema-spec/blob/main/.github/workflows/minimum-open-time.yml"
    click ci3 "https://github.com/json-schema-org/json-schema-spec/blob/main/.github/workflows/pr-dependencies.yml"

    %% Styles
    classDef source fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef build fill:#D2F8D2,stroke:#28a745,color:#155724
    classDef output fill:#FFE0B2,stroke:#e65100,color:#e65100
    classDef ci fill:#E1D5E7,stroke:#6f42c1,color:#381085
    classDef external fill:#F0F0F0,stroke:#999,stroke-dasharray: 5 5,color:#333
```
