Skip to content

Build on jsonld.js

Excluded alternative universe

This is the excluded alternative universe from the parent ADR.

This planning path uses jsonld.js for JSON-LD semantic processing and builds an LSP around it. jsonld.js supplies JSON-LD processing, not an LSP transport, workspace model, or editor integration; “universe” is planning shorthand for the consequences of committing to this foundation.

digitalbazaar/jsonld.js publishes the JavaScript jsonld package for JSON-LD processing.

Implementation checklist

  • Choose the TypeScript or JavaScript LSP runtime, transport, document model, position conversion, lifecycle handling, and capability-registration boundaries.
  • Build JSON-LD, YAML-LD, and Markdown front-matter syntax layers that preserve a source map from semantic value paths to authored key and scalar ranges.
  • Adapt mapped semantic values for jsonld.js processing digitalbazaar/jsonld.js while retaining path associations for diagnostics and semantic results.
  • Translate jsonld.js processing failures into diagnostics at original JSON, YAML-LD, or Markdown-LD source spans rather than generated JSON text.
  • Define the context, document-loader, and local-resolver policy, including contextual base IRIs, relative document resolution, permitted local paths, and remote-context handling.
  • Interpret JSON-LD @type: @id coercion to classify IRI-valued scalars, publish clickable links, and return every workspace definition for an IRI.
  • Keep unsaved buffers and incremental edits authoritative for parsing, context loading, diagnostics, document links, and the workspace definition index.
  • Maintain a workspace index of definitions and references that updates as in-memory and on-disk documents change.
  • Add protocol and end-to-end tests for diagnostic ranges, context errors, @type: @id links, relative cross-file resolution, multiple definition targets, and unsaved edits.
  • Publish a Node package and editor integrations, including file associations for JSON-LD, YAML-LD, and Markdown-LD.

Universe consequences

  • The project owns the LSP transport, incremental document model, syntax parsing, source mapping, navigation, workspace indexing, and editor-distribution layers around jsonld.js.
  • The implementation and release toolchain follow the Node and TypeScript ecosystem, including its editor-client packaging conventions.
  • YAML-LD and Markdown-LD need a maintained semantic-value-to-source-span bridge because jsonld.js processes JSON-LD values rather than authored YAML or Markdown syntax.
  • jsonld.js dependency and behavioural updates need compatibility tracking behind a stable LSP-facing semantic model.