[USER STORY] Human Friendly JSON-LD representation of STIRData data

[sskagemo]

As a: Developer with limited knowledge about Linked Data

I wish to: Be able to consume data in formats as similar to JSON as possible

So that I: Don't become confused and prefer other sources, or create "wrappers" around the STIRData sources

Related to User Story: #45

Related to Epic: #4

Description:

RDF-data can be represented in JSON-LD in a compacted and an expanded way

Compacted:

{
  "@context": {
    "@vocab": "http://example.com/vocab/"
  },
  "@id": "http://example.org/places#BrewEats",
  "@type": "Restaurant",
  "name": "Brew Eats"
  ...
}

Expanded:

[{
  "@id": "http://example.org/places#BrewEats",
  "@type": ["http://example.com/vocab/Restaurant"],
  "http://example.com/vocab/name": [{"@value": "Brew Eats"}]
}]

Source: https://www.w3.org/TR/json-ld11/#example-24-using-a-default-vocabulary

The latter format (expanded) has the advantage of being complete, in terms that all terms are URIs, and there is no need for a specification of where they are from. But the URIs makes it harder to read the format. The compacted format is closer to traditional JSON, as long as you learn (to ignore) the context and vocab part, and understand the use of @id and @type.

But in order to achieve this, the terms must be defined in a single RDF-vocabulary, that can be linked to through @vocab, or specified in a JSON LD context file. Or, you must refer to several vocabularies with prefixes, which is familiar for those who are used to linked data and the turtle-format, but might look strange for others (see example at the bottom of this comment).

Old text, not correct (see Jakubs comment): This is in contrast to for instance the turtle format, were we can use prefixes to mix and match terms from several vocabularies, as is done in the current version of the STIRData data model.

An alternative, is to have the different information elements split in separate parts of the JSON LD document, where each part have their own context, but this will probably also make the format look less familiar for developers used to JSON.

There is also the opportunity to define "prefixes", but again, although this is familiar for persons with experience with linked data, this will probably also look a bit frightening for others:

{
  "@context": {
    "@version": 1.1,
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "foaf": "http://xmlns.com/foaf/0.1/",
    "foaf:homepage": { "@type": "@id" },
    "picture": { "@id": "foaf:depiction", "@type": "@id" }
  },
  "@id": "http://me.markus-lanthaler.com/",
  "@type": "foaf:Person",
  "foaf:name": "Markus Lanthaler",
  "foaf:homepage": "http://www.markus-lanthaler.com/",
  "picture": "http://twitter.com/account/profile_image/markuslanthaler"
}

Disclaimer: There are possibly a lot of misunderstandings on my part about the details in JSON-LD and the use of @context and @vocab here, so maybe this issue is totally irrelevant.

[jakubklimek]

@sskagemo there are multiple points here.

The STIRData specification contains the data model in RDF - which predicates and classes to use. It does not prescribe any particular data format for representation of the data (i.e. Turtle or JSON-LD in RDF). What you are asking would be to prescribe a particular JSON structure and its mapping (via context) to this RDF data model. But before we get to that - this assumes there is an API in the STIRData platform that somehow provides the data. Only then we can talk about in which format the data should be provided, and, if in JSON-LD, how that JSON-LD should look like. But this would have to be the API that currently serves the STIRData platform frontend, because there is no other API (again, AFAIK), and I am not sure whether this API is designed to also serve as a public API for providing data. We need to ask @achort.

The data according to the specification is currently still stored in the individual SPARQL endpoints of the individual registries, the SPARQL endpoint being the API for data access. And a SPARQL endpoint does not allow you to specify a JSON-LD context to be used - if you ask for data in JSON-LD, it will be a JSON-LD (one of its many forms), not the one you specify with your context. In order to do that, there would have to be some kind of proxy software transforming the JSON-LD files to the specified format - which is IMHO out of scope at the moment.

Then again, if you are talking about the API of the STIRData platform - e.g. to ask for info about a company in RDF and get that data (the same data the Platform frontend gets) in a particular JSON-LD format, this could be doable. Again, we need to ask @achort how the API actually looks like, because I have not seen it.

in order to achieve this, the terms must be defined in a single RDF-vocabulary, that can be linked to through @vocab, or specified in a JSON LD context file. This is in contrast to for instance the turtle format, were we can use prefixes to mix and match terms from several vocabularies, as is done in the current version of the STIRData data model.

Not true. In JSON-LD context, you can mix and match vocabularies the same way you can in Turtle.

[sskagemo]

Thanks for you reply @jakubklimek , and I realised at the end of my comment that I was wrong when I said that JSON-LD can't use prefixes in the same way as in turtle, but I obviously didn't think far enough to go back and correct it. But still, I believe that a JSON-LD document without prefixes will look more familiar for developers that are not used to Linked Data.

I also realise that there is a user story lacking for accessing the individual registries and the platform through "plain" APIs, I'll add that, and then these two issues should be considered together.

[achort]

I have a relevant api call to the platform the return a json-ld description of an entity given its stirdata uri. E.g. http://dev.stirdata.eu/api/data/entity?uri=https://lod.stirdata.eu/data/organization/no/988920738 Currently I have defined a temporary json-ld context.