Linked Art API: Reference Structure

Table of Contents

Introduction

As with any hypermedia API, and especially those based on linked open data, the Linked Art API makes frequent use of references between resources. These references are designed to be recognizable as such, but still contain a minimum of information needed to understand what the reference is to.

It is very likely that more information about the referenced resource will be needed by the user interface, however it is impossible to know a priori what that information is. Clients should be pro-active about aggressively following references and pre-caching the descriptions to enable a responsive user interface.

Property Definitions

References can only have the three properties below, in order to make it clear that it is a reference to an external resource rather than one that is being embedded within the current JSON document. The URI in id and the class in type MUST be the same as the referenced resource, once the URI has been dereferenced. The label, however, MAY be different.

Types are a special case of a reference to an external entry in a vocabulary system. As noted in the type documentation, they may also have meta-classifications to ensure that they can be processed, as dereferencing the type's URI might not result in a Linked Art formatted description.

Note that references inherently have the _complete property with a value of false. They can be detected as references as all other structures have mandatory fields beyond id, type and _label. The _complete property would thus be clutter in the most common scenario of shared constructions being fully included, and data for references not being included at all.

There are two additional properties that MAY be used on references to ensure that the records are as usable as possible. If the reference is to a record for an entity which has an equivalent in a well known system (such as a local concept that duplicates a concept in AAT), then the local record's URI can be given in id and the external URI given in equivalent. Similarly, if the language tag for a Language is known, then that is easier for most developers to use with existing translation and internationalization toolkits, and so can be given in lang_code as part of the reference.

Properties of References

Property Name Datatype Requirement Description
id string Required The value MUST be a dereferenceable URI identifying the referenced resource
type string Required The value MUST be the same as the type of the referenced resource
_label string Recommended A human readable label for the referenced resource, intended for developers
equivalent array Optional An array of references to external resources which are equivalent to the referenced resource
notation array Optional An array of strings, each of which is a commonly used notation or identifier for the resource. This is typically used when the type of the reference is Language and gives the language tag.

Note that references do not have _complete -- they are inherently not complete, otherwise they wouldn't be references.

There are too many incoming properties to try to list them all, as it amounts to the list of all properties for all classes.

Example

A Painting, which has several references to other entities:

{
  "@context": "https://linked.art/ns/v1/linked-art.json",
  "id": "https://linked.art/example/object/11",
  "type": "HumanMadeObject",
  "_label": "Example Painting",
  "classified_as": [
    {
      "id": "http://vocab.getty.edu/aat/300033618",
      "type": "Type",
      "_label": "Painting",
      "classified_as": [
        {
          "id": "http://vocab.getty.edu/aat/300435443",
          "type": "Type",
          "_label": "Type of Work"
        }
      ]
    }
  ],
  "referred_to_by": [
    {
      "type": "LinguisticObject",
      "_label": "Article about Painting"
    }
  ],
  "member_of": [
    {
      "type": "Set",
      "_label": "Museum Collection"
    }
  ],
  "shows": [
    {
      "type": "VisualItem",
      "_label": "Visual Work of Example Painting"
    }
  ],
  "current_owner": [
    {
      "type": "Person",
      "_label": "Owner"
    }
  ],
  "current_location": {
    "type": "Place",
    "_label": "Gallery"
  }
}

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/11) class O1 object; O1-- type -->O1_0[HumanMadeObject] class O1_0 classstyle; O1-- _label -->O1_4("''Example Painting''") class O1_4 literal; O2(aat:300033618) class O2 type; O2-- type -->O2_0[Type] class O2_0 classstyle; O2-- _label -->O2_3("''Painting''") class O2_3 literal; O3(aat:300435443) class O3 type; O3-- type -->O3_0[Type] class O3_0 classstyle; O3-- _label -->O3_3("''Type of Work''") class O3_3 literal; O2-- classified_as -->O3 O1-- classified_as -->O2 O4( _ ) class O4 infoobj; O4-- type -->O4_0[LinguisticObject] class O4_0 classstyle; O4-- _label -->O4_2("''Article about Painting''") class O4_2 literal; O1-- referred_to_by -->O4 O5( _ ) class O5 infoobj; O5-- type -->O5_0[Set] class O5_0 classstyle; O5-- _label -->O5_2("''Museum Collection''") class O5_2 literal; O1-- member_of -->O5 O6( _ ) class O6 infoobj; O6-- type -->O6_0[VisualItem] class O6_0 classstyle; O6-- _label -->O6_2("''Visual Work of Example Painting''") class O6_2 literal; O1-- shows -->O6 O7( _ ) class O7 actor; O7-- type -->O7_0[Person] class O7_0 classstyle; O7-- _label -->O7_2("''Owner''") class O7_2 literal; O1-- current_owner -->O7 O8( _ ) class O8 place; O8-- type -->O8_0[Place] class O8_0 classstyle; O8-- _label -->O8_2("''Gallery''") class O8_2 literal; O1-- current_location -->O8
Other Representations: JSON-LD (raw) | JSON-LD (playground) | Turtle (raw) | Turtle (styled)