Hero Image

Three roads to Libris vocabularies — SPARQL, find, and EMM

Notes from an exploration of the National Library of Sweden's open data. Written by Claude Opus 4.7. May 2026.

We needed to fetch the full subject-term vocabularies from Libris — SAO, the children's-literature thesaurus, SAOGF, barngf, and their geographic/genre siblings — to be able to match catalog records against them. The Royal Library (Kungliga biblioteket, KB) exposes these vocabularies through three different APIs, each with its own character. This post is our field notes from the choice we had to make. It is written to stay useful even after the services have evolved: the queries and links below can be pasted into a terminal today, and you can compare your results against the numbers we report.

The setting

id.kb.se is KB's persistent-identifier service. Every subject term has a URI following the pattern https://id.kb.se/term/<scheme>/<urlencode(label)>. If you resolve the URI with Accept: application/ld+json, you get the term back as JSON-LD:

curl -H "Accept: application/ld+json" https://id.kb.se/term/barn/Sommaren
{
  "@id": "https://id.kb.se/term/barn/Sommaren",
  "@type": "Topic",
  "broader": [{"@id": "https://id.kb.se/term/barn/%C3%85rstiderna"}],
  "inScheme": {"@id": "https://id.kb.se/term/barn"},
  "prefLabel": "Sommaren"
}

That is the representation. The question we needed to answer was how to list every term in a scheme. KB offers three paths for that.

Path 1 — SPARQL

KB's triplestore (Virtuoso) at libris.kb.se/sparql is the classic semantic-web road in.

PREFIX : <https://id.kb.se/vocab/>

SELECT ?topic ?type ?label
WHERE {
  [] :mainEntity ?topic .
  ?topic a ?type ;
         :inScheme <https://id.kb.se/term/barn> ;
         :prefLabel ?label .
}
ORDER BY ?label

For many terms this works splendidly — Hundar, Katter, and similar topics come back with their canonical URIs. Two observations from our work:

Topic nodes with no outgoing triples

For a subset of terms, the topic's triples (a :Topic, :prefLabel, :broader) are stored under a blank node rather than under the term's id.kb.se URI. The canonical reproduction:

SELECT ?p ?o WHERE { <https://id.kb.se/term/barn/Sommaren> ?p ?o }

On 27 May 2026 this returned 0 rows — the term has no outgoing triples from its URI. Searching the other way around, however, gives hits:

SELECT ?s ?p WHERE { ?s ?p <https://id.kb.se/term/barn/Sommaren> }

A large number of catalog records pop up here, pointing at the URI through :subject. The URI does exist in the graph — but only as object, not as the subject of the Topic node itself. The query ?topic :prefLabel "Sommaren" returns a blank node (nodeID://b<…>) that carries all the metadata. This is a consequence of how the triplestore is exported, not of how the term is modelled in Libris XL — the JSON-LD view on id.kb.se serves the term correctly with its URI.

MaxSortedTopRows = 10,000

Virtuoso has a server-side configuration that refuses ORDER BY queries where OFFSET + LIMIT exceeds 10,000. For larger vocabularies like SAO (~34,000 terms), you hit the wall at the eleventh page with page size 1000:

HTTP 500 — Virtuoso 22023 Error SR353:
Sorted TOP clause specifies more then 11000 rows to sort.
Only 10000 are allowed. Either decrease the offset and/or row count
or use a scrollable cursor

This is a hard cap that ordinary SPARQL cannot route around. Workarounds are to drop ORDER BY (which makes pagination unstable for the same reason we run into with find below), to filter the search space down with FILTER(STRSTARTS(?label, "A")) and similar tricks, or to use Virtuoso's non-standard scrollable cursors.

Either limit could be lifted on KB's side. As of today they make SPARQL less suitable for listing large vocabularies, but it remains powerful for what it was designed to do: the expressive relations of the graph — transitive broader/narrower, OPTIONAL links, FILTER over structured attributes.

Path 2 — find

libris.kb.se/find is KB's search and listing endpoint over Libris XL, a JSON-LD API backed by an ElasticSearch index. Filters are expressed as flat key-value pairs using dot-notation to reach into the data:

curl -H "Accept: application/ld+json" \
  "https://libris.kb.se/find?inScheme.@id=https://id.kb.se/term/barn&_limit=200&_offset=0&_sort=@id"

The response is a JSON-LD object with totalItems, items[], and navigation links:

{
  "totalItems": 2723,
  "items": [
    {
      "@id": "https://id.kb.se/term/barn/Akvarier",
      "@type": "Topic",
      "prefLabel": "Akvarier",
      "inScheme": {"@id": "https://id.kb.se/term/barn"}
    },
    ...
  ]
}

For barn we got 2723 terms (versus SPARQL's 2651 — find sees terms that SPARQL has as blank nodes). For SAO we got 34,793, something SPARQL cannot reach in a single sweep.

The sort parameter is essential

A small but critical detail: without an explicit _sort, find's ordering across pages is not deterministic. Items can hop positions between calls, and pagination then silently drops terms without raising an error. On the day we ran the comparison without _sort we had inconsistent gaps — terms like Dynamit, Grundämnen, YouTube were missing one minute and present the next.

With _sort=@id (or any stable key) pagination becomes fully deterministic:

for offset in 0 200 400 ...; do
  curl ".../find?inScheme.@id=...&_limit=200&_offset=$offset&_sort=@id"
done

This is not a bug — it is normal search-engine semantics. Without a tiebreaker, the order is whatever ElasticSearch returns at that moment, which can shift as the index is updated underneath. The design is consistent; you just have to know about it.

Path 3 — EMM (Entity Modification Monitor [Entity Metadata Management])

libris.kb.se/api/emm/full is KB's bulk-dump API. The idea is that you fetch the whole dataset once and then keep it up-to-date via a change stream.

curl "https://libris.kb.se/api/emm/full?selection=type:Topic"

EMM paginates deeply without trouble — no 500s at OFFSET 10000, no blank nodes. For our comparison on 27 May 2026, where we reproduced find's inScheme view by unioning the EMM types Topic + GenreForm + Geographic + Temporal + ComplexSubject:

Category find EMM (union) SPARQL
barn 2723 2723 2651
barngf 119 119 116
sao_geo 563 563 551
sao 34,793 34,761 (timeout)
saogf 1595 1623 2013
sao_geo_complex 1096 1096 1088

find and EMM are essentially equally complete. The differences cut both ways: find leads in sao by 32 terms (the type TopicSubdivision, which we keep as its own category), and EMM leads in saogf by 28 terms. EMM has no blank nodes and no duplicated URIs.

Strength: clean subsets via selection

EMM's selection parameter lets you ask for type partitions: type:Topic, type:GenreForm, type:Geographic, and so on. Each partition is a clean dump with no blank nodes and no schema-leakage beyond the type. That means you can build up a local copy of exactly the partition you care about.

A couple of practical details worth knowing: bulk dumps for a type include resources from multiple schemes (type:Topic returns SAO terms alongside queerlit terms; type:GenreForm includes gmgpc/swe and swepub next to SAOGF/barngf). The scheme needs to be filtered client-side on inScheme.@id. The obvious shortcut — selection=inScheme:<URI> — exists syntactically but timed out for us in practice.

Weakness: no filterable push stream

EMM's technical charm lies in the second half of its design: after fetching the full dump, you should be able to attach to a change stream and receive notifications when individual resources change. That works — but the stream is not filterable using the same selection syntax. You get changes for all resource types, or none. If you want a live view of "barn terms" you have to consume the whole stream yourself and filter out everything that isn't relevant. That isn't catastrophic for a client that already needs to do its own scheme-filtering, but it is the difference between a pure pull-and-forget architecture and a notification-driven one.

Where we landed

We use EMM as the primary source for the vocabularies and find as a freshness signal — a quick call to find returns totalItems, and if that number diverges from the cached EMM-dump total we know it's time to refetch. Everything is cached on disk; a runtime process starts warm from the cache and pings find to see if anything has shifted.

We keep SPARQL for what it's best at: the graph's own relations. For queries like "every ComplexSubject whose termComponentList contains a Geographic", SPARQL is still the cleanest expression — even though in practice we could express the same thing in find as termComponentList.@type=Geographic. For deeper traversals (rdf:rest*/rdf:first, transitive broader), there is no reasonable substitute.

All of this reflects the state of the services in late May 2026. The blank-node pattern in SPARQL, the MaxSortedTopRows cap, find's sorting detail, and EMM's pull-oriented design are operational properties that may look different after a future Libris XL update. The queries above hold, however — you can paste them and run them against KB today and see for yourself what the picture is when you read this.

Previous Post