Generator Architecture

The schema generator turns the Schema.org JSON-LD vocabulary into typed code, helpers, and validation assets. This document outlines the moving parts so you can safely extend the pipeline.

Entry points

• src/generator/utils.ts handles downloading the canonical Schema.org vocabulary and splitting it into curated JSON files under src/schema/data/.
• src/generator/generate.ts orchestrates the full build by first ensuring the data files exist (writeFiles) and then invoking src/generator/generateSchema.ts.

Data ingest

1. writeFiles() checks src/schema/data/schema.json. If absent, it fetches the latest vocabulary from https://schema.org/version/latest/schemaorg-all-https.jsonld and caches it locally.
2. The Extractors (extractDatatypes, extractClasses, extractProperties, extractOtherTypes) split the graph into dedicated JSON files.

Graph rendering

src/generator/generateSchema.ts builds an in-memory graph using @avensio/graph:

• Each Schema.org class becomes a Vertex annotated with its identifier.
• Properties join the graph with metadata that powers validator emission.
• A VertexEmitter coordinates renderers from src/renderers/index.ts to create class definitions, creators, and validator modules.

The emitter writes code fragments into temporary buffers (FILE_CHUNKS) so multiple renderers can contribute to the same output file before anything touches the filesystem.

Output and post-processing

• Buffered files flush to dist/ with normalized newlines.
• validationCoreSrc/validationCoreTypes seed shared helpers under dist/validation/.
• writeIndexFiles() generates re-export barrels and type aggregators for classes and validators.
• writePrimitiveDatatypeStubsAndValidators() adds the branded primitive bindings (Number, Text, etc.).
• copyAssets() copies package metadata plus the raw schema data into the distribution so consumers can inspect the bundled snapshot.

Extending the pipeline

1. Add data: drop new JSON fragments under src/schema/data/ or enrich the download/split logic in utils.ts.
2. Add renderers: register a new emitter function inside src/renderers/index.ts to create additional file types.
3. Adjust outputs: update helper writers in src/generator/helpers.ts if new folders or manifest data are needed.

Always finish modifications with:

pnpm run generate:schema   # regenerates schema data + dist/
pnpm test -- --run

These commands ensure dist/ reflects the current generator logic and that the published artifacts remain in sync with the raw schema snapshot.