Skip to content

Build on JSON-Gold

Excluded alternative universe

This is the excluded alternative universe from the parent ADR.

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

piprate/json-gold is a Go JSON-LD processor; its latest v0.8.0 release (2026-02-23) piprate/json-gold is published on GitHub.

Implementation checklist

  • Choose a Go LSP framework, transport, document model, position conversion, lifecycle handling, and capability-registration boundaries.
  • Build JSON-LD, YAML-LD, and Markdown front-matter syntax layers that preserve source maps from semantic value paths to authored key and scalar ranges.
  • Connect mapped semantic values and JSON-Gold processing piprate/json-gold errors to their original source spans rather than generated JSON text.
  • Define the context, document-loader, and local relative-IRI policy, including contextual base IRIs, 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.
  • Add JSON-LD conformance and LSP end-to-end tests for diagnostic ranges, context errors, @type: @id links, relative cross-file resolution, multiple definition targets, and unsaved edits.
  • Build and distribute a Go binary with editor-installation guidance and 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 index, and editor-distribution layers around JSON-Gold.
  • The implementation, dependency management, cross-compilation, and release process follow the Go ecosystem.
  • YAML-LD and Markdown-LD require a maintained semantic-value-to-source-span bridge because JSON-Gold processes JSON-LD values rather than authored YAML or Markdown syntax.
  • JSON-Gold dependency and behavioural changes require compatibility tracking behind a stable LSP-facing semantic model.