WTC Semantic Layer

Version 1.0.0 provides a vendor-neutral semantic layer engine for production metadata workflows.

Maintained by Franz Malten Buemann [email protected] for Eksido.com / WeTakeControl.eu.

It supports three operating modes:

• Generate a governed semantic model from business glossary terms, metric definitions, and physical metadata.
• Suggest mappings from physical columns to semantic attributes with confidence scores and explainable evidence.
• Approve mapping suggestions into a traceable metadata graph that can be exported or served through an HTTP API.

The npm package is authored in TypeScript, emits declaration files, is dependency-free at runtime, and exposes both a programmatic API and the wtc-semantic-layer CLI.

Install

From this repository:

npm install
npm link
wtc-semantic-layer --help

For local development without linking:

node ./bin/wtc-semantic-layer.js --help

Programmatic usage:

import {
  approveMappings,
  generateModel,
  type SemanticModel,
  suggestMappings
} from "@eksido/wtc-semantic-layer";

declare const glossary: unknown;
declare const metrics: unknown;
declare const assets: unknown;

const model: SemanticModel = generateModel(glossary, metrics, assets);

Input Contracts

All inputs are JSON. Objects may include additional fields; unknown fields are preserved where possible but are not required.

Business Glossary

{
  "terms": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "classification": "string",
      "classifications": ["string"],
      "owner": "string",
      "tags": ["string"]
    }
  ]
}

Metric Catalog

{
  "metrics": [
    {
      "id": "string",
      "name": "string",
      "definition": "string",
      "formula": "string",
      "related_terms": ["string"],
      "owner": "string"
    }
  ]
}

Physical Metadata

{
  "assets": [
    {
      "id": "string",
      "database": "string",
      "schema": "string",
      "table": "string",
      "name": "string",
      "description": "string",
      "owner": "string",
      "classifications": ["string"],
      "columns": [
        {
          "id": "string",
          "name": "string",
          "data_type": "string",
          "description": "string",
          "classification": "string",
          "classifications": ["string"],
          "nullable": true
        }
      ]
    }
  ]
}

CLI

Generate a semantic model:

wtc-semantic-layer generate-model \
  --glossary /path/glossary.json \
  --metrics /path/metrics.json \
  --assets /path/physical-assets.json \
  --model-name enterprise \
  --output /path/semantic-model.json

Suggest mappings:

wtc-semantic-layer suggest-mappings \
  --model /path/semantic-model.json \
  --assets /path/physical-assets.json \
  --threshold 0.62 \
  --top-k 3 \
  --output /path/mapping-suggestions.json

Approve accepted mappings into a graph:

wtc-semantic-layer approve-mappings \
  --suggestions /path/mapping-suggestions.json \
  --model /path/semantic-model.json \
  --assets /path/physical-assets.json \
  --output /path/metadata-graph.json

Suggestions are only approved automatically when --auto-accept-threshold is supplied. Without that flag, only records with "decision": "accepted" are promoted into graph edges.

Run the HTTP API:

wtc-semantic-layer serve --host 127.0.0.1 --port 8088 --state-dir /var/lib/wtc-semantic-layer

Endpoints:

• GET /health
• POST /v1/models/generate
• POST /v1/mappings/suggest
• POST /v1/mappings/approve

Examples

Production examples are available in examples/ and are grouped by usage mode:

• examples/node/ for programmatic package usage
• examples/cli/ for batch and steward-review workflows
• examples/http/ for API client workflows
• examples/ops/ for operational checks and package inspection
• examples/frontend/ for the browser console

They do not bundle business datasets. Workflows that need metadata read real file paths from environment variables.

node examples/ops/health-check.mjs
./examples/ops/inspect-package.sh
python3 -m http.server 8090 --directory examples/frontend

Run a complete Node workflow with your own files:

GLOSSARY_JSON=/secure/path/glossary.json \
METRICS_JSON=/secure/path/metrics.json \
ASSETS_JSON=/secure/path/assets.json \
OUTPUT_DIR=/secure/path/output \
node examples/node/full-pipeline.mjs

Package Validation

Run the full quality gate:

npm run quality

The quality gate runs TypeScript checking, ESLint, Jest with 100% coverage thresholds, the production build, and a package dry-run. Check dependency advisories separately:

npm audit --audit-level=moderate

Repository Layout

bin/       CLI entry point that loads the compiled package
src/       TypeScript package library, CLI, and API server implementation
dist/      compiled JavaScript and TypeScript declaration output generated by `npm run build`
test/      TypeScript Jest suite with 100% coverage thresholds
examples/  Node, CLI, HTTP, ops, and browser examples
scripts/   local maintenance commands
docs/      architecture notes

Production Notes

• Runtime behavior is deterministic and auditable: every suggested mapping includes evidence.
• The scoring engine combines token overlap, sequence similarity, classification agreement, entity/table context, data type compatibility, glossary links, and metric references.
• The HTTP API uses only Node.js standard library modules. Deploy behind a reverse proxy or API gateway for TLS, authentication, request limits, and centralized audit logging.
• Keep steward approval in the workflow for regulated environments. Use --auto-accept-threshold only for controlled batch jobs with known precision requirements.