Orientation for developers

If you're a developer already familiar with linked data, or you just need some waypoints to get data in or out of the model, these are the basics.

Data format and releases

The data for the Duchamp Research Portal is available in versioned releases on GitHub, as both JSON-LD and RDF/Turtle. The JSON-LD is framed from the perspective of a few core classes--ManMadeObject (for archival objects, library books, art objects, and ephemera), PhysicalObject (for collective objects), Actor (for people and organizations), Event (for exhibitions), and Aggregation (for cross-entity relationships).

All top-level entity URIs also return a JSON-LD document in response to HTTP(S) requests:

Request

URL : /object/123.json

METHOD: GET

HEADER: Accept: application/json, Content-Type: application/json

Response

{
    "id": "http://example_document_here"
}

JSON-LD data basics

While the site's data releases contain the data in full fidelity as RDF, our expectation is that most developers will use the documentized JSON-LD form. The most minimal example of this would be a snippet like:

{
    "@context": "https://linked.art/ns/v1/linked-art.json",
    "id": "http://ex.com/obj1",
    "type": "ManMadeObject"
}

which expresses that the object "http://ex.com/obj1" has the type ManMadeObject.

Data model

The Portal's data model adapts an early version of the Linked.Art model, a profile of the CIDOC-CRM content reference model that attempts to map knowledge as stateful classes representing objects / people / things that interact with creation / destruction / use events. Thus to express the makers of an object, linked.art describes an object's having been produced_by an event that itself was carried_out_by an actor:

{
    "@context": "https://linked.art/ns/v1/linked-art.json",
    "id": "http://ex.com/obj1",
    "produced_by": {
        "id": "http://ex.com/obj1/production",
        "carried_out_by": [
            {
                "id": "http://ex.com/actor1",
                "label": "Jane Painter"
            }
        ]
    }
}

Data Classes

The model uses five core classes:

  • ManMadeObject
  • PhysicalObject
  • Actor
  • Event
  • Aggregation

Using the field mappings

For ease of access, this reference site contains a set of field mappings that demonstrate basic properties for objects, people, events, and relationships. Each contains an example snippet of real production data for a property, an example of source data for that property, its field name on the site's Elasticsearch cluster, and a graph showing its model.

A single field mapping gives you a sense of how to feed new data into that property, how to use that property in your own projects, and how similar data might be mapped.

"Do I need a triplestore?"

Perhaps, but not unless you know you do. While the DRP site pipelines use a triplestore to produce this data, managing the triplestore and handling performance optimization on queries is not for the faint of heart. SPARQL query efficiency is explicitly and understandably not in scope for Linked Art, and the same is true for this project.

In cases where you're just dereferencing object properties and feeding them to something else, it's probably easiest to use the JSON-LD documents as if they were JSON.

Likewise, the JSON-LD APIs for framing, compacting, normalizing, and flattening give powerful intra-document reshaping tools in one declarative command. For example, this site's field mapping diagrams use flattening to produce a complete list of the document's tree of nodes and properties, which it then turns into Mermaid markup. As long as your needs around inter-document linking are limited (or can be replicated with a faceted search index) there's no need to take on the overhead of a triplestore.

That said, JSON-LD is designed to give full fidelity to linked data as statements as well, so if you have extensive cross-entity needs then a triplestore may be sensible. We use Neptune or RDF4J in a docker image to reduce the number of custom management aspects.

References