Do we need JSON-LD support? If yes, what for?

[acka47]

Until now, JSON-LD came up in:

• seven issues: https://github.com/search?q=repo%3Areconciliation-api%2Fspecs+%22JSON-LD%22&type=issues
• three PRs: https://github.com/search?q=repo%3Areconciliation-api%2Fspecs+%22JSON-LD%22&type=pullrequests
• one mail thread: https://lists.w3.org/Archives/Public/public-reconciliation/2024Oct/0005.html

We probably need to get on the same page about our goals of supporting JSON-LD for the reconciliation API. I am formulating this from my point of view as someone who likes JSON-LD a lot in terms of an extended JSON that enables unambigously identifying the properties/JSON keys used and referencing the documentation for each key. However, until now I mostly have not been persuaded to make investments needed to optimize usage of the JSON-LD data as RDF e.g. by enabling enable reasoning or optimizing for SPARQL queries.

Why JSON-LD?

To get a clearer picture what we are actually talking about, I am distinguishing four levels of JSON-LD adoption which will require different levels of discussion and workload to accomplish. I go from easiest to most complex.

1. We just want the data delivered by Reconciliation endpoints to be valid JSON-LD

• lowest level
• create a JSON-LD context document mapping properties and types to URIs
• add @context link to payloads
• DON'T make property URIs resolvable
• benefits:
  • properties have an unambigous IRI as identifier
  • JSON-LD tooling can be used on the data (see https://github.com/reconciliation-api/specs/pull/182#issuecomment-2448803269)
  • JSON-LD's built-in support for multi-linguality can be used (see e.g. #52, #138 and https://github.com/reconciliation-api/specs/pull/182#issuecomment-2449525681)

2. We also want property/type URIs to resolve

• This can be accomplished by doing 1.) plus pointing property and type URIs to existing documentation (see https://github.com/reconciliation-api/specs/pull/38#issuecomment-584541901), e.g. to the respective paragraph in the spec (might involve some reworking of the spec, at least by adding anchors) or the property's JSON schema (would require reworking the schema to have one file per property).
• Benefits: people would be able to access property-/type-level documentation by following links in the payload.
• Drawbacks
  • linking to existing documentation is not a common approach as people might expect structured data (more JSON-LD/RDF) when resolving property/type URIs
  • I have my doubts that this will be used much as people will have to know about JSON-LD and the context in the first place to follow the context link and then the link to the respective property.

3. We want property and type URIs to resolve to a RDFS/OWL reconciliation vocab

• benefit: one overview about all properties and types used in the reconcilation API
• drawback: This will involve creating a third – next to the HTML spec and the JSON schema – separate kind of normative description of the reconciliation API in terms of its vocab. Changes to all three resources will have to be coordinated.

4. We want JSON-LD that can be used as RDF together with an ontology to support reasoning on Reconciliation API payloads (or other Semantic Web magic)

• This probably means putting much more thought into creating the reconciliation vocab/ontology.

[Abbe98]

create a JSON-LD context document mapping properties and types to URIs

On my end I would imagine than rather than just map the existing properties and types to new URIs one would adopt existing vocabularies like DCAT(for much of the manifests), Activity Streams/Web Annotations for reconciliation requests, schema.org, etc.

This would allow us to take advantage of so much ecosystem and tooling from day one and completely skip a lot of the adoption that would otherwise be needed.

[acka47]

On my end I would imagine than rather than just map the existing properties and types to new URIs one would adopt existing vocabularies like DCAT(for much of the manifests), Activity Streams/Web Annotations for reconciliation requests, schema.org, etc.

This would allow us to take advantage of so much ecosystem and tooling from day one and completely skip a lot of the adoption that would otherwise be needed.

Thanks. So, you basically want to create kind of a metadata profile for the reconciliation API based on existing vocabularies. This is definitely something we'd need to discuss. I am also a fan of metadata profiles in an application context or one specifying community profiles. I haven't seen a metadata profile yet for protocols and I assume it will be hard to cover every bit of the reconciliation API with existing RDF properties and classes...

[Abbe98]

I haven't seen a metadata profile yet for protocols and I assume it will be hard to cover every bit of the reconciliation API with existing RDF properties and classes...

I wouldn't expect that one would be able to cover all of it with existing properties and classes but just getting the basics interoperable would go a long way.

[thadguidry]

Pretty much STEP 6 https://www.w3.org/TR/ld-bp/

Also least we forget: https://www.w3.org/TR/cooluris/ But generally:

But how to be on the Web with this approach? How to enable agents to download more data about resources we mention? There is a best practice to achieve this goal: Provide not only the IFP of the resource (e.g. the person's email address), but also an rdfs:seeAlso property that points to a Web address of an RDF document with further information about it. We see that HTTP URIs are still used to identify the location where more information can be downloaded.