JSON-LD responses: make them FAIR.

[RinkeHoekstra]

I think it's great to standardise on what a reconciliation API should and shouldn't do, but I strongly favour ensuring that the API response is in line with the W3C Linked Data family of languages.

This means that the response should be more entity-centric (i.e. the response should return a part of an entity's description) and that it should be interpretable as RDF through a JSON-LD context definition.

[wetneb]

@RinkeHoekstra thanks for the suggestion! Would you be interested in drafting a PR to show what it would look like?

[RinkeHoekstra]

:-) that’s what I thought you’d say. Let me see what I can do.

[wetneb]

In today's call @fsteeg pointed out that ActivityPub uses JSON-LD to format some payloads: https://www.w3.org/TR/activitypub/

[thadguidry]

@RinkeHoekstra Can you give us some more feedback on what the response might be required to look like? Is a JSON @context always supplied? Do we require @type always supplied within candidates? It is unclear to me how conformant we should tell services to be with JSON-LD responses. Do we allow JSON-LD to be optionally embedded within candidates? or is your suggestion that the reconciliation api full response be in JSON-LD, i.e. candidates might have type maps, nested properties, etc. and all the bells and whistles of a JSON-LD document that expresses a labeled directed graph?

We could even start simple if some clients prefer and need conformance and say in the spec that a response can be in JSON-LD and that it may include @context, have blank nodes, etc. but then what does a client do with a blank node for a resource, for instance?

Many questions here and certainly open to discuss more.

I do want to point out that I am a big fan of JSON-LD and it could particularly help us with a consistent method of string internationalization just as an example, but then would all clients have to fully support all the variety of ways for a JSON-LD plain string to be annotated with a language (there are about 4) and particularly nice are the @container language maps.

[thadguidry]

@wetneb @fsteeg Having a consistent format and processer library in their language of choice would address parsing issues for developers and not having to write their own as evidenced by @stefanw with https://github.com/reconciliation-api/specs/issues/84#issuecomment-1150013674

Writing the parsing for the API requests was cumbersome, had lots of difficult to debug errors and took a long time. (I hear it's gotten better since then with more tooling.)

JSON-LD has many that are compliant with latest JSON-LD 1.1 https://json-ld.org/#developers

A reconcile service returns Objects, some of them might be related, some not, and so I don't think a @graph context might be accurate to use, but everything else in JSON-LD potentially could. Then again, relatedness of Objects and their shared properties although being more verbose in data format, could allow clients to provide better filtering mechanisms of candidates rather than the service side.

Which ultimately leads to a question of performance to service user requests:

1. Filter on the service by first asking a narrowed filtered query VERSUS
2. Filter within the client by reshaping a more full/partial graph result that was returned by the service.

[acka47]

This popped up in my emails. Unfortunately, I currently don't have the time to go deeper into this right now, I want to point to a thread from 2020 where we already discussed JSON-LD payloads: https://github.com/reconciliation-api/specs/pull/38#issuecomment-584541901 ff Maybe it can be helpful...

[Abbe98]

I would suggest looking at the Hydra Vocabulary for the manifest/service definition and Linked Data Platform for reconciliation itself.

Other relevant vocabularies would include VoID, Web Annotations, DCAT, and Activity Streams.