Candidate Requirements for Network of Terms Implementations

Living Standard,

This version:
https://docs.nde.nl/requirements-network-of-terms-implementations/
Issue Tracking:
GitHub
Editor:
David de Boer (Netwerk Digitaal Erfgoed)
Version:
0.2.0

CC0 To the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 4 March 2026, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0, which is available at https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0. Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document.

Abstract

This document describes requirements for implementing the Network of Terms API in collection management systems. By following these requirements, implementers enable users to efficiently search for and link to terms from terminology sources.

1. Introduction

This section is non-normative.

The Requirements for Collection Management Systems include a general obligation for vendors to implement the Network of Terms API in their collection management systems. However, feedback from users of these systems, as well as questions from vendors, has shown the need for more detailed guidance. The requirements below provide such guidance, specifying in more detail the steps needed for performant and user-friendly implementations of the Network of Terms. The goal is to help both users and vendors.

2. Definitions

Collection manager

A person who creates metadata records in a collection management system and links terms to those records.

Configurator

A special type of collection manager who configures the collection management system for searching the Network of Terms, without requiring vendor modifications.

Collection management system

A software application for creating, editing, and publishing metadata records that implements the Network of Terms API.

Term

A concept from a terminology source, identified by a URI, with properties such as prefLabel, altLabel, scopeNote, and broader/narrower relations.

Terminology source

A source of terms, such as a thesaurus or vocabulary, that is available through the Network of Terms.

Vendor

An organization that supplies a collection management system.

3. Requirements

These requirements are organized into four phases: selecting sources, searching terms, viewing terms, and publishing links.

3.1. Terminology sources

3.1.1. Search in selected sources

Searches by collection managers MUST be executed only in selected terminology sources and MUST NOT default to searching all sources.

NDE has observed implementations querying all sources by default. This makes users wait needlessly for slow sources and puts unnecessary load on terminology sources.

3.1.2. Select sources

Configurators MUST be able to select which terminology sources are available for searching in the collection management system without requiring vendor involvement.

Allowing customers to make their own selection, and being able to adapt it later as need arises, improves the adoption speed of the Network of Terms.

3.1.3. New sources immediately available

When new terminology sources are added to the Network of Terms, they MUST become available to configurators for selection.

Dependence on vendors to add terminology sources delays collection managers from being able to use new sources.

3.1.4. Identify sources by URI

Terminology sources MUST be identified by their dataset URI. Distribution information MUST NOT be hardcoded but MUST be retrieved dynamically from the Network of Terms.

Distribution information may change over time (e.g. a terminology source’s SPARQL endpoint), but the dataset URI will remain the same.

3.2. Search terms

3.2.1. Debounce queries

Collection management systems MUST debounce search queries by collection managers.

This prevents excessive requests to terminology sources while the collection manager is still typing.

3.2.2. Minimum query length

Collection management systems MUST NOT send queries shorter than 3 characters to the Network of Terms.

Many terminology sources don’t handle short search strings well.

3.2.3. Display complete term information

All information from the Network of Terms MUST be accessible in search results without truncation, including prefLabel, altLabel, scopeNote, and broader/narrower terms.

Collection managers need to see all relevant information about terms to differentiate terms and make informed decisions about which terms to link.

3.2.4. Display source information

For each term, its source MUST be shown, including the source’s name and alternateName (short name), and the creator’s name and alternateName.

This helps collection managers select a term from a source appropriate to the resource and the property they are editing, for example ‘material’.

3.2.5. Display error messages

Errors from the Network of Terms API MUST be shown to collection managers.

The Network of Terms queries terminology sources in real time. Each source returns either a list of terms or an error. The API defines two error types:

Because errors are reported per source, other sources may still return results successfully. Displaying these errors communicates to collection managers that some sources may be periodically unavailable, through no fault of the Network of Terms.

3.2.6. Send multilingual queries

Collection management systems MUST include a languages parameter in queries to the Network of Terms.

Without a language parameter, the Network of Terms returns labels in all available languages combined in a single search result, which is confusing and hard to read.

3.2.7. Identify client in requests

Collection management systems MUST send a User-Agent HTTP header identifying the system and its version to the Network of Terms.

This helps NDE to monitor usage and advise vendors in optimizing their implementations.

3.2.8. Distinguish previously linked terms

Collection management systems MAY visually distinguish previously linked terms in search results through highlighting or prioritization.

When collection managers reuse previously linked terms, this improves consistency within the dataset and strengthens interlinking between datasets.

3.3. View terms

3.3.1. Store term URIs

The URI for each linked term MUST be stored in the collection management system.

To maintain stable references to terms, implementations must store the term’s identifier. This also enables looking up the term later, to refresh its information in the collection management system.

3.3.2. Display term information

When viewing metadata records in the collection management system, all linked term information MUST be displayed, including term information and source information.

This provides context to collection managers when they are viewing records.

3.3.3. Cache term information

Term information MAY be cached but MUST then be refreshed from the Network of Terms at a configurable interval.

Caching reduces load on terminology sources. However, users must be presented with recent term information.

3.4.1. Publish term URIs

Linked term URIs MUST be included in published datasets. The term’s prefLabel SHOULD be included as a literal value alongside the URI.

Consumers of the dataset should have access to linked terms. This requirement is in accordance with Schema.org Application Profile for NDE § reference-terms.

4. Changes

4.1. Version 0.2.0 (2026-03-04)

4.2. Version 0.1.0 (2026-03-04)

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

References

Normative References

[NDE-CMS]
Gertjan Filarski; Enno Meijers. Requirements for Collection Management Systems. URL: https://docs.nde.nl/requirements-collection-management-systems/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[SCHEMA-AP-NDE]
David de Boer. Schema.org Application Profile for NDE. URL: https://docs.nde.nl/schema-profile/