Skip to content

Build on JSONLD-Java

Excluded alternative universe

This is the excluded alternative universe from the parent ADR.

This planning path uses JSONLD-Java as the JSON-LD semantic foundation and builds an LSP around it. It does not adopt an existing LSP implementation; “universe” is planning shorthand for the consequences of committing to this foundation.

jsonld-java/jsonld-java provides JSON-LD processing for Java and is published to Maven Central as com.github.jsonld-java:jsonld-java.

Implementation checklist

  • Choose a Java LSP framework, transport, document store, lifecycle model, position conversion, and workspace-index boundary.
  • Build source maps for JSON-LD, YAML-LD, and Markdown-LD that map semantic values and JSON-LD paths to authored key and scalar spans.
  • Bridge JSONLD-Java processing results and errors to mapped source paths instead of reporting diagnostics against a serialized JSON intermediate.
  • Define context and document-loader policy, including relative local-IRI resolution, allowed local documents, remote-context handling, and contextual base-IRI selection.
  • Interpret JSON-LD @type: @id coercion to classify IRI-valued values, expose clickable links, and return every matching workspace definition.
  • Make unsaved buffers and incremental edits authoritative for parsing, context resolution, diagnostics, document links, and the definition index.
  • Add JSON-LD conformance, LSP protocol, source-range, navigation, and editor end-to-end tests, including multiple definition targets and unsaved edits.
  • Publish a JVM package, language-server launch path, and editor-installation metadata for JSON-LD, YAML-LD, and Markdown-LD.

Universe consequences

  • The project supplies the complete LSP transport, workspace model, syntax parsing, source mapping, navigation, and editor-distribution layers around JSONLD-Java.
  • YAML-LD and Markdown-LD need a maintained semantic-value-to-source-span bridge because JSONLD-Java receives JSON-LD values rather than authored YAML or Markdown syntax.
  • The server, packaging, editor launch configuration, and contributor toolchain become JVM-based.