SD Creation Wizard

SHACL-driven metadata wizard for the ENVITED-X ecosystem. TypeScript React 19

Overview

Parses SHACL/OWL ontologies (Turtle format) and renders dynamic form UIs for creating JSON-LD metadata assets. Used by the sl-5-8-asset-tools pipeline for metadata enrichment.

Architecture

┌────────────────────────────────────────────────────────────┐
│  Wizard (React 19 + Vite, port 5173)                       │
│    Upload TTL → Stepper → react-hook-form dynamic fields   │
│    → Review JSON-LD → Export                               │
│                      │ /api proxy                          │
├──────────────────────▼─────────────────────────────────────┤
│  API (Hono, port 3007)                                     │
│    /convertFile         → parse → ShaclModel               │
│    /convertAndPrefillFile → parse + match JSON-LD values   │
│    /getAvailableShapes  → cached ontology list             │
│                      │                                     │
├──────────────────────▼─────────────────────────────────────┤
│  shacl-core (N3.js)                                        │
│    RDF Store → Navigator → Extractor → Form Model          │
└────────────────────────────────────────────────────────────┘

API Reference

Method Path Description
POST /convertFile Upload a SHACL TTL file, get a form model JSON back
POST /convertAndPrefillFile Parse SHACL + prefill form values from existing JSON-LD
GET /getAvailableShapes List all cached shape schemas
GET /getAvailableShapesCategorized Shapes grouped by ontology prefix
GET /getJSON/:schema Retrieve a cached form model by schema name
GET /health Health check endpoint

Form Model (ShaclModel)

{
  "shapes": [
    {
      "schema": "HdMapShape",
      "targetClass": "https://w3id.org/ascs-ev/envited-x/hdmap/v6/HdMap",
      "targetClassName": "HdMap",
      "constraints": [
        {
          "path": { "prefix": "hdmap", "value": "hasFormat" },
          "name": "Format",
          "datatype": { "prefix": "xsd", "value": "string" },
          "minCount": 1,
          "maxCount": 1,
          "order": 1,
          "description": { "en": "The file format" },
          "in": [
            { "prefix": "hdmap", "value": "OpenDRIVE" },
            { "prefix": "hdmap", "value": "Lanelet2" }
          ],
          "or": [],
          "children": null,
          "validations": []
        }
      ]
    }
  ],
  "prefixList": [
    { "prefix": "hdmap", "namespace": "https://w3id.org/ascs-ev/envited-x/hdmap/v6/" }
  ]
}

Frontend Field Types

SHACL Constraint Field Type Rendered As
sh:in [...] select Dropdown (multi if maxCount > 1)
sh:or [...] union Radio selector → conditional sub-form
sh:maxCount > 1 repeat Dynamic array with add/remove (useFieldArray)
xsd:integer / xsd:decimal number Number input with min/max range
xsd:date / xsd:dateTime date Date input
xsd:anyURI / sh:nodeKind sh:IRI iri URL input with link icon
xsd:boolean boolean Checkbox (Yes/No)
sh:node group Nested field group
xsd:string (default) text Text input

Development

pnpm dev              # Start API + wizard concurrently
pnpm test             # Unit tests (vitest)
pnpm test:e2e         # Playwright E2E tests
pnpm lint             # ESLint
pnpm format:check     # Prettier
pnpm check-types      # TypeScript

Links