Skip to content

Reading results ​

Dates and periods ​

A date comes back at the precision its source gave: 1606 for a year, 1595-09 for a month, 1889-06-15 for a day. A filter bound takes the same forms, a year before 1 CE included (sdDatePublished: {min: "2024"}), and max reaches through the end of the period it names, so max: "1999" includes everything dated 1999. Date fields and range bounds are typed ISO8601Date, and a date facet’s buckets are DateBucket.

A period comes back as its source stated it, in EDTF: a work’s dateCreated and temporalCoverage, and a person’s birthDate and deathDate. A work made somewhere between 1935 and 1955 is 1935/1955, around 1620 is 1620~, in the 1620s is 162X. These fields are typed EDTF (a list for a work, and wrapped for temporalCoverage, below), and you render the qualifier in your reader’s language. They take the same DateRange filter, which matches every period that overlaps it: dateCreated: {min: "1940", max: "1950"} finds the work dated 1935/1955. A sort on one orders by where a period starts when ascending and by where it ends when descending. A period is not a valid filter bound itself – read 1935/1955 back and filter on {min: "1935", max: "1955"} – and it has no facet, since a period belongs in every bucket it overlaps.

A work’s temporalCoverage can also name its period instead of dating it, the way Tracé’s decorbladen say “19e/20e eeuw”. So each entry is a TermOrPeriod, with exactly one of two fields set: value, the EDTF period, or reference, the term, with its name like any other term reference. A term has no dates, so a DateRange filter on temporalCoverage matches only the entries that have a value:

graphql
{
  creativeWorks(perPage: 1) {
    items {
      temporalCoverage {
        value
        reference {
          name {
            value
          }
        }
      }
    }
  }
}

Images ​

Each reproduction of a work is one associatedMedia entry with its own URLs, license and attribution, so a work with several images keeps each image’s values together. A work that also publishes a IIIF Presentation manifest exposes it as iiifManifest – one field, however the publisher states it, so a IIIF-aware client reads that and never has to search associatedMedia for the manifest.

Lay out an image before it loads ​

A work with a IIIF Presentation manifest gets a representativeImage: the first image its manifest paints, with the image’s full width and height. That is enough to reserve each tile’s aspect ratio in a grid, so the layout holds still while the images arrive.

graphql
{
  creativeWorks(
    perPage: 10
    where: { associatedMedia: { where: { thumbnailUrl: { exists: true } } } }
  ) {
    items {
      name {
        value
      }
      representativeImage {
        url
        width
        height
        sizes {
          width
          height
          url
        }
        service {
          url
        }
      }
    }
  }
}
Run query

url is the image at full size. Where the image has a IIIF image service, sizes lists the smaller versions it serves, smallest first, each with a url that goes straight into a srcset – no IIIF Image API knowledge needed. service.url is the base to build any other size from. Limburgs Museum and Discovery Museum have image services. Drapo’s manifests paint plain JPEGs, so its works have no sizes: url is the only version, at the size the manifest states – 1466 × 2000 for this one.

representativeImage is null when:

  • the work has no manifest as an associatedMedia entry of its own. The older isBasedOn shape that iiifManifest still reads is not used here, so a work can have an iiifManifest and no representativeImage.
  • the manifest paints no image with an image service or a stated size.
  • the indexer has not read the manifest yet. Each run fetches manifests and image-service descriptions (info.json) for up to 30 minutes and keeps them for the next run, so a fresh index may get its images over more than one run.

Fall back to associatedMedia[].thumbnailUrl, which has no dimensions.

Who made a work ​

creator lists the agents who made the work, each a person or an organization. contributor lists the agents beside them – a printer, a manufacturer – as edges: each entry pairs the role a publisher stated with the agent it points at.

graphql
{
  creativeWorks(query: "Maastricht", perPage: 10) {
    items {
      name {
        value
      }
      creator {
        id
        name {
          value
        }
      }
      contributor {
        role
        contributor {
          id
          name {
            value
          }
        }
      }
    }
  }
}
Run query

A creator has no role: SCHEMA-AP-NDE forbids one there, and puts qualified roles on contributor. A contributor entry is a schema:Role edge, because the role belongs to neither the work nor the agent: the same person is drukker on one work and uitgever on another, and on one work an agent can be both.

Reading them:

  • an agent – a creator, or the inner contributor – is resolved out of the persons or the organizations collection. id, name, alternateName, authority and fetchedAt work on either; select __typename to tell which it is (PersonReference or OrganizationReference), and the rest of a kind’s own fields through an inline fragment – ... on PersonReference { birthDate }, see One artist, however many collections credit them. An agent is an organization where the publisher types it schema:Organization, and a person otherwise. Its id is null where the graph named the agent inline without a URI.
  • role is one of the publisher’s own literals, and is often absent – plenty of collections credit an agent without qualifying how. A Role stated in two languages, or naming two agents, is that many entries, so that each one answers this agent in this role. “etser”, “Etser” and “prentmaker” are three values.
  • a contributor entry itself has no id. The Role node behind it is an artefact of how a publisher modelled the edge – a fragment IRI for one, a blank node for the next – so it is not served, and two statements of one role-and-agent pair are one entry.

Filter on a creator by its id, and on a contributor in either of two ways:

graphql
where: { creator: { in: ["https://data.rkd.nl/artists/104628"] } }
where: { contributor: { in: ["https://data.rkd.nl/artists/104628"] } }
where: { contributor: { where: { contributor: { in: ["https://data.rkd.nl/artists/104628"] }, role: { in: ["fabrikant"] } } } }

The first two ask for works crediting that agent, as creator or in any role. In the third, sibling keys are welded to the same entry, so it asks this agent as a fabrikant rather than this agent somewhere and a fabrikant somewhere.

Facets on creator and contributor are keyed on the agent’s identity, never on the name, so two people who share one are never merged into a bucket. There is no facet over role, and cannot be: a facet cannot be scoped to the entry a filter matched, so it would count every role of every matching work.

Dimensions, and why values are nested ​

size does not return a string. It returns a list, with one entry per value the publisher states:

graphql
{
  creativeWorks(query: "litho", perPage: 10) {
    items {
      name {
        value
      }
      size {
        statement {
          value
          language
        }
        value
        unitCode {
          name {
            value
          }
        }
        unitText
        valueReference {
          name {
            value
          }
          sameAs
        }
        description {
          value
        }
      }
    }
  }
}
Run query

An entry is one of two kinds:

  • a statement: the publisher’s own display text, such as “150 cm” or “74 cm hoog bij 92 cm breed”, with its language. Only statement is set.
  • a measurement: one measured dimension of one part of the work. value is a number, unitCode the unit as a term or unitText as a label (“cm”), valueReference the dimension measured (height, width, depth) and description the part measured. statement is empty.

A lithograph in the Limburgs Museum collection has seven measurements, three of them heights:

valueReferencevalueunitTextdescription
hoogte17.2cmlitho
breedte23cm
hoogte24.3cmblad
breedte32.1cm
hoogte45cmpasse-partout
breedte60cm
diepte0.3cm

The print, the sheet and the mount are three different objects. Without description, 17.2 would read as the height of the work.

Why not a plain string? ​

If all you want is a line of text under an image, a nested structure is more work than a string. We return it anyway, for these reasons:

  • It follows SCHEMA-AP-NDE. The profile models a measurement as a schema:QuantitativeValue, and the field names are the profile’s own. If you know the profile, or Linked Art’s Dimension, which it maps onto one to one, you already know the shape.
  • Every value says what it is. A bare 17.2 could be a height, a width or a weight, in centimetres or millimetres, of the print or of its frame. The entry carries all of that with the number.
  • Nothing is dropped. A single value would have to choose. Before this field was a list, the index kept one of the seven measurements above, and a work that had both a statement and a measurement kept whichever came first.
  • You decide the presentation. value is a number, so you format it for your reader’s locale (17,2 in Dutch, 17.2 in English), and you choose the order, the separators and what to leave out. A string we composed would fix all of that in one language.
  • Terms compare across collections. Where a publisher gives one, valueReference.sameAs and unitCode.sameAs hold the term’s canonical URI, such as aat:300055644 for height. Two collections that use different words for one dimension share that URI. A string match cannot find that out.
  • It can grow without breaking you. Because value is already a number, sorting or filtering on dimensions can be added later without changing what the field returns.
  • The words are the publisher’s. We do not write a sentence on a publisher’s behalf. A measurement without a statement stays a measurement.

The same reasoning applies elsewhere in the API: associatedMedia, contributor and identifier are lists of entries for the same reason.

A string, if you want one ​

You only need a few lines on your side. Prefer the publisher’s statement, and compose the measurements otherwise:

js
function formatSize(entries, locale = 'nl') {
  const statements = entries.flatMap((entry) =>
    entry.statement.map((text) => text.value),
  );
  if (statements.length > 0) {
    return statements.join('; ');
  }
  const number = new Intl.NumberFormat(locale);
  return entries
    .map((entry) => {
      const dimension = entry.valueReference?.name[0]?.value;
      const unit = entry.unitCode?.name[0]?.value ?? entry.unitText;
      const part = entry.description[0]?.value;
      const amount = entry.value == null ? null : number.format(entry.value);
      return [dimension, amount, unit, part && `(${part})`]
        .filter(Boolean)
        .join(' ');
    })
    .join('; ');
}
// → "hoogte 17,2 cm (litho); breedte 23 cm; hoogte 24,3 cm (blad); …"

Pick name by language if you show more than one language.

What the data does today ​

Of the four collections indexed, two ship measurements and two do not:

  • Drapo states all 515 of its sizes as text, so every entry is a statement.
  • Limburgs Museum and Discovery Museum, both published through LDMax, ship 2018 and 373 measurements, with the dimension and the unit as labels ("hoogte"@nl, "cm") rather than terms – a shape the profile accepts when no term is known. So valueReference.name and unitText are filled, and sameAs and unitCode are empty.
  • Tracé states no sizes.

Neither LDMax collection ships a statement, so their works have measurements only.

Identifiers ​

identifier lists the identifiers a publisher assigned to a work, each with the value and, where the publisher said what kind of identifier it is, a propertyID.

graphql
{
  creativeWorks(query: "Maastricht", perPage: 10) {
    items {
      name {
        value
      }
      identifier {
        value
        propertyID
      }
    }
  }
}
Run query

SCHEMA-AP-NDE § 4.2.8 lets a publisher state each identifier as a plain string or as a schema:PropertyValue, and both arrive here as one list. A plain string has no propertyID. Limburgs Museum states its object number that way, G11125-19, beside the Axiell record number 12042 with propertyID https://data.axiell.com/vocabulary#Priref. Drapo states only PropertyValues, with a compact propertyID such as drapo:nodegoat_id. A propertyID is therefore an IRI or text, served as a string either way.

Which identifiers to show is the client’s call: to hide internal record numbers, skip the entries whose propertyID you don’t want, such as the Axiell priref. identifier cannot be filtered on yet: LDE filters a nested entry only through a reference to another collection, which an identifier does not have (ldelements/lde#1012).

Dataset details ​

A detail view usually has to say what dataset an object came from and on what terms: the license to honour, the institution to credit, and somewhere to send a visitor for the full record. A work carries the dataset it was indexed from, but only as a reference: an id and a label. So does an occupation. Places, persons, organizations and terms do not: each is keyed on a canonical identifier and shared by every dataset that references it, so one dataset value would name whichever was indexed last (One identity across datasets).

graphql
{
  creativeWorks(query: "vaandel", perPage: 1) {
    items {
      id
      name {
        value
      }
      dataset {
        id
      }
    }
  }
}
Run query

The terms live on the dataset, so take that id and ask the datasets collection:

graphql
{
  datasets(
    where: { id: { in: ["https://id.drapo.nl/dataset/drapo-schemaorg"] } }
  ) {
    items {
      name {
        value
        language
      }
      license
      landingPage
      publisher {
        id
        name {
          value
        }
      }
    }
  }
}
Run query

Two round trips, because there is no join yet, but only two for a whole page of results, not one per object: collect the distinct dataset ids from the page and pass them together, since a page of results usually shares a handful of datasets between them.

dataset and isPartOf both resolve against datasets, and they are not the same thing. dataset is a fact about the harvest: the dataset this document was drawn from, which is how the index knows it at all. isPartOf is a claim the publisher makes about the work, and a work may assert several. For a work drawn from the dataset it says it belongs to the two coincide – for any other value they do not, and only dataset tells you where the record came from. Where isPartOf names only the dataset the work was harvested from, it is left out, so it is usually absent.