JSON-LD for non-LD to LD and LD to LD mappings

[simontaurus]

@matentzn, @sveinugu, @jesper-friis

Following the scenario-discussion in #84 JSON-LD should be more prominent as recommendation since it is an existing W3C standard and can cover multiple scenarios:

non-LD to LD

This is the major usecase for JSON-LD by applying a JSON-LD context to any JSON document.

non-LD to non-LD

Since (most) JSON-LD transformations are reversible having two non-LD to LD mappings in place can also form the chain non-LD' to LD, LD to non-LD''. Note that the LD representations needs to be the same or a mapping (see next point) exists.
This does not only cover simple keyword mappings but also important data transformations like array/literal enforcement ("@container": "@set"), adding/skipping nesting levels (@nest) and default language for non-localized literals (@language), all implemented by JSON-LD standard algorithms

LD to LD

This is out of scope for standard JSON-LD since not even the definition of an alias is allowed.
However, a simple extension (see OO-LD/schema#11) would allow to define exact mappings for properties and classes, potentially generated from SSSOM by applying confidence intervals for the exactness of a mapping.

In combination with syntactical schemas like JSON-SCHEMA / pydantic (see https://github.com/OO-LD/schema) we can archive e.g. people using multiple, syntactically non-interoperable, data classes

class Person(BaseModel):
    model_config = ConfigDict(
        json_schema_extra={
            "@context": {
                "schema": "https://schema.org/",
                "name": "schema:name",
                "type": "@type",
                "Person": "schema:Person"
            },
            "$id": "https://example.org/Person"
        }
    )
    type: Optional[str] = "Person"
    name: str
    """First and Last name"""

class Human(BaseModel):
    model_config = ConfigDict(
        json_schema_extra={
            "@context": {
                "rdfs": "http://www.w3.org/TR/rdf-schema/",
                "label": "rdfs:label",
                "label*": "https://schema.org/name", # could be generated from SSSOM
                "type": "@type",
                "ex": "https://another-example.org/",
                "Human": "ex:Human",
                 "Human*": "https://schema.org/Person", # could be generated from SSSOM
            },
            "$id": "https://another-example.org/Human"
        }
    )
    type: Optional[str] = "Human"
    label: str
    """First and Last name"""

which are nevertheless semantically interoperable with the provide annotations (see https://github.com/OO-LD/oold-python) and a corresponding SSSOM:

subject_id	subject_label	predicate_id	object_id	object_label	mapping_justification	author_id	confidence	comment
schema:name	name	skos:exactMatch	rdfs:label	label	semapv:ManualMappingCuration	orcid:0000-0003-0410-3616	0.95
schema:Person	Person	skos:exactMatch	ex:Human	Human	semapv:ManualMappingCuration	orcid:0000-0003-0410-3616	0.95

classDiagram
    class A{
        type: "Person"
        name: "Jane Doe"
    }

    class B{
        type: "Human"
        label: "Jane Doe"
    }

    A<--> B: mappedTo

Loading

If you agree I can draft an update of the documentation https://github.com/mapping-commons/rda-fair-mappings/blob/main/docs/recommendation.md regarding JSON-LD in general and add a use case for the specific implementation with OO-LD.

[matentzn]

https://github.com/mapping-commons/rda-fair-mappings/blob/main/docs/recommendation.md

I am not exactly clear yet about what you would like to add to the recommendation; Can you provide a full JSON LD example with the mapping for the Jane Doe example?

[simontaurus]

---

1. Plain JSON

Our starting point is a simple JSON file representing a person. Here, we do not use any JSON-LD constructs yet—just a standard JSON structure.

{
  "type": "Person",
  "name": "Jane Doe"
}

---

2. Add a JSON-LD Context

To convert the above JSON into JSON-LD (and hence RDF), we attach an "@context" and aliasing the "type" field to "@type". In doing so, we link our data to specific vocabularies (e.g., Schema.org) while keeping the original data unchanged:

{
  "@context": {
    "schema": "https://schema.org/",
    "name": "schema:name",
    "type": "@type",
    "Person": "schema:Person"
  },
  "type": "Person",
  "name": "Jane Doe"
}

or a RDF/Turtle

@prefix schema: <https://schema.org/> .

[] a schema:Person ;
   schema:name "Jane Doe" .

Explanation

1. We add the special key "@context" per JSON-LD spec to define how various JSON keys map to IRIs (in this case, Schema.org).
2. We map name to schema:name
3. Instead of relying on a plain "type" field, we use "@type"—a reserved JSON-LD property indicating the RDF type.
4. We treat "Person" as schema:Person by mapping "Person": "schema:Person"

3. Example: JSON-LD for "Human"

On the other hand, we have a JSON document using the Human class (based on a custom namespace https://another-example.org/) and referencing "label": "Jane Doe":

{
  "@context": {
    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
    "label": "rdfs:label",
    "label*": "https://schema.org/name",
    "type": "@type",
    "ex": "https://another-example.org/",
    "Human": "ex:Human",
    "Human*": "https://schema.org/Person"
  },
  "type": "Human",
  "label": "Jane Doe"
}

or a RDF/Turtle

@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix ex: <https://another-example.org/> .

[] a ex:Human ;
   rdfs:label "Jane Doe" .

This document describes the same entity (“Jane Doe”), but with different vocabulary terms.

Note:
Per JSON-LD specification this transformation is reversible, so it's possible to get back to the JSON document from the RDF graph

---

4. SSSOM Mapping: Connecting schema:name ↔ rdfs:label and schema:Person ↔ ex:Human

To align both JSON-LD structures, we can use SSSOM mappings for the relevant predicates and classes (e.g., [schema:name] and [rdfs:label]). Below is a sample snippet:

subject_id,subject_label,predicate_id,object_id,object_label,mapping_justification,author_id,confidence,comment
schema:name,name,skos:exactMatch,rdfs:label,label,semapv:ManualMappingCuration,orcid:0000-0003-0410-3616,0.95,
schema:Person,Person,skos:exactMatch,ex:Human,Human,semapv:ManualMappingCuration,orcid:0000-0003-0410-3616,0.95,

• schema:name maps to rdfs:label via skos:exactMatch.
• schema:Person maps to ex:Human via skos:exactMatch.

Hence, an SSSOM-compatible tool can automatically recognize that both JSON-LD representations (“Person” vs. “Human”) describe the same underlying concept.

---

5. Gain Syntactical Interoperability from Semantic Interoperability

If we decide that exactMatch with 95 percent is enough we can apply a generic transformation to actually translate the Human object to the Person object.

Using the oold-python package this would work as follows:

from oold.utils.transform import json_to_json

input_data = {
  "type": "Human",
  "label": "Jane Doe"
}

# JSON-LD @context if input_data
input_context = {
    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
    "label": "rdfs:label",
    "type": "@type",
    "ex": "https://another-example.org/",
    "Human": "ex:Human",
}

# JSON-LD @context for mapping with alias notation defined by OO-LD (*)
mapping_context = {
    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
    "schema": "https://schema.org/",
    "ex": "https://another-example.org/",
    "type": "@type",
    "name": "schema:name",
    "name*": "rdfs:label", # from SSSOM mappings
    "Person": "schema:Person",
    "Person*": "ex:Human", # from SSSOM mappings
}

# actual transformation
output_data = json_to_json(input_data, mapping_context, input_context)
>>
{
    "type": "Person",
    "name": "Jane Doe",
}

Note:
Entries with * such as label* or Human* serve are an non-standard extension to JSON-LD in order to define exact or close matches to other vocabularies (e.g., Schema.org). One could automatically derive these mappings (e.g., via SSSOM).

[matentzn]

@simontaurus thanks for the very detailed example. What would happen though if the person object is not flat, but nested (say

{
    "type": "Person",
    "name": {
       "first": "Jane",
       "middle": "",
       "last": "Doe"
    },
}

Then a simple context would not be enough, and a set of broad matches neither, because you need to specify how to concatenate the name parts to achieve the schema:name?

[simontaurus]

You could do

{
  "@context": {
    "schema": "https://schema.org/",
    "type": "@type",
    "Person": "schema:Person",
    "name": "@nest",
    "first": {
      "@id": "schema:givenName",
      "@nest": "name"
    },
    "middle": {
      "@id": "schema:additionalName",
      "@nest": "name"
    },
    "last": {
      "@id": "schema:familyName",
      "@nest": "name"
    }
  },
  "type": "Person",
  "name": {
    "first": "Jane",
    "middle": "",
    "last": "Doe"
  }
}

using @nest to keep the semantic granularity (see also playground)

Note:
``"@nest": "name"` is needed to reconstruct the nested JSON from RDF

However, any manipulation of the values itself (e.g. spliting or concatenate strings) is out of scope for JSON-LD
This, and complex shaping beyond JSON-LDs framing is usually the point were people introduce script languages to make arbitrary manipulations.
IMHO we should stick as long as possible to well established portable programming language agnostic query and template languages, e.g. JSONPath + mustache/handlebars (syntactical manipulation) or SPARQL CONSTRUCT (semantic manipulation).
E.g. SPARQL CONSTRUCT for the given case:

PREFIX schema: <https://schema.org/>

CONSTRUCT {
  ?person a schema:Person ;
          schema:name ?fullName .
}
WHERE {
  ?person a schema:Person .
  OPTIONAL { ?person schema:givenName ?first . }
  OPTIONAL { ?person schema:additionalName ?middle . }
  OPTIONAL { ?person schema:familyName ?last . }

  # Combine parts, collapse extra spaces, and trim leading/trailing spaces
  BIND(COALESCE(?first, "") AS ?f)
  BIND(COALESCE(?middle, "") AS ?m)
  BIND(COALESCE(?last, "") AS ?l)
  BIND(
    REPLACE(
      REPLACE(
        CONCAT(?f, " ", ?m, " ", ?l),
        "\\s+",
        " "
      ),
      "^\\s+|\\s+$",
      ""
    ) 
    AS ?fullName
  )
}

which gives us (after JSON-LD compacting)

{
  "type": "Person",
  "name": "Jane Doe"
}

If we realy need arbitrary code for very complex cases it would be nice to register typed functions semantically and deployable as REST endpoints, e.g.

from typing import Optional
from fastapi import FastAPI
from pydantic import BaseModel, ConfigDict
import re

app = FastAPI()

class PersonWithName(BaseModel):
    """
    schema.org Person with combined name
    """
    model_config = ConfigDict(
        json_schema_extra={
            "@context": {
                "schema": "https://schema.org/",
                "type": "@type",
                "Person": "schema:Person",
                "name": "schema:name"
            },
            "$id": "https://example.org/PersonWithName"
        }
    )
    type: Optional[str] = "Person"
    name: str
    """First and Last name combined"""

class PersonWithNameParts(BaseModel):
    """
    schema.org Person with separate name parts
    """
    model_config = ConfigDict(
        json_schema_extra={
            "@context": {
                "schema": "https://schema.org/",
                "type": "@type",
                "Person": "schema:Person",
                "first": "schema:givenName",
                "middle": "schema:additionalName",
                "last": "schema:familyName"
            },
            "$id": "https://example.org/PersonWithNameParts"
        }
    )
    type: Optional[str] = "Person"
    first: Optional[str] = None
    middle: Optional[str] = None
    last: Optional[str] = None

@app.post("/transform", response_model=PersonWithName)  # optional as API endpoint
def transform(person_parts: PersonWithNameParts) -> PersonWithName:
    f = person_parts.first or ""
    m = person_parts.middle or ""
    l = person_parts.last or ""

    # Concatenate with spaces, remove extra whitespace
    full_name = f"{f} {m} {l}"
    full_name = re.sub(r"\s+", " ", full_name)   # collapse multiple spaces
    full_name = re.sub(r"^\s+|\s+$", "", full_name)  # trim leading/trailing spaces

    return PersonWithName(name=full_name)