ChartSpec

At a Glance

Why

Traditional charting libraries couple visual definitions with rendering logic, making visualizations hard to version, review, and reuse across different contexts.

Benefit

Separates chart specifications from rendering, enabling charts to be defined declaratively, versioned in git, and rendered in any compatible environment.

For

Data analysts, visualization engineers, and teams who need reproducible, versionable chart definitions that can be reviewed and deployed independently of rendering code.

Use

Define charts using JSON/YAML specifications, version them in source control, and render them using the ChartSpec renderer in your application or workflow.

Architecture

Context Diagram

How ChartSpec interacts with users and data sources:

┌─────────────────────────────────────────────────────────────┐
│                    Data Analyst / Dev                       │
│              (creates chart specifications)                 │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        │ writes/maintains
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                  Chart Specification                        │
│                   (JSON/YAML files)                         │
│  • Data source config                                       │
│  • Visual encodings                                         │
│  • Interaction definitions                                  │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        │ consumed by
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                     ChartSpec                               │
│                 (specification engine)                      │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Parser     │  │  Validator   │  │   Renderer   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        │ fetches
                        ▼
                ┌──────────────┐
                │ Data Sources │
                │ (APIs, DBs)  │
                └──────────────┘

Internal Architecture

Components inside ChartSpec:

┌─────────────────────────────────────────────────────────────┐
│                      ChartSpec Core                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌───────────────────────────────────────────────────┐     │
│  │          Specification Parser                     │     │
│  │  • Reads JSON/YAML definitions                    │     │
│  │  • Schema validation                              │     │
│  │  • Resolves references                            │     │
│  └───────────────┬───────────────────────────────────┘     │
│                  │                                          │
│                  ▼                                          │
│  ┌───────────────────────────────────────────────────┐     │
│  │           Transformation Layer                    │     │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐        │     │
│  │  │   Data   │  │  Visual  │  │  Scale   │        │     │
│  │  │Transform │  │ Encoding │  │ Mapping  │        │     │
│  │  └──────────┘  └──────────┘  └──────────┘        │     │
│  └───────────────┬───────────────────────────────────┘     │
│                  │                                          │
│                  ▼                                          │
│  ┌───────────────────────────────────────────────────┐     │
│  │            Rendering Engine                       │     │
│  │  • SVG generation                                 │     │
│  │  • Canvas rendering                               │     │
│  │  • Interactive layer                              │     │
│  └───────────────────────────────────────────────────┘     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

How to Use

1. Install ChartSpec Add to your project: npm install @gitbrainlab/chartspec
2. Create a chart specification Define your chart in a JSON or YAML file with data source, visual encodings, and interaction rules.
3. Validate the specification Use the ChartSpec validator to ensure your specification is correct and complete.
4. Render the chart Import and render: chartspec.render(spec, targetElement) to display your visualization.
5. Version and iterate Commit your spec files to version control and iterate on visualizations through code review.

Related Projects