Linked Art API: Digital Reference Structure

Table of Contents

Introduction

There are many references to external digital resources that are necessary to include in a description of a core entity, including images of the entity or a web page about the entity. These references can be managed with separate records describing the various textual works, visual works and digital objects, however it is much easier and more usable to embed the information necessary within the record that the work depicts or describes. As such, this is a specific embedding case of the general pattern that can still be used when there is more information about the resources involved.

This is a complex shared structure in that it involves nested JSON objects rather than a single level. The first level is an embedded Textual or Visual Work, which then refers to an embedded Digital Object.

Property Definitions

Properties of Embedded Works

Property Name Datatype Requirement Description
id string Optional If present, the value MUST be a URI identifying the work, from which a representation of it can be retrieved
type string Required The class for the work, which MUST be the value "VisualItem" or "LinguisticObject"
_label string Optional A human readable label, intended for developers
_complete boolean Optional Non-Semantic. If there is an id property with a URI, and there is more information about the work available from the representation at that URI, then _complete MUST be present with a value of false to inform the consuming application that it might want to retrieve it
classified_as array Optional An array of json objects, each of which is a further classification of the work and MUST follow the requirements for Type
identified_by array Optional An array of json objects, each of which is a name for the work and follows the Name pattern
referred_to_by array Optional An array of json objects, each of which is an embedded statement about the work
digitally_shown_by array Required * Used only when type is "VisualItem". An array of json objects, each of which is a DigitalObject as described below
digitally_carried_by array Required * Used only when type is "LinguisticObject". An array of json objects, each of which is a DigitalObject as described below
language array Optional Used only when type is "LinguisticObject". An array of json objects, each of which is a language the text is expressed in, and MUST follow the requirements for Language

Properties of Embedded Digital Objects

Property Name Datatype Requirement Description
id string Optional If present, the value MUST be a URI identifying the digital object, from which a representation of it can be retrieved
type string Required The class for the work, which MUST be the value "DigitalObject"
_label string Optional A human readable label, intended for developers
_complete boolean Optional Non-Semantic. If there is an id property with a URI, and there is more information about the digital object available from the representation at that URI, then _complete MUST be present with a value of false to inform the consuming application that it might want to retrieve it
classified_as array Optional An array of json objects, each of which is a further classification of the digital object and MUST follow the requirements for Type
identified_by array Optional An array of json objects, each of which is a name for the digital object and follows the Name pattern
referred_to_by array Optional An array of json objects, each of which is an embedded statement about the digital object
access_point array Optional An array of json objects, each of which has only two properties: id which contains the URI where the representation of the described digital object can be retrieved, and type which has the value "DigitalObject". Both are required
digitally_available_via array Optional An array of json objects, each of which is a Digital Service structure, defined in the Digital Object documentation
format string Optional The media type of the described digital object, for example "image/jpeg"
conforms_to array Optional An array of json objects, each of which is a reference to an external specification that the current digital object conforms to. The type value of the reference MUST be "InformationObject"

Property Diagram

diagram

Incoming Properties

Name instances are typically found as the object of the following properties. This list is not exhaustive, but is intended to cover the likely cases.

Property Name Source Class Description
representation All When the Work is a Visual Item.
subject_of All When the Work is a Linguistic Object.

Example

An object has a home page at https://example.org/objects/1 which carries text in English.

{
  "@context": "https://linked.art/ns/v1/linked-art.json",
  "id": "https://linked.art/example/object/6",
  "type": "HumanMadeObject",
  "identified_by": [
    {
      "type": "Name",
      "classified_as": [
        {
          "id": "http://vocab.getty.edu/aat/300404670",
          "type": "Type",
          "_label": "Primary Name"
        }
      ],
      "content": "Object"
    }
  ],
  "subject_of": [
    {
      "type": "LinguisticObject",
      "language": [
        {
          "id": "http://vocab.getty.edu/aat/300388277",
          "type": "Language",
          "_label": "English"
        }
      ],
      "digitally_carried_by": [
        {
          "type": "DigitalObject",
          "classified_as": [
            {
              "id": "http://vocab.getty.edu/aat/300264578",
              "type": "Type",
              "_label": "Web Page"
            }
          ],
          "identified_by": [
            {
              "type": "Name",
              "classified_as": [
                {
                  "id": "http://vocab.getty.edu/aat/300404670",
                  "type": "Type",
                  "_label": "Primary Name"
                }
              ],
              "content": "Home page for Object"
            }
          ],
          "access_point": [
            {
              "id": "https://example.org/objects/1",
              "type": "DigitalObject"
            }
          ]
        }
      ]
    }
  ]
}

graph TD classDef object stroke:black,fill:#E1BA9C,rx:20px,ry:20px; classDef actor stroke:black,fill:#FFBDCA,rx:20px,ry:20px; classDef type stroke:red,fill:#FAB565,rx:20px,ry:20px; classDef name stroke:orange,fill:#FEF3BA,rx:20px,ry:20px; classDef dims stroke:black,fill:#c6c6c6,rx:20px,ry:20px; classDef infoobj stroke:#907010,fill:#fffa40,rx:20px,ry:20px classDef timespan stroke:blue,fill:#ddfffe,rx:20px,ry:20px classDef place stroke:#3a7a3a,fill:#aff090,rx:20px,ry:20px classDef event stroke:#1010FF,fill:#96e0f6,rx:20px,ry:20px classDef literal stroke:black,fill:#f0f0e0; classDef classstyle stroke:black,fill:white; O1(object/6) class O1 object; O1-- type -->O1_0[HumanMadeObject] class O1_0 classstyle; O2( _ ) class O2 name; O2-- type -->O2_0[Name] class O2_0 classstyle; O3(aat:300404670) class O3 type; O3-- type -->O3_0[Type] class O3_0 classstyle; O3-- _label -->O3_3("''Primary Name''") class O3_3 literal; O2-- classified_as -->O3 O2-- content -->O2_3("''Object''") class O2_3 literal; O1-- identified_by -->O2 O4( _ ) class O4 infoobj; O4-- type -->O4_0[LinguisticObject] class O4_0 classstyle; O5(aat:300388277) class O5 type; O5-- type -->O5_0[Language] class O5_0 classstyle; O5-- _label -->O5_3("''English''") class O5_3 literal; O4-- language -->O5 O6( _ ) class O6 digital; O6-- type -->O6_0[DigitalObject] class O6_0 classstyle; O7(aat:300264578) class O7 type; O7-- type -->O7_0[Type] class O7_0 classstyle; O7-- _label -->O7_3("''Web Page''") class O7_3 literal; O6-- classified_as -->O7 O8( _ ) class O8 name; O8-- type -->O8_0[Name] class O8_0 classstyle; O8-- classified_as -->O3 O8-- content -->O8_3("''Home page for Object''") class O8_3 literal; O6-- identified_by -->O8 O9(https://example.org/objects/1) class O9 digital; O9-- type -->O9_0[DigitalObject] class O9_0 classstyle; O6-- access_point -->O9 O4-- digitally_carried_by -->O6 O1-- subject_of -->O4
Other Representations: JSON-LD (raw) | JSON-LD (playground) | Turtle (raw) | Turtle (styled)