Conversation
achrinza
force-pushed
the
filter-specification
branch
3 times, most recently
from
d96976d to
87c257e
Compare
| @@ -0,0 +1,270 @@ | |||
| # The LoopBack 4 Filter Specification - Draft 1 | |||
|
|
|||
There was a problem hiding this comment.
I'd like to discuss what's the best place where to keep documents like this one. Using a new top-level folder specifications is a fine choice 👍
Few other alternatives that come to my mind:
- Do we want to ever render the spec on https://loopback.io? Then it maybe better to put the content to
docs/specifications. - Since this spec is tied to
@loopback/filterpackage, would it make sense to keep it inpackages/filter? Maybe have a doc page with links to different spec documents we have in our packages, to make them easier to find from a single place.
Also do we need to repeat "loopback" and "specifications" in the file name? Since this file is in the LoopBack 4 repo and inside specifications folder, maybe specifications/filter.md is sufficient?
Just few ideas to consider. I don't want to bike-shed, feel free to keep what you have now.
| @@ -0,0 +1,270 @@ | |||
| # The LoopBack 4 Filter Specification - Draft 1 | |||
There was a problem hiding this comment.
Should we perhaps emphasize the fact that this is a work in progress? Maybe add a paragraph with content similar to what we have in experimental packages?
## Status: ⚠️WORK IN PROGRESS⚠️
> The specification is not complete yet and some parts may be inaccurate.
achrinza
force-pushed
the
filter-specification
branch
from
87c257e to
83233cf
Compare
Signed-off-by: Rifa Achrinza <25147899+achrinza@users.noreply.github.com>
achrinza
force-pushed
the
filter-specification
branch
from
83233cf to
b7cf51a
Compare
| - _Connector_: A code implementation that interfaces with a Datastore that MUST | ||
| accept a Normalized Filter for data querying against the Datastore. | ||
| - _Datastore_: A code implementation that manages the state of Connectors. |
There was a problem hiding this comment.
We should generalise these to something along the lines of "Data Producer" as this specification should be scoped to only passing of filters from Data Consumer to Data Producer. What exactly is the Data Producer and Data Consumer should be up to the implementations to decide.
For LoopBack Juggler and LoopBack 4, we should informally document that the Connector accepts a normalized filter in line with a specific compliance matrix, the LB4 Repository (and inherently the REST API) accepts un-normalized filter with specific compliance matrix, etc.
| - _Compliance Matrix_: A standardised, grouped list of Filter Features used to | ||
| provide a higher-level overlay to gauge general interopability of features | ||
| without requiring deep knowledge on the subject matter. |
There was a problem hiding this comment.
A "compliance matrix" may be better-suited as a separate specification that profiles this specification. This "profiling" approach is adopted by OASIS Open.
| This document describes the LoopBack 4 Filter Specification; A JSON-based | ||
| [[RFC7159](https://tools.ietf.org/html/rfc7159)] data query language that |
There was a problem hiding this comment.
We should switch over to JADN instead of binding ourselves to JSON serialisation.
One of the problems with the current approach of this work is that it pivots around a default JSON serialisation. This makes it difficult to perform information modelling and exposes the specification to the quirks of JSON. Since this work started, JSON Abstract Data Notation Committee Specification 01 (JADN CS01) was released. This specification allows for first-class information modelling with a built-in JSON, XML and CBOR serialisation strategy; This means that there's a clear path to converting from JADN to JSON Schema for compatibility with the current implementation in LoopBack 4. The plan is to rewrite the existing work to leverage JADN and publish JADN packages as normative references.
| The grammatical rules in this document are to be interpreted as described in | ||
| [[RFC5234](https://tools.ietf.org/html/rfc5234)]. | ||
|
|
||
| This document makes reference to grammatical rules defined in | ||
| [[RFC7159](https://tools.ietf.org/html/rfc7159)]. |
There was a problem hiding this comment.
Likewise, we should use JADN instead of JSON serialisation directly.
| [[RFC7159](https://tools.ietf.org/html/rfc7159)] data query language that | ||
| enables rich, interopable and protocol-agnostic data query filters across | ||
| multiple datastores. | ||
|
|
There was a problem hiding this comment.
We may want to state that data manipulation is out of scope.
2 participants
Update 25 April 2022: One of the problems with the current approach of this work is that it pivots around a default JSON serialisation. This makes it difficult to perform information modelling and exposes the specification to the quirks of JSON. Since this work started, JSON Abstract Data Notation Committee Specification 01 (JADN CS01) was released. This specification allows for first-class information modelling with a built-in JSON, XML and CBOR serialisation strategy; This means that there's a clear path to converting from JADN to JSON Schema for compatibility with the current implementation in LoopBack 4. The plan is to rewrite the existing work to leverage JADN and publish JADN packages as normative references.
Signed-off-by: Rifa Achrinza 25147899+achrinza@users.noreply.github.com
Checklist
npm testpasses on your machinepackages/cliwere updatedexamples/*were updated👉 Check out how to submit a PR 👈