JSON-LD export

[nichtich]

The SSSOM/JSON format is underspecified (#321). It's implementation in sssom-py is based on whatever LinkML does. At the same time a JSON-LD export is asked for (#102, #241). I'm not sure whether a good JSON-LD export for mapping to RDF is doable with LinkML at all - in my point of view LinkML framework is more a burden for this task (mapping-commons/sssom-py#590). sssom-js is not based on LinkML and it supports JSON(-LD) export that differs from JSON export in sssom-py. Here is an example:

# curie_map:
#  x: http://example.org/
#  orcid: https://orcid.org/
# mapping_set_id: http://example.org/mapping_set
# license: https://creativecommons.org/licenses/by/4.0/
# creator_id: orcid:0000-0002-1825-0097
# creator_label: Josiah Carberry
subject_id	predicate_id	object_id	mapping_justification	reviewer_label
x:1	skos:exactMatch	x:2	semapv:ManualMappingCuration	Alice

JSON-LD (=JSON minus curie_map)

{
  "curie_map": {
    "x": "http://example.org/",
    "orcid": "https://orcid.org/"
  },
  "mapping_set_id": "http://example.org/mapping_set",
  "license": "https://creativecommons.org/licenses/by/4.0/",
  "creator": [ {
      "id": "https://orcid.org/0000-0002-1825-0097",
      "label": "Josiah Carberry"
  } ],
  "mappings": [ {
      "subject_id": "http://example.org/1",
      "predicate_id": "http://www.w3.org/2004/02/skos/core#exactMatch",
      "object_id": "http://example.org/2",
      "mapping_justification": "https://w3id.org/semapv/vocab/ManualMappingCuration",
      "reviewer": [ { "label": "Alice" } ]
  } ]
}

RDF

@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix semapv: <https://w3id.org/semapv/vocab/> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix sssom: <https://w3id.org/sssom/> .
@prefix dct: <http://purl.org/dc/terms/> .

<http://example.org/mapping_set> dct:creator <https://orcid.org/0000-0002-1825-0097> ;
  dct:license <https://creativecommons.org/licenses/by/4.0/> ;
  sssom:mappings [
    dct:contributor [
      rdfs:label "Alice"
    ] ;
    owl:annotatedProperty skos:exactMatch ;
    owl:annotatedSource <http://example.org/1> ;
    owl:annotatedTarget <http://example.org/2> ;
    sssom:mapping_justification semapv:ManualMappingCuration
  ] .

<https://orcid.org/0000-0002-1825-0097> rdfs:label "Josiah Carberry" .

The JSON-LD context can still be improved to cover more slots

{
  "dct": "http://purl.org/dc/terms/",
  "sssom": "https://w3id.org/sssom/",
  "owl": "http://www.w3.org/2002/07/owl#",
  "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
  "prov": "http://www.w3.org/ns/prov#",
  "mappings": {
    "@id": "sssom:mappings",
    "@context": {
      "owl": "http://www.w3.org/2002/07/owl#",
      "mapping_id": "@id",
      "subject_id": { "@id": "owl:annotatedSource", "@type": "@id" },
      "object_id": { "@id": "owl:annotatedTarget", "@type": "@id" },
      "predicate_id": { "@id": "owl:annotatedProperty", "@type": "@id" },
      "mapping_justification": { "@id": "sssom:mapping_justification", "@type": "@id" },
      "similarity_score": { "@id": "sssom:similarity_score", "@type": "xsd:double" },
      "author": {
        "@id": "dct:creator",
        "@context": { "id": "@id", "label": "rdfs:label" }
      },
      "reviewer": {
        "@id": "dct:contributor",
        "@context": { "id": "@id", "label": "rdfs:label" }
      }
    }
  },
  "mapping_set_id": "@id",
  "mapping_set_version": { "@id": "owl:versionInfo" },
  "mapping_set_source": { "@type": "@id", "@id": "prov:wasDerivedFrom" },
  "mapping_set_title": { "@id": "dct:title" },
  "mapping_set_description": "dct:description",
  "comment": { "@id": "rdfs:comment" },
  "creator": {
    "@id": "dct:creator",
    "@context": { "id": "@id", "label": "rdfs:label" }
  },
  "license": { "@id": "dct:license", "@type": "@id" },
  "publication_date": { "@type": "xsd:date", "@id": "dct:issued" },
  "see_also": { "@id": "rdfs:seeAlso", "@type": "@id" },
  "mapping_date": { "@type": "xsd:date", "@id": "dct:created" },
  "mapping_provider": { "@id": "sssom:mapping_provider", "@type": "@id" }
}

Notable features of the JSON-LD export:

• All CURIEs are expanded to URIs and curie_map is not passed to RDF (it may be included in SSSOM/JSON nevertheless and could be reused for pretty RDF/Turtle but CURIEs are not RDF data model)
• All repeatable slots are arrays
• Array slot elements with id and label are merged into nested elements (creator, author, reviewer).
• Some RDF properties are not fixed yet (e.g. author should be pav:authoredBy). I'd like to keep the property URIs in the https://w3id.org/sssom/ namespace minimal and reuse existing ontologies instead

[matentzn]

If I am totally honest with you, this proposal looks very sane to me.. Can you provide a full JSON-LD example with type decorators etc?

[nichtich]

This is the "expanded" form of JSON-LD, as generated by JSON-LD playground from the JSON-LD and context document (put into additional field @context) from above:

[
  {
    "http://purl.org/dc/terms/creator": [
      {
        "@id": "https://orcid.org/0000-0002-1825-0097",
        "http://www.w3.org/2000/01/rdf-schema#label": [
          {
            "@value": "Josiah Carberry"
          }
        ]
      }
    ],
    "http://purl.org/dc/terms/license": [
      {
        "@id": "https://creativecommons.org/licenses/by/4.0/"
      }
    ],
    "@id": "http://example.org/mapping_set",
    "https://w3id.org/sssom/mappings": [
      {
        "https://w3id.org/sssom/mapping_justification": [
          {
            "@id": "https://w3id.org/semapv/vocab/ManualMappingCuration"
          }
        ],
        "http://www.w3.org/2002/07/owl#annotatedTarget": [
          {
            "@id": "http://example.org/2"
          }
        ],
        "http://www.w3.org/2002/07/owl#annotatedProperty": [
          {
            "@id": "http://www.w3.org/2004/02/skos/core#exactMatch"
          }
        ],
        "http://purl.org/dc/terms/contributor": [
          {
            "http://www.w3.org/2000/01/rdf-schema#label": [
              {
                "@value": "Alice"
              }
            ]
          }
        ],
        "http://www.w3.org/2002/07/owl#annotatedSource": [
          {
            "@id": "http://example.org/1"
          }
        ]
      }
    ]
  }
]

[gouttegd]

Array slot elements with id and label are merged into nested elements (creator, author, reviewer).

This is wrong.

You are turning this:

# creator_id: orcid:0000-0002-1825-0097
# creator_label: Josiah Carberry

(which, by the way, is a supported-for-backwards-compatibility but officially discouraged syntax: creator_id and creator_label are multi-valued slots, they should not be represented as scalar strings)

into this (JSON):

"creator": [ {
      "id": "https://orcid.org/0000-0002-1825-0097",
      "label": "Josiah Carberry"
  } ],

or this (RDF):

<http://example.org/mapping_set> dct:creator <https://orcid.org/0000-0002-1825-0097> .
<https://orcid.org/0000-0002-1825-0097> rdfs:label "Josiah Carberry" .

That is, your are assuming that the creator_id and creator_label slots are linked, in that creator_label is the human-readable label of the creator identified in creator_id. That is not the case. The two slots are independent, and creator_label is intended, not to provide the label of a creator already listed in creator_id, but as a fallback for cases where a creator does not have any semantic identifier that could be used in creator_id.

[gouttegd]

So the JSON output of your example set should rather be something like:

"creator": [ {
      "id": "https://orcid.org/0000-0002-1825-0097"
    },
    {
       "label": "Josiah Carberry"
    } ]

and the RDF output

<http://example.org/mapping_set> dct:creator <https://orcid.org/0000-0002-1825-0097> ,
  "Josiah Carberry" .

(This is assuming that the set has been created by two people, one identified by their ORCID, and one represented by their name; if “Josiah Carberry” is in fact the name of the person identified by ORCID:0000-0002-1825-0097, then the original set should not mention “Josiah Carberry” at all – again, creator_label is intended as a fallback when no semantic identifier is available: if the creator has an ORCID, then only the ORCID needs to be present.)

[nichtich]

Oh, sorry - I should have read the documentation more carefully! I'm going to implement optional warnings for such cases: if both creator_id and creator_label are given, this is not an error but likely wrong or misleading.

[gouttegd]

Some RDF properties are not fixed yet (e.g. author should be pav:authoredBy)

I just want to note that the properties to use should be defined by the LinkML model (meaning slot in each slot definition).

For example:

• author_id is already supposed to represented, in RDF context, by pav:authoredBy, not by dct:creator.
• publication_date is supposed to be represented by dct:created, not by dct:issued.
• mapping_date is supposed to be represented by pav:authoredOn, not by dct:created.

I personally don’t care which properties are used for which slots, and I would have zero objection to changing the ones that are currently assigned – but my point is that if we want to change them, the change must happen in the LinkML model, not in the specification for the RDF or JSON-LD formats.

[nichtich]

Update (using both creator_id and creator_label should give a warning but is allowed). See also updated context.json:

{
  "curie_map": {
    "x": "http://example.org/",
    "orcid": "https://orcid.org/"
  },
  "mapping_set_id": "http://example.org/mapping_set",
  "license": "https://creativecommons.org/licenses/by/4.0/",
  "creator_id": [ "https://orcid.org/0000-0002-1825-0097" ],
  "creator_label": [ "Josiah Carberry" ],
  "mappings": [ {
      "subject_id": "http://example.org/1",
      "predicate_id": "http://www.w3.org/2004/02/skos/core#exactMatch",
      "object_id": "http://example.org/2",
      "mapping_justification": "https://w3id.org/semapv/vocab/ManualMappingCuration",
      "reviewer_label": [ "Alice" ]
  } ]
}

@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix semapv: <https://w3id.org/semapv/vocab/> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix sssom: <https://w3id.org/sssom/> .
@prefix dct: <http://purl.org/dc/terms/> .

<http://example.org/mapping_set> dct:creator "Josiah Carberry", <https://orcid.org/0000-0002-1825-0097> ;
  dct:license <https://creativecommons.org/licenses/by/4.0/> ;
  sssom:mappings [
    dct:contributor "Alice" ;
    owl:annotatedProperty skos:exactMatch ;
    owl:annotatedSource <http://example.org/1> ;
    owl:annotatedTarget <http://example.org/2> ;
    sssom:mapping_justification semapv:ManualMappingCuration
  ] .

I'm not sure about how to best express authors and reviewers in RDF (dct:contributor, pav:authoredBy, schema:review with reviewer as dct:creator, ...), but this hopefully only affect JSON-LD context document, not the JSON-LD serialization.