# jsonata-js/jsonata architecture

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

- Interactive diagram: https://gitdiagram.com/jsonata-js/jsonata
- Repository: https://github.com/jsonata-js/jsonata

## Overview

##### Project type and purpose
- JSONata is a reference implementation of a JSON query & transformation language.
- It can be embedded in Node.js or browsers.
- It provides a parser, evaluator, built-in function library, and a small polyfill for older JS environments.
- It ships docs and a static website as part of the repo.

##### File structure
Top-level components:
- src/           → core modules
– jsonata.js   → public API entry
– parser.js    → converts expression strings to AST
– signature.js → builds the evaluation signature tree
– functions.js → registry for all built-in functions
– datetime.js  → date/time library
– utils.js     → shared utilities
- polyfill.js    → ES feature polyfills
- test/          → test harness and JSONata conformance suites
- docs/          → Markdown reference docs
- website/       → Docusaurus-style static site
- package.json, bower.json → build & distribution configs

##### Key points from the README
- “Require('jsonata')” or “<script src='jsonata.min.js'>”
- expression.evaluate(data) asynchronously returns results
- Extensive language docs live on docs.jsonata.org
- repo contains both code & documentation sources

##### Main components and relationships
A. External Clients
– Node.js applications
– Browser applications
↳ both import the same UMD bundle (jsonata.min.js) which may include polyfill.js
B. Public API Facade (src/jsonata.js)
– Exposes jsonata() factory → Expression object
C. Parser (src/parser.js)
– Parses expression text → produces AST
D. Signature Builder (src/signature.js)
– Converts AST → internal “signature tree” for evaluation
E. Evaluator & Runtime
– Walks signature tree → invokes built-in functions
– Uses functions.js & datetime.js for built-in behavior
– Utils.js provides generic helpers (e.g., deep-equals)
F. Built-in Function Registry (src/functions.js)
– Registers each “$sum”, “$filter”, etc.
G. Polyfill Layer (polyfill.js)
– Provides compatibility (e.g., Promise in older browsers)
H. Test Harness (test/run-test-suite.js)
– Loads test/test-suite data & runs parser + evaluator → conformance results
I. Documentation & Website
– docs/ Markdown guides → website/ static site generator → published docs

##### Architectural patterns & design principles
- Modularized: parser, signature, evaluator are separate
- Pluggable Parser: regex-based, can replace regex engine
- Functional: built-ins are pure and registered centrally
- UMD build: works in Node, AMD, browser globals

##### Side Subsystems
- Test Harness:
– Loads AST & signature, runs conformance tests against datasets
- Documentation Pipeline:
– docs/ + versioned_docs/ → static site in website/

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External Clients"
        direction TB
        NodeJS["Node.js"]:::external
        Browser["Browser"]:::external
    end

    Configs["Build & Distribution\n(package.json, bower.json)"]:::util
    Configs -->|"build"| UMD["UMD Bundle\n(polyfill.js + jsonata.min.js)"]:::core

    NodeJS -->|import jsonata| UMD
    Browser -->|<script src>| UMD

    UMD -->|"jsonata() factory"| API["Public API Facade"]:::core
    API -->|"expression text"| Parser["Parser Module"]:::core
    Parser -->|produces| AST["AST"]:::data
    AST -->|"AST"| Signature["Signature Builder"]:::core
    Signature -->|produces| SigTree["Signature Tree"]:::data
    SigTree -->|"data + signature"| Evaluator["Evaluator Module"]:::core

    Evaluator -->|invokes| Functions["Built-in Function Registry"]:::lib
    Evaluator -->|invokes| DateTime["Date/Time Library"]:::lib
    Evaluator -->|uses helpers| Utils["Shared Utilities"]:::util

    Evaluator -->|result| Result["Result"]:::data
    Result -->|returns| NodeJS
    Result -->|returns| Browser

    subgraph "Test Pipeline"
        direction TB
        TH["Test Harness"]:::side
        TS["Test Suites"]:::side
        TH -->|loads| TS
        TS -->|runs parser+evaluator| TH
        TH -->|conformance results| Result
    end

    subgraph "Documentation Pipeline"
        direction TB
        DocsSrc["Reference Docs"]:::side
        StaticSite["Static Website"]:::side
        VersionDocs["Versioned Docs"]:::side
        DocsSrc --> StaticSite
        VersionDocs --> StaticSite
    end

    click API "https://github.com/jsonata-js/jsonata/blob/master/src/jsonata.js"
    click Parser "https://github.com/jsonata-js/jsonata/blob/master/src/parser.js"
    click Signature "https://github.com/jsonata-js/jsonata/blob/master/src/signature.js"
    click Functions "https://github.com/jsonata-js/jsonata/blob/master/src/functions.js"
    click DateTime "https://github.com/jsonata-js/jsonata/blob/master/src/datetime.js"
    click Utils "https://github.com/jsonata-js/jsonata/blob/master/src/utils.js"
    click UMD "https://github.com/jsonata-js/jsonata/blob/master/polyfill.js"
    click TH "https://github.com/jsonata-js/jsonata/blob/master/test/run-test-suite.js"
    click TS "https://github.com/jsonata-js/jsonata/tree/master/test/test-suite/"
    click DocsSrc "https://github.com/jsonata-js/jsonata/tree/master/docs/"
    click StaticSite "https://github.com/jsonata-js/jsonata/tree/master/website/"
    click VersionDocs "https://github.com/jsonata-js/jsonata/tree/master/website/versioned_docs/"
    click Configs "https://github.com/jsonata-js/jsonata/blob/master/package.json"

    classDef core fill:#d0e1f9,stroke:#4a6785
    classDef lib fill:#d0f0d0,stroke:#2e7d32
    classDef util fill:#e0e0e0,stroke:#616161
    classDef data fill:#f9e2d0,stroke:#d45d00
    classDef side fill:#fde4b9,stroke:#f57c00
    classDef external fill:#e1f5fe,stroke:#0288d1
```
