Concept Browser

A statically deployable single-page application for browsing terminology datasets. Built with Vue 3, TypeScript, and Tailwind CSS. Add new datasets with zero code changes — just configure site-config.yml.

Current version: v0.7.67 — see the v3.1 release announcement for what’s new across the ecosystem.

Live sites:

• GeoLexica — IEC Electropedia + ISO/TC 211 + more
• VIML — OIML International Vocabulary of Legal Metrology
• OIML Terms — OIML G 18 terminology

Features

• Multi-dataset browsing — Concepts from multiple terminology registers in one place
• Full multilingual support — Definitions, notes, and examples in all available languages with i18n UI
• Concept history timeline — Review dates, decisions, and change notes per language
• 3D relation sphere — Interactive sphere visualization of a concept’s neighborhood using d3 force simulation, with per-relationship-type colors and degree filtering
• Edition series — Sidebar timeline for vocabulary edition groups (e.g. VIML 1968/2000/2013/2022) with current-edition markers and supersession chain navigation
• Cross-reference graph — D3 force-directed graph showing concept relationships with dataset filtering
• Dataset groups — Organize datasets into lineage series, topic bundles, publication families, or curated collections; each group kind has distinct sidebar rendering
• Per-dataset color theming — { light, dark } color pairs per dataset, plus per-relationship-type colors configurable via site-config.yml
• RDF / SHACL outputs — Every concept emits SHACL-conformant Turtle + JSON-LD; dataset-level dcat:Dataset, group-level dcat:DatasetSeries/dcat:Catalog, vocabulary SKOS ConceptSchemes, bibliography dcterms:BibliographicResource, build provenance prov:Activity
• Rich sidebar provenance — Publication reference, owner, status, concept/language counts, and a sections tree derived from the manifest
• Sections tree — Hierarchical navigation mirroring the dataset’s register.yaml sections, with transitive membership
• Math rendering — KaTeX rendering for AsciiMath notation in definitions (stem:[...])
• Responsive design — Mobile-first layout with light/dark mode
• Static deployment — No server required. Deploy to any static host

Quick Start (deployment repo)

A deployment repo provides a site-config.yml, dataset source files, and content pages. The concept-browser is installed as an npm package.

# In your deployment repo:
npm install --ignore-scripts @glossarist/concept-browser
npm install --prefix node_modules/@glossarist/concept-browser sharp 2>/dev/null || true
npx concept-browser build

The CLI reads site-config.yml from the working directory, fetches/generates data, and builds the SPA into dist/.

Quick Start (development)

git clone https://github.com/glossarist/concept-browser.git
cd concept-browser
npm install
npm run dev
# Open http://localhost:5173

The dev server serves pre-built data from public/data/. If no data is present yet, run the data pipeline first.

CLI Reference

concept-browser <command> [options]

Commands:
  fetch      Fetch/update datasets (from GCR packages, local paths, or source repos)
  generate   Convert harmonized YAML concepts to JSON-LD static files + RDF artifacts
  edges      Build cross-reference edges from generated concept data
  about      Compile per-dataset and per-group about pages
  build      Full pipeline: fetch + generate + edges + about + vite build
  site       Same as build (alias)
  doctor     Run diagnostic checks (node version, deps, shapes, data integrity)
  normalize  NFC-normalize YAML concept files in-place

Options:
  --site <id>  Site config ID (looks for site-config.yml in CWD)

Environment:
  SITE_CONFIG    Site config file path (highest priority)
  SITE_ID        Site config ID (same as --site)
  GITHUB_TOKEN   GitHub token for private repos

Data Pipeline

site-config.yml
  └─> scripts/fetch-datasets.mjs       (fetch from GCR, localPath, or sourceRepo)
      └─> .datasets/{id}/concepts/*.yaml
          └─> scripts/generate-data.mjs (YAML → JSON-LD + RDF artifacts)
              └─> public/data/{id}/
                  ├── manifest.json      Dataset metadata (ref, owner, stats)
                  ├── index.json         Concept listing (chunked for large sets)
                  ├── edges.json         Pre-computed cross-reference + domain edges
                  ├── domain-nodes.json  Domain classification nodes
                  ├── {register}.ttl     Dataset-level RDF (dcat:Dataset + skos:ConceptScheme + sections)
                  ├── bib.ttl            Bibliography graph (dcterms:BibliographicResource)
                  └── concepts/*.json    Individual concept documents
              └─> public/data/_vocab.ttl    Vocabulary graph (SKOS ConceptSchemes)
              └─> public/data/activity/    Build provenance (prov:Activity per build)
              └─> public/data/agents.ttl   Contributor records (foaf:Person)
              └─> public/data/versions.ttl Version chain (prov:Entity)
          └─> scripts/build-edges.js    (extract graph + domain edges)

Configuration: site-config.yml

All configuration lives in a single file. The CLI reads it from the current working directory.

id: viml                                # Site identifier
domain: viml.oiml.info                  # Primary domain
basePath: /oiml-viml/                   # URL subpath for GitHub Pages deployment
title: VIML                             # Site title
subtitle: International Vocabulary...   # Short description
description: Terminology from...        # Longer description

uiLanguages:                            # Available UI languages
  - eng
  - fra

datasets:
  - id: vim-2022
    sourceRepo: https://github.com/...
    ref: "OIML V 1:2022"
    owner: OIML
    color: { light: "#6366f1", dark: "#818cf8" }
    languageOrder: [eng, fra, rus]
    tags: [metrology]

groups:
  - id: vim-editions
    kind: lineage                       # lineage | topic | publisher | curated
    members: [vim-1993, vim-2007, vim-2012, vim-2022]
    title: "VIM Edition Series"

relationTypeColors:
  broader:        { light: "#3b82f6", dark: "#60a5fa" }
  narrower:       { light: "#ef4444", dark: "#f87171" }
  exact_match:    { light: "#10b981", dark: "#34d399" }

Adding a new dataset requires zero code changes — just add an entry and rebuild.

Dataset groups

Four group kinds cover the common organizational patterns:

Each kind has distinct sidebar rendering: lineage shows a timeline with current-edition markers; topic bundles render as colored cards; publisher families show counts and badges; curated collections show curator attribution.

Relation sphere

The 3D relation sphere visualizes a concept’s neighborhood as an interactive force-directed sphere. Each surrounding node is a directly related concept, color-coded by relationship type. A degree filter lets users collapse the sphere to specific relationship categories (e.g. show only broader/narrower, or only cross-vocabulary matches).

This is built on d3-force-3d and is fully static — no WebGL backend or server required.

Edition series & cross-dataset navigation

For vocabularies with multiple editions (VIM, VIML, ISO/IEC directories), concepts declare supersedes relationships to their predecessors using ref.source URNs. The concept-browser resolves these at build time into a supersession chain, surfacing both forward (“supersedes”) and derived inverse (“superseded by”) links in the UI.

See Relationships → Cross-dataset navigation for the data side.

RDF & SHACL outputs

Every concept emits SHACL-conformant Turtle + JSON-LD. Dataset-level artifacts include:

The build pipeline runs the canonical SHACL shapes from the concept-model against every concept before serialization.

Architecture

The codebase is organized around an Open-Closed Principle (OCP) group registry and renderer registry:

• Adding a new dataset group kind = registering a renderer, not editing a switch statement
• Adding a new RDF emitter = registering a serializer, not modifying the build pipeline
• Adding a new relationship-type color = editing site-config.yml, not touching code

This keeps the build pipeline stable as new dataset shapes and group kinds are added. See CLAUDE.md for the full architectural overview.

RDF layer lives in glossarist-js (v0.7.67)

As of v0.7.67 the in-repo src/components/concept-rdf/ layer is gone — ~2,300 LOC of duplicate emitters, writers, and graph abstractions deleted. The Vue UI now consumes glossarist-js directly: conceptToQuads and provenanceToQuads for the graph, writeTurtleSync + canonical prefixes for CURIE-form Turtle, and formatJsonLd for JSON-LD. This makes glossarist-js the single source of truth for RDF emission across the ecosystem — fixes land once and propagate to every consumer.

Links

• GitHub
• Live: GeoLexica
• Live: VIML

See Also

• Concept Model docs — the data model the browser renders
• Datasets & sections — register.yaml and section trees
• Non-verbal entities — figures, tables, formulas in the browser
• Relationships — cross-dataset navigation