How json-schema-org/json-schema-spec works
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)