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:
{
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.
{
creativeWorks(
perPage: 10
where: { associatedMedia: { where: { thumbnailUrl: { exists: true } } } }
) {
items {
name {
value
}
representativeImage {
url
width
height
sizes {
width
height
url
}
service {
url
}
}
}
}
} Run queryurl 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
associatedMediaentry of its own. The olderisBasedOnshape thatiiifManifeststill reads is not used here, so a work can have aniiifManifestand norepresentativeImage. - 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.
{
creativeWorks(query: "Maastricht", perPage: 10) {
items {
name {
value
}
creator {
id
name {
value
}
}
contributor {
role
contributor {
id
name {
value
}
}
}
}
}
} Run queryA 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 innercontributor– is resolved out of thepersonsor theorganizationscollection.id,name,alternateName,authorityandfetchedAtwork on either; select__typenameto tell which it is (PersonReferenceorOrganizationReference), 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 itschema:Organization, and a person otherwise. Itsidisnullwhere the graph named the agent inline without a URI. roleis 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:
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:
{
creativeWorks(query: "litho", perPage: 10) {
items {
name {
value
}
size {
statement {
value
language
}
value
unitCode {
name {
value
}
}
unitText
valueReference {
name {
value
}
sameAs
}
description {
value
}
}
}
}
} Run queryAn 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. Onlystatementis set. - a measurement: one measured dimension of one part of the work.
valueis a number,unitCodethe unit as a term orunitTextas a label (“cm”),valueReferencethe dimension measured (height, width, depth) anddescriptionthe part measured.statementis empty.
A lithograph in the Limburgs Museum collection has seven measurements, three of them heights:
valueReference | value | unitText | description |
|---|---|---|---|
| hoogte | 17.2 | cm | litho |
| breedte | 23 | cm | |
| hoogte | 24.3 | cm | blad |
| breedte | 32.1 | cm | |
| hoogte | 45 | cm | passe-partout |
| breedte | 60 | cm | |
| diepte | 0.3 | cm |
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’sDimension, which it maps onto one to one, you already know the shape. - Every value says what it is. A bare
17.2could 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.
valueis a number, so you format it for your reader’s locale (17,2in Dutch,17.2in 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.sameAsandunitCode.sameAshold the term’s canonical URI, such asaat:300055644for 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
valueis 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:
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. SovalueReference.nameandunitTextare filled, andsameAsandunitCodeare 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.
{
creativeWorks(query: "Maastricht", perPage: 10) {
items {
name {
value
}
identifier {
value
propertyID
}
}
}
} Run querySCHEMA-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).
{
creativeWorks(query: "vaandel", perPage: 1) {
items {
id
name {
value
}
dataset {
id
}
}
}
} Run queryThe terms live on the dataset, so take that id and ask the datasets collection:
{
datasets(
where: { id: { in: ["https://id.drapo.nl/dataset/drapo-schemaorg"] } }
) {
items {
name {
value
language
}
license
landingPage
publisher {
id
name {
value
}
}
}
}
} Run queryTwo 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.