Skip to content

Build on OxJSONLD

Excluded alternative universe

This is the excluded alternative universe from the parent ADR.

This planning path uses OxJSONLD as the JSON-LD semantic foundation, not as an existing LSP. “Universe” is planning shorthand for the consequences of committing to this foundation.

OxJSONLD is separately published as the oxjsonld crate, while its crate manifest Cargo.toml places its source in the Oxigraph monorepo.

Implementation checklist

  • Select or create the LSP transport and document store, including URI, position-conversion, lifecycle, capability-registration, and workspace-index boundaries.
  • Preserve a source map for JSON-LD, YAML-LD, and Markdown-LD that maps semantic values and JSON-LD paths back to authored key and scalar spans.
  • Feed semantic JSON-LD values into OxJSONLD while retaining their source paths; do not report diagnostics against a serialized intermediate JSON document.
  • Define the 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 maintain a workspace index that returns every definition for an IRI.
  • Make unsaved buffers and incremental edits authoritative for parsing, context resolution, diagnostics, document links, and the definition index.
  • Translate OxJSONLD processing errors into diagnostics at the original YAML-LD or Markdown-LD source spans.
  • Add protocol and end-to-end LSP tests covering diagnostic ranges, context errors, @type: @id links, relative cross-file resolution, multiple definition targets, and unsaved edits.
  • Publish a Rust binary and editor-installation path, including file associations for JSON-LD, YAML-LD, and Markdown-LD.

Universe consequences

  • The project must supply the complete LSP transport, workspace model, syntax parsing, source mapping, navigation, and editor-distribution layers around OxJSONLD.
  • YAML-LD and Markdown-LD require a maintained semantic-value-to-source-span bridge because OxJSONLD receives JSON-LD values rather than their original YAML or Markdown syntax.
  • Changes in the Oxigraph monorepo can affect the separately versioned OxJSONLD crate, requiring dependency and compatibility tracking.