json-ld icon indicating copy to clipboard operation
json-ld copied to clipboard

Syntax & processing overhaul

Open timothee-haudebourg opened this issue 2 years ago • 1 comments

This is an important PR that I hope will remove the current limitations of the library. It will:

  • Remove need for the trait_alias unstable feature.
  • Reduce the complexity of the type signature of a lot of functions across the crate.
  • Allow the static definition of LD contexts.

The problem(s)

For now, a JSON-LD context/document is processed directly from its raw JSON representation. This complicates the implementation of various processing algorithms since the syntax of JSON-LD is a subset of the JSON, which introduce many checks and conversions across the algorithms. Over all, the implementation feels loosely typed. Moreover since many different JSON library exist, for different purposes, I've added an abstraction layer over the underlying JSON implementation (through the generic-json crate). This abstraction layer complicates even more the implementation, the type signatures, and require the use of the unstable trait_alias feature.

In addition, many of the type abstraction present in the library were introduced in the past to allow for the static definition of JSON-LD contexts. This is a very useful feature for applications that already know which contexts they will be dealing with, by removing the cost of reloading the context. However with the current implementation this very hard to do:

  • The abstraction layer over JSON makes it difficult (impossible?) to define anything with a 'static lifetime
  • I wrongly assumed that the processed context should be a type parameter for this to work, where only the local context is required to be a type parameter. Then an application can replace this type parameter with their static implementation of a JSON-LD (local) context.

Changes

  • Split the crate in multiple modules to simplify the maintenance of the library. The code base was getting too big.
  • Add a syntax library that provides type representing the syntax tree of a JSON-LD document (the subset of the JSON syntax). This will replace the JSON abstract with a well-typed and correct representation of unprocessed JSON-LD documents. It will be possible to directly parse a JSON-LD document without going through a JSON library, or convert from a JSON pre-parsed JSON repr, or use serde.
  • Rewrite the processing functions to take this AST type as parameter instead of a generic JSON type. No JSON abstraction needed, no unstable feature.

To do

  • [x] Split the crate
  • [x] Create the syntax crate
  • [x] Refactor the context processing algorithm
  • [x] Refactor the expansion algorithm
  • [ ] Refactor the compaction algorithm
  • [x] Pass the expansion test suite
  • [ ] Pass the compaction test suite

timothee-haudebourg avatar Jun 22 '22 13:06 timothee-haudebourg

This should also solve #40

timothee-haudebourg avatar Aug 24 '22 15:08 timothee-haudebourg