Skip to content

Build on PyLD

Excluded alternative universe

This is the excluded alternative universe from the parent ADR.

This planning path uses PyLD as the JSON-LD semantic foundation and builds an LSP around it. PyLD 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/pyld publishes the Python PyLD package for JSON-LD processing.

Implementation checklist

  • Choose the Python 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 PyLD processing digitalbazaar/pyld while retaining path associations for diagnostics and semantic results.
  • Translate PyLD 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-IRI 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 PyLD, LSP-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 Python 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 PyLD.
  • The implementation and release toolchain follow the Python ecosystem, including its LSP-client and editor-extension packaging conventions.
  • YAML-LD and Markdown-LD need a maintained semantic-value-to-source-span bridge because PyLD processes JSON-LD values rather than authored YAML or Markdown syntax.
  • PyLD dependency and behavioural updates need compatibility tracking behind a stable LSP-facing semantic model.