Requirements for Datasets

1. Introduction

This section is non-normative.

To enable datasets to be found and used, they must be described according to a well-documented, shared and machine-readable publication model.

This document describes such a model and its rules. When publishers make their dataset descriptions adhere to these rules, they enable consumers – both humans and machines – to use the datasets in new and better ways.

These requirements prescribe the metadata that publishers must provide for their dataset. This metadata tells consumers:

• what the dataset is called and under what license it is published (§ 5.2 Dataset information);

• which person/organization has published the dataset (§ 5.3 Creator/publisher information);

• where the data can be found (§ 5.4 Distributions).

1.1. Audience

This document is mainly geared towards two groups of readers.

Digital heritage collection managers can follow the requirements in this document to make their published datasets findable and usable, for instance through Google Dataset Search and the NDE Dataset Register.

Suppliers of collection management systems can implement these requirements in their software to help collection managers using it to publish datasets in the correct format. These requirements are scoped to the online publication output of collection management systems; they do not prescribe how those systems should store data internally.

1.2. Context

While focused on digital heritage institutions in The Netherlands, this document is based on broader, international best practices for publishing datasets, including [DWBP-UCR], [DWBP] and [LD-BP].

These requirements incorporate a previous publication model, which provides more background on choices made here.

1.3. Code examples

Publishers can describe their datasets in either of two vocabularies: Schema.org [SCHEMA-ORG] or DCAT-AP-NL 3.0 [DCAT-AP-NL], the Dutch application profile of [VOCAB-DCAT-3]. The NDE Dataset Register accepts both and converts every dataset description to DCAT-AP-NL 3.0. Search engines such as Google Dataset Search read Schema.org; DCAT-AP-NL 3.0 is the standard for Dutch government data catalogs.

Every RDF code example is given in both vocabularies, serialized as [JSON-LD]. Use the tabs above an example to switch between them; all examples and attribute tables switch together.

2. Version 2.0

Version 2.0 takes effect on Monday 3 May 2027. Until that date, the NDE Dataset Register accepts dataset descriptions that break a version 2.0 rule and reports each broken rule as a warning. From that date, it rejects new and updated dataset descriptions that break one. A dataset without a creator (schema:creator or dct:creator), for example, is registered with a warning before that date and refused from it.

A dataset that is already registered is not removed on that date. If its description breaks a version 2.0 rule, the Register marks it as invalid the next time it reads the description.

The changes follow DCAT-AP-NL 3.0, the format into which the Register converts every dataset description. The attribute tables in § 5.6 Overview of attributes mark each affected attribute with a label such as ‘v2.0: becomes required’. Run your datasets through the validator: the warnings it gives are the changes that apply to you. The announcement gives the reasons.

3. Definitions

Dataset

A collection of metadata records. These are made available through the dataset’s distributions.

Dataset description

Metadata about the dataset, including the dataset’s name and publisher. This description must be distinguished from the metadata records themselves.

For example: imagine a dataset of Van Gogh paintings called ‘Sunflowers’, which is published by the Van Gogh Museum under a specific license. The name, license and publisher are all part of the dataset description. The dataset description also tells us the URLs of distributions where we can download or query the data. Using these distributions, we can access the metadata records themselves, which may include descriptions of paintings, persons, places etc. These are not part of the dataset description.

Data catalog

A collection of dataset descriptions.

Distribution

A channel through which a dataset is made available, either for downloading (such as a CSV file download or RDF dump), or for querying (such as a SPARQL endpoint).

Web API

An API that is available over HTTP, for example an OAI-PMH, OpenAPI or SPARQL endpoint.

Machine-readability

TODO

Publisher

An individual or organization that provides one or more datasets.

is this a good translation for ‘bronhouder’? And add examples. This would probably be 'heritage institution' in DERA.

Consumer

On organization, individual or service platform that uses one or more datasets that are provided by a publisher.

4. Conceptual model

The model consists of four resource types: organizations or persons publish datasets, which are available in distributions. Optionally, the datasets are grouped in data catalogs.

5. Requirements

5.1. Available in RDF

For machine-readable access to data, it needs to be published in an RDF format. RDF formats include [JSON-LD], [Turtle] and [TriG].

Publishers MUST make their dataset description available in RDF.

Publishers MAY use either the Schema.org [SCHEMA-ORG] or the DCAT-AP-NL 3.0 [DCAT-AP-NL] vocabulary (see § 1.3 Code examples).

<html>
  <head>
    <title>Koninklijke Bibliotheek</title>
    <script type="application/ld+json">
      {
        "@context": "https://schema.org/",
        "@type": "Organization",
        "@id": "http://www.wikidata.org/entity/Q1526131",
        "name": {
          "@value": "Koninklijke Bibliotheek",
          "@language": "nl"
        }
      }
    </script>
  </head>
  <body>
    Here continues the web page of the organization...
  </body>
</html>

<html>
  <head>
    <title>Koninklijke Bibliotheek</title>
    <script type="application/ld+json">
      {
        "@context": {
          "foaf": "http://xmlns.com/foaf/0.1/"
        },
        "@type": "foaf:Organization",
        "@id": "http://www.wikidata.org/entity/Q1526131",
        "foaf:name": {
          "@value": "Koninklijke Bibliotheek",
          "@language": "nl"
        }
      }
    </script>
  </head>
  <body>
    Here continues the web page of the organization...
  </body>
</html>

See also Data on the Web Best Practices Use Cases & Requirements § R-FormatMachineRead.

5.1.1. Content-Type

Clients that retrieve dataset descriptions rely on the HTTP Content-Type header to determine how the response should be parsed.

Therefore, the URL at which a dataset description is published MUST be served with a Content-Type header whose media type matches the RDF serialization of the response body.

Recognized RDF media types include application/ld+json for [JSON-LD], text/turtle for [Turtle], application/n-triples for [N-TRIPLES] and application/rdf+xml for RDF/XML. When the dataset description is embedded in an HTML page (see § 5.1 Available in RDF), text/html is acceptable.

5.1.2. Durable identifiers

Consumers want to refer to datasets. They prefer to do so by linking to them.

Therefore, publishers MUST maintain a permanent and unique identifier for each dataset. Publishers MUST use HTTP IRIs as identifiers.

See also Data on the Web Best Practices Use Cases & Requirements § R-UniqueIdentifier and Data on the Web Best Practices Use Cases & Requirements § R-PersistentIdentification.

5.1.3. Resolvable dataset IRIs

Consumers want to look up a dataset by its IRI. When the dataset IRI resolves, consumers can retrieve both the machine-readable dataset description (via content negotiation) and a human-readable HTML page without needing a separate landing page URL.

Therefore, publishers SHOULD ensure that the dataset IRI resolves and serves both an RDF representation (the dataset description) and an HTML representation. The HTML representation MUST be consistent with and include at least all details (such as distributions) from the RDF representation.

When the dataset IRI resolves to an HTML page, a separate schema:mainEntityOfPage or dcat:landingPage is not needed (see § 5.2.5 More information).

5.1.4. Information remains available

Datasets will be used by all kinds of consumers and their systems. For stability, users must be able to trust that the datasets will remain available so they can be consulted in the future.

Therefore, publishers MUST ensure information remains available in the future.

5.2. Dataset information

Consumers want to consult information about the dataset to decide whether and how they want to use its data. This information answers user questions such as:

• What is the name of the dataset?

• What is the dataset about? What kind of data does the dataset contain?

• How recent is the data? When was the dataset last published?

• How can I use the data? Are there any restrictions? Under which license is the data published?

• Where can I get the data? In what formats?

5.2.1. Basic information

Publishers MUST include basic information about the dataset, at the very minimum its HTTP [IRI] and name.

{
  "@context": "https://schema.org/",
  "@type": "Dataset",
  "@id": "http://data.bibliotheken.nl/doc/dataset/rise-alba",
  "name": [
    {
      "@value": "Alba amicorum van de Koninklijke Bibliotheek",
      "@language": "nl"
    },
    {
      "@value": "Alba amicorum of the Dutch Royal Library",
      "@language": "en"
    }
  ]
}

{
  "@context": {
    "dcat": "http://www.w3.org/ns/dcat#",
    "dct": "http://purl.org/dc/terms/"
  },
  "@type": "dcat:Dataset",
  "@id": "http://data.bibliotheken.nl/doc/dataset/rise-alba",
  "dct:title": [
    {
      "@value": "Alba amicorum van de Koninklijke Bibliotheek",
      "@language": "nl"
    },
    {
      "@value": "Alba amicorum of the Dutch Royal Library",
      "@language": "en"
    }
  ]
}

5.2.2. License

License applicable to the dataset. This license is inherited by all distributions that do not specify their own license. Publishers MUST make known under which license the dataset may be used.

This license specifies the conditions under which the metadata records in the dataset may be accessed and reused. It does not cover the heritage objects (either physical or digital) that the metadata describes. Access conditions for these objects should be specified in their own descriptions within the dataset.

The DERA requires metadata to be published openly, so this value SHOULD be an open license that allows consumers to reuse the data, such as http://creativecommons.org/publicdomain/zero/1.0/ (CC0), http://creativecommons.org/licenses/by/4.0/ (CC BY 4.0), or http://creativecommons.org/licenses/by-sa/4.0/ (CC BY-SA 4.0). Adopting a non-open license will severely limit reuse and does not comply with the DERA principles.

The value MUST be the canonical URI of a license. For example, use http://creativecommons.org/publicdomain/zero/1.0/ instead of http://creativecommons.org/publicdomain/zero/1.0/deed.nl.

{
  "@context": "https://schema.org/",
  "@type": "Dataset",
  "license": "http://creativecommons.org/publicdomain/zero/1.0/"
}

{
  "@context": {
    "dcat": "http://www.w3.org/ns/dcat#",
    "dct": "http://purl.org/dc/terms/"
  },
  "@type": "dcat:Dataset",
  "dcat:distribution": {
    "@type": "dcat:Distribution",
    "dct:license": {
      "@id": "http://creativecommons.org/publicdomain/zero/1.0/"
    }
  }
}

DCAT-AP-NL 3.0 [DCAT-AP-NL] requires the use of Creative Commons licences and defines a value list for licences. The default SHOULD be CC0 (http://creativecommons.org/publicdomain/zero/1.0/). The following table lists the recommended canonical license IRIs. Creative Commons IRIs MUST end with a trailing slash. They MAY use http:// or https://; the Register stores them as http://, the canonical form in Creative Commons’ own RDF.

See also Data on the Web Best Practices Use Cases & Requirements § R-LicenseAvailable.

5.2.3. Creation, publication and modification dates

Publishers SHOULD make known when the dataset description was originally created, published and when it was last updated. The dates MUST be valid according to [ISO8601].

{
  "@context": "https://schema.org/",
  "@type": "Dataset",
  "dateCreated": "2019-04-14",
  "datePublished": "2019-05-21",
  "dateModified": "2019-08-15"
}

{
  "@context": {
    "dcat": "http://www.w3.org/ns/dcat#",
    "dct": "http://purl.org/dc/terms/",
    "xsd": "http://www.w3.org/2001/XMLSchema#"
  },
  "@type": "dcat:Dataset",
  "dct:created": { "@value": "2019-04-14", "@type": "xsd:date" },
  "dct:issued": { "@value": "2019-05-21", "@type": "xsd:date" },
  "dct:modified": { "@value": "2019-08-15", "@type": "xsd:date" }
}

5.2.4. Versions

A dataset description may change over time. Consumers, such as researchers, may want to determine which information was valid at a certain moment.

Therefore, publishers SHOULD not only publish the current version of the dataset description, but keep historical versions accessible to users.

It is up to the publisher to determine when to publish new versions.

See also Data on the Web Best Practices § dataVersioning.

5.2.5. More information

If more information is available, publishers SHOULD add it.

{  "@context": "https://schema.org/",  "@type": "Dataset",  "description": {    "@value": "Alba amicorum van de Koninklijke Bibliotheek, een dataset gedefinieerd voor het Europeana Rise of Literacy project.",    "@language": "nl"  },  "mainEntityOfPage": "https://www.kb.nl/bronnen-zoekwijzers/kb-collecties/moderne-handschriften-vanaf-ca-1550/alba-amicorum"}

{  "@context": {    "dcat": "http://www.w3.org/ns/dcat#",    "dct": "http://purl.org/dc/terms/"  },  "@type": "dcat:Dataset",  "dct:description": {    "@value": "Alba amicorum van de Koninklijke Bibliotheek, een dataset gedefinieerd voor het Europeana Rise of Literacy project.",    "@language": "nl"  },  "dcat:landingPage": {    "@id": "https://www.kb.nl/bronnen-zoekwijzers/kb-collecties/moderne-handschriften-vanaf-ca-1550/alba-amicorum"  }}

See § 5.6.1 Dataset attributes for an overview of attributes.

5.3. Creator/publisher information

Users want to know where the dataset came from (provenance). The dataset’s creator and/or publisher is either a person or an organization. Providing information about the person/organization behind the dataset answers user questions such as:

• Which person/organization has published this dataset? How reliable and credible does that make the dataset?

• How can I contact the person/organization for questions or feedback?

Therefore, publishers MUST publish basic information about the person/organization. At the least, the organization’s name and HTTP IRI must be provided. The organization’s name SHOULD be a language-tagged string.

{
  "@context": "https://schema.org/",
  "@type": "Organization",
  "@id": "http://www.wikidata.org/entity/Q1526131",
  "name": {
    "@value": "Koninklijke Bibliotheek",
    "@language": "nl"
  },
  "alternateName": {
    "@value": "KB",
    "@language": "nl"
  }
}

{
  "@context": {
    "foaf": "http://xmlns.com/foaf/0.1/"
  },
  "@type": "foaf:Organization",
  "@id": "http://www.wikidata.org/entity/Q1526131",
  "foaf:name": {
    "@value": "Koninklijke Bibliotheek",
    "@language": "nl"
  },
  "foaf:nick": {
    "@value": "KB",
    "@language": "nl"
  }
}

See § 5.6.2 Organization attributes for a full overview of organization attributes.

{
  "@context": "https://schema.org/",
  "@type": "Person",
  "@id": "https://example.com",
  "name": {
    "@value": "Jan Jansen",
    "@language": "nl"
  }
}

{
  "@context": {
    "foaf": "http://xmlns.com/foaf/0.1/"
  },
  "@type": "foaf:Person",
  "@id": "https://example.com",
  "foaf:name": {
    "@value": "Jan Jansen",
    "@language": "nl"
  }
}

5.3.1. Organization IRI

Consumers use the organization’s IRI to tell which datasets come from the same organization. That only works if a publisher uses one IRI for itself across all its dataset descriptions, and if no two organizations share an IRI. A URL of a collection website, a software supplier’s server or a web page about the organization may resolve, but it identifies that website, server or page, not the organization.

Therefore, the organization’s HTTP IRI MUST identify the organization itself. Publishers SHOULD use the same IRI in all their dataset descriptions, keep it stable over time, and make sure it resolves.

Publishers SHOULD use one of:

• a persistent HTTP URI, such as an ARK or a Wikidata entity IRI (http://www.wikidata.org/entity/Q1526131);

• an IRI that the organization mints on a domain it controls, such as https://www.example.org/id/organization;

• the organization’s homepage (https://www.example.org). This is acceptable, but a homepage identifies the website as much as the organization, so prefer one of the above.

The organization’s IRI MUST NOT be:

• an address of the collection software or its supplier, such as a hosting server (https://museum.hosting.supplier.example/) or the supplier’s homepage;

• a Wikidata web page (https://www.wikidata.org/wiki/Q1526131) instead of the Wikidata entity IRI;

• a URL that identifies one collection website of the organization.

The validator warns about known software supplier addresses and Wikidata web pages. Publishers MAY link to other identifiers of the organization, such as its Wikidata entity, with schema:sameAs or owl:sameAs.

5.3.2. ISIL identifier

Publishers SHOULD include the organization’s ISIL code.

{
  "@context": "https://schema.org/",
  "@type": "Organization",
  "@id": "http://www.wikidata.org/entity/Q1526131",
  "identifier": "NL-HaKB"
}

{
  "@context": {
    "dct": "http://purl.org/dc/terms/",
    "foaf": "http://xmlns.com/foaf/0.1/"
  },
  "@type": "foaf:Organization",
  "@id": "http://www.wikidata.org/entity/Q1526131",
  "dct:identifier": "NL-HaKB"
}

5.3.3. Contact information

Publishers SHOULD include contact information so consumers can reach them with questions or feedback. If contact information is provided, it MUST include a name and e-mail address. The e-mail address SHOULD be an organizational or departmental address rather than a personal one for GDPR compliance.

In Schema.org, the contact point belongs to the publisher (schema:contactPoint). In DCAT-AP-NL 3.0, it belongs to the dataset or catalog (dcat:contactPoint), and the e-mail address is a mailto: IRI.

{  "@context": "https://schema.org/",  "@type": "Dataset",  "publisher": {    "@type": "Organization",    "@id": "http://www.wikidata.org/entity/Q1526131",    "name": "Koninklijke Bibliotheek",    "alternateName": "KB",    "contactPoint": {      "@type": "ContactPoint",      "name": {        "@value": "Datasets Department",        "@language": "en"      },      "email": "datasets@kb.nl",      "telephone": "+31 6 12345678"    }  }}

{  "@context": {    "dcat": "http://www.w3.org/ns/dcat#",    "vcard": "http://www.w3.org/2006/vcard/ns#"  },  "@type": "dcat:Dataset",  "dcat:contactPoint": {    "@type": "vcard:Kind",    "vcard:fn": {      "@value": "Datasets Department",      "@language": "en"    },    "vcard:hasEmail": {      "@id": "mailto:datasets@kb.nl"    }  }}

5.3.4. Dataset publisher

The person/organization data is then included as the dataset’s publisher:

{
  "@context": "https://schema.org/",
  "@type": "Dataset",
  "publisher": {
    "@type": "Organization",
    "@id": "http://www.wikidata.org/entity/Q1526131",
    "identifier": "NL-HaKB",
    "name": {
      "@value": "Koninklijke Bibliotheek",
      "@language": "nl"
    },
    "alternateName": {
      "@value": "KB",
      "@language": "nl"
    },
    "contactPoint": {
      "@type": "ContactPoint",
      "name": {
        "@value": "Datasets Department",
        "@language": "en"
      },
      "email": "datasets@kb.nl",
      "telephone": "+31 6 12345678"
    }
  }
}

{
  "@context": {
    "dcat": "http://www.w3.org/ns/dcat#",
    "dct": "http://purl.org/dc/terms/",
    "foaf": "http://xmlns.com/foaf/0.1/",
    "vcard": "http://www.w3.org/2006/vcard/ns#"
  },
  "@type": "dcat:Dataset",
  "dct:publisher": {
    "@type": "foaf:Organization",
    "@id": "http://www.wikidata.org/entity/Q1526131",
    "dct:identifier": "NL-HaKB",
    "foaf:name": {
      "@value": "Koninklijke Bibliotheek",
      "@language": "nl"
    },
    "foaf:nick": {
      "@value": "KB",
      "@language": "nl"
    }
  },
  "dcat:contactPoint": {
    "@type": "vcard:Kind",
    "vcard:fn": {
      "@value": "Datasets Department",
      "@language": "en"
    },
    "vcard:hasEmail": {
      "@id": "mailto:datasets@kb.nl"
    }
  }
}

{
  "@context": "https://schema.org/",
  "@type": "Dataset",
  "publisher": {
    "@type": "Person",
    "@id": "https://example.com",
    "name": {
      "@value": "Jan Jansen",
      "@language": "nl"
    }
  }
}

{
  "@context": {
    "dcat": "http://www.w3.org/ns/dcat#",
    "dct": "http://purl.org/dc/terms/",
    "foaf": "http://xmlns.com/foaf/0.1/"
  },
  "@type": "dcat:Dataset",
  "dct:publisher": {
    "@type": "foaf:Person",
    "@id": "https://example.com",
    "foaf:name": {
      "@value": "Jan Jansen",
      "@language": "nl"
    }
  }
}

5.4. Distributions

Consumers that are interested in a dataset should be able to access the data in it. Distributions tell consumers where and how they can get the data.

Therefore, publishers SHOULD add at least one distribution. Each distribution MUST have at least a MIME format and the URL where the distribution can be directly accessed.

Examples of distributions are data dumps in one or more RDF serializations, such as JSON-LD and Turtle, CSV files, SPARQL endpoints, OAI-PMH endpoints or other web APIs. All distributions of a dataset MUST contain broadly the same data.

The URL of the distribution itself – the data file, or the endpoint of the web API – goes in schema:contentUrl (Schema.org) or dcat:accessURL (DCAT-AP-NL 3.0). For a download, DCAT-AP-NL 3.0 also puts the file URL in dcat:downloadURL. If a documentation page describes or provides access to the distribution alongside it – for example a SPARQL query editor for the endpoint, or a download landing page – add it on the distribution with schema:documentation or foaf:page.

The format of the distribution goes in schema:encodingFormat or dcat:mediaType. A web API identifies its protocol instead (see § 5.4.2 Usage information): in Schema.org with schema:usageInfo; in DCAT-AP-NL 3.0 with dct:conformsTo, next to a dct:format from the EU file type list.

{
  "@context": "https://schema.org/",
  "@type": "DataDownload",
  "contentUrl": "http://vocab.getty.edu/sparql",
  "usageInfo": "https://www.w3.org/TR/sparql11-protocol/"
}

{
  "@context": {
    "dcat": "http://www.w3.org/ns/dcat#",
    "dct": "http://purl.org/dc/terms/"
  },
  "@type": "dcat:Distribution",
  "dcat:accessURL": { "@id": "http://vocab.getty.edu/sparql" },
  "dct:conformsTo": { "@id": "https://www.w3.org/TR/sparql11-protocol/" },
  "dct:format": { "@id": "http://publications.europa.eu/resource/authority/file-type/SPARQLQ" },
  "dct:license": { "@id": "http://creativecommons.org/publicdomain/zero/1.0/" }
}

The distributions are then included under the schema:distribution or dcat:distribution attribute with the dataset.

{
  "@context": "https://schema.org/",
  "@type": "Dataset",
  "distribution": [
    {
      "@type": "DataDownload",
      "contentUrl": "https://service.archief.nl/sparql",
      "documentation": "https://www.nationaalarchief.nl/onderzoeken/sparql",
      "usageInfo": "https://www.w3.org/TR/sparql11-protocol/"
    },
    {
      "@type": "DataDownload",
      "encodingFormat": "application/ld+json",
      "contentUrl": "http://data.bibliotheken.nl/id/dataset/rise-alba.json"
    },
    {
      "@type": "DataDownload",
      "encodingFormat": "text/csv+gzip",
      "contentUrl": "https://example.com/data.csv.gz"
    }
  ]
}

{
  "@context": {
    "dcat": "http://www.w3.org/ns/dcat#",
    "dct": "http://purl.org/dc/terms/",
    "foaf": "http://xmlns.com/foaf/0.1/"
  },
  "@type": "dcat:Dataset",
  "dcat:distribution": [
    {
      "@type": "dcat:Distribution",
      "dcat:accessURL": { "@id": "https://service.archief.nl/sparql" },
      "foaf:page": { "@id": "https://www.nationaalarchief.nl/onderzoeken/sparql" },
      "dct:conformsTo": { "@id": "https://www.w3.org/TR/sparql11-protocol/" },
      "dct:format": { "@id": "http://publications.europa.eu/resource/authority/file-type/SPARQLQ" },
      "dct:license": { "@id": "http://creativecommons.org/publicdomain/zero/1.0/" }
    },
    {
      "@type": "dcat:Distribution",
      "dcat:mediaType": { "@id": "https://www.iana.org/assignments/media-types/application/ld+json" },
      "dcat:accessURL": { "@id": "http://data.bibliotheken.nl/id/dataset/rise-alba.json" },
      "dcat:downloadURL": { "@id": "http://data.bibliotheken.nl/id/dataset/rise-alba.json" },
      "dct:license": { "@id": "http://creativecommons.org/publicdomain/zero/1.0/" }
    },
    {
      "@type": "dcat:Distribution",
      "dcat:mediaType": { "@id": "https://www.iana.org/assignments/media-types/text/csv" },
      "dcat:compressFormat": { "@id": "https://www.iana.org/assignments/media-types/application/gzip" },
      "dcat:accessURL": { "@id": "https://example.com/data.csv.gz" },
      "dcat:downloadURL": { "@id": "https://example.com/data.csv.gz" },
      "dct:license": { "@id": "http://creativecommons.org/publicdomain/zero/1.0/" }
    }
  ]
}

See § 5.6.4 Distribution attributes for a full overview.

5.4.1. Creation and modification dates

Publishers SHOULD make known when the distribution was first published and when it was last updated, so consumers can efficiently stay up-to-date with the latest changes. Please note that this is different from the dataset description’s dates. Datetimes (2019-08-15T08:05:00Z) are preferred because they offer greater precision, but simple dates (2019-04-14) are also allowed.

{
  "@context": "https://schema.org/",
  "@type": "DataDownload",
  "datePublished": "2019-04-14",
  "dateModified": "2019-08-15T08:05:00"
}

{
  "@context": {
    "dcat": "http://www.w3.org/ns/dcat#",
    "dct": "http://purl.org/dc/terms/",
    "xsd": "http://www.w3.org/2001/XMLSchema#"
  },
  "@type": "dcat:Distribution",
  "dct:issued": { "@value": "2019-04-14", "@type": "xsd:date" },
  "dct:modified": { "@value": "2019-08-15T08:05:00", "@type": "xsd:dateTime" }
}

5.4.2. Usage information

Each distribution SHOULD include one or more schema:usageInfo (Schema.org) or dct:conformsTo (DCAT-AP-NL 3.0) IRIs that describe what the distribution provides.

For web APIs, this MUST be the IRI of the protocol specification (such as SPARQL or OAI-PMH). The Dataset Register uses this IRI to identify the distribution as an API.

For downloads as well as APIs, this MUST be the IRI of the application profile(s) that the data conforms to.

{
  "@context": "https://schema.org/",
  "@type": "DataDownload",
  "encodingFormat": "application/ld+json",
  "contentUrl": "https://example.com/data.jsonld",
  "usageInfo": "https://docs.nde.nl/schema-profile/"
}

{
  "@context": {
    "dcat": "http://www.w3.org/ns/dcat#",
    "dct": "http://purl.org/dc/terms/"
  },
  "@type": "dcat:Distribution",
  "dcat:mediaType": { "@id": "https://www.iana.org/assignments/media-types/application/ld+json" },
  "dcat:accessURL": { "@id": "https://example.com/data.jsonld" },
  "dcat:downloadURL": { "@id": "https://example.com/data.jsonld" },
  "dct:conformsTo": { "@id": "https://docs.nde.nl/schema-profile/" }
}

{
  "@context": "https://schema.org/",
  "@type": "DataDownload",
  "contentUrl": "https://example.com/sparql",
  "usageInfo": [ "https://www.w3.org/TR/sparql11-protocol/", "https://docs.nde.nl/schema-profile/" ]
}

{
  "@context": {
    "dcat": "http://www.w3.org/ns/dcat#",
    "dct": "http://purl.org/dc/terms/"
  },
  "@type": "dcat:Distribution",
  "dcat:accessURL": { "@id": "https://example.com/sparql" },
  "dct:format": { "@id": "http://publications.europa.eu/resource/authority/file-type/SPARQLQ" },
  "dct:conformsTo": [
    { "@id": "https://www.w3.org/TR/sparql11-protocol/" },
    { "@id": "https://docs.nde.nl/schema-profile/" }
  ]
}

See also Data on the Web Best Practices Use Cases & Requirements § R-APIDocumented.

5.5. Data catalog

A data catalog provides consumers with a complete overview of available dataset descriptions, which improves discoverability.

Therefore, publishers SHOULD provide a catalog.

{
  "@context": "https://schema.org/",
  "@type": "DataCatalog",
  "@id": "http://data.bibliotheken.nl/id/datacatalog",
  "name": {
    "@value": "Linked Data van de KB",
    "@language": "nl"
  },
  "description": {
    "@value": "Alle linked data zoals beschikbaar gesteld door de Koninklijke Bibliotheek.",
    "@language": "nl"
  },
  "publisher": {
    "@type": "Organization",
    "@id": "http://www.wikidata.org/entity/Q1526131",
    "name": {
      "@value": "Koninklijke Bibliotheek",
      "@language": "nl"
    }
  },
  "dataset": [
    {
      "@type": "Dataset",
      "@id": "http://data.bibliotheken.nl/id/dataset/rise-alba",
      ...
    },
    {
      ...
    }
  ]
}

{
  "@context": {
    "dcat": "http://www.w3.org/ns/dcat#",
    "dct": "http://purl.org/dc/terms/",
    "foaf": "http://xmlns.com/foaf/0.1/",
    "vcard": "http://www.w3.org/2006/vcard/ns#"
  },
  "@type": "dcat:Catalog",
  "@id": "http://data.bibliotheken.nl/id/datacatalog",
  "dct:title": {
    "@value": "Linked Data van de KB",
    "@language": "nl"
  },
  "dct:description": {
    "@value": "Alle linked data zoals beschikbaar gesteld door de Koninklijke Bibliotheek.",
    "@language": "nl"
  },
  "dct:publisher": {
    "@type": "foaf:Organization",
    "@id": "http://www.wikidata.org/entity/Q1526131",
    "foaf:name": {
      "@value": "Koninklijke Bibliotheek",
      "@language": "nl"
    }
  },
  "dcat:contactPoint": {
    "@type": "vcard:Kind",
    "vcard:fn": {
      "@value": "Datasets Department",
      "@language": "en"
    },
    "vcard:hasEmail": { "@id": "mailto:datasets@kb.nl" }
  },
  "dcat:dataset": [
    {
      "@type": "dcat:Dataset",
      "@id": "http://data.bibliotheken.nl/id/dataset/rise-alba",
      ...
    },
    {
      ...
    }
  ]
}

See § 5.6.5 DataCatalog attributes for a full overview of catalog attributes.

5.5.1. Pagination

Large data catalogs may be harder to process for clients.

Therefore, publishers SHOULD split large data catalogs in parts of at most a 1000 datasets, using the Hydra Core Vocabulary.

Each page MUST be a complete RDF document in itself. Related resources, such as the publishing organization, must be described on each page, even if that resource is the same on all pages.

{  "@context": [    "https://schema.org/",    {"hydra": "http://www.w3.org/ns/hydra/core#"}  ],  "@type": ["DataCatalog", "hydra:Collection"],  "@id": "https://example.com/catalog",  "name": {    "@value": "Paginated catalog of datasets",    "@language": "en"  },  "description": {    "@value": "This catalog is paginated using the Hydra Core Vocabulary.",    "@language": "en"  },  "publisher": {    "@type": "Organization",    "@id": "/publisher",    "name": {      "@value": "Example Publisher",      "@language": "en"    }  },  "hydra:view": {    "@id": "/catalog?page=1",    "@type": "hydra:PartialCollectionView",    "hydra:first": {"@id": "/catalog?page=1"},    "hydra:next": {"@id": "/catalog?page=2"},    "hydra:last": {"@id": "/catalog?page=498"}  },  "dataset": [    {      "@type": "Dataset",      "@id": "https://example.com/dataset/1",      ...    },    {      "@type": "Dataset",      "@id": "https://example.com/dataset/2",      ...    },    ...  ]}

{  "@context": {    "dcat": "http://www.w3.org/ns/dcat#",    "dct": "http://purl.org/dc/terms/",    "foaf": "http://xmlns.com/foaf/0.1/",    "hydra": "http://www.w3.org/ns/hydra/core#"  },  "@type": ["dcat:Catalog", "hydra:Collection"],  "@id": "https://example.com/catalog",  "dct:title": {    "@value": "Paginated catalog of datasets",    "@language": "en"  },  "dct:description": {    "@value": "This catalog is paginated using the Hydra Core Vocabulary.",    "@language": "en"  },  "dct:publisher": {    "@type": "foaf:Organization",    "@id": "https://example.com/publisher",    "foaf:name": {      "@value": "Example Publisher",      "@language": "en"    }  },  "hydra:view": {    "@id": "/catalog?page=1",    "@type": "hydra:PartialCollectionView",    "hydra:first": {"@id": "/catalog?page=1"},    "hydra:next": {"@id": "/catalog?page=2"},    "hydra:last": {"@id": "/catalog?page=498"}  },  "dcat:dataset": [    {      "@type": "dcat:Dataset",      "@id": "https://example.com/dataset/1",      ...    },    {      "@type": "dcat:Dataset",      "@id": "https://example.com/dataset/2",      ...    },    ...  ]}

5.6. Overview of attributes

This is an overview of required and recommended attributes.

5.6.1. Dataset attributes

5.6.2. Organization attributes

5.6.3. Contact point attributes

5.6.4. Distribution attributes

5.6.5. DataCatalog attributes

5.6.6. Full example

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Dataset",
      "@id": "http://data.bibliotheken.nl/id/dataset/rise-alba",
      "name": [
        {
          "@value": "Alba amicorum van de Koninklijke Bibliotheek",
          "@language": "nl"
        },
        {
          "@value": "Alba amicorum of the Dutch Royal Library",
          "@language": "en"
        }
      ],
      "description": {
        "@value": "Description only in English",
        "@language": "en"
      },
      "about": { "@id": "http://vocab.getty.edu/aat/300026680" },
      "url": "https://www.kb.nl/bronnen-zoekwijzers/kb-collecties/moderne-handschriften-vanaf-ca-1550/alba-amicorum",
      "identifier": "http://data.bibliotheken.nl/id/dataset/rise-alba",
      "license": "http://creativecommons.org/publicdomain/zero/1.0/",
      "inLanguage": [
        "nl-NL",
        "en-GB"
      ],
      "spatialCoverage": {
        "@id": "https://sws.geonames.org/2750405/"
      },
      "temporalCoverage": "1939/1945",
      "publisher": {
        "@id": "https://example.com"
      },
      "creator": [
        {
          "@type": "Person",
          "@id": "https://example.com/creator1",
          "name": {
            "@value": "Creator 1",
            "@language": "en"
          }
        },
        {
          "@type": "Person",
          "@id": "https://example.com/creator2",
          "name": {
            "@value": "Creator 2",
            "@language": "en"
          }
        },
        {
          "@id": "https://example.com"
        }
      ],
      "dateModified": "2021-05-27T09:56:21.370767",
      "datePublished": "2021-05-28",
      "dateCreated": {
        "@type": "http://www.w3.org/2001/XMLSchema#date",
        "@value": "2021-05-27"
      },
      "distribution": [
        {
          "@type": "DataDownload",
          "encodingFormat": "application/rdf+xml",
          "contentUrl": "https://data.bibliotheken.nl/id/dataset/rise-alba.rdf",
          "contentSize": 12582912,
          "description": "RDF/XML dump"
        },
        {
          "@type": "DataDownload",
          "encodingFormat": "application/ld+json",
          "contentUrl": "https://data.bibliotheken.nl/id/dataset/rise-alba.jsonld",
          "usageInfo": "https://docs.nde.nl/schema-profile/",
          "description": "JSON-LD dump"
        },
        {
          "@type": "DataDownload",
          "contentUrl": "https://data.bibliotheken.nl/id/dataset/sparql",
          "documentation": "https://data.bibliotheken.nl/KB/Production/sparql",
          "usageInfo": "https://www.w3.org/TR/sparql11-protocol/",
          "description": "SPARQL endpoint"
        }
      ]
    },
    {
      "@type": "Organization",
      "@id": "https://example.com",
      "identifier": "NL-HaKB",
      "name": {
        "@value": "Koninklijke Bibliotheek",
        "@language": "nl"
      },
      "sameAs": "https://ror.org/02w4jbg70",
      "contactPoint": {
        "@type": "ContactPoint",
        "name": { "@value": "Datasets Manager", "@language": "en" },
        "email": "datasets@example.com"
      }
    }
  ]
}

{
  "@context": {
    "dcat": "http://www.w3.org/ns/dcat#",
    "dct": "http://purl.org/dc/terms/",
    "foaf": "http://xmlns.com/foaf/0.1/",
    "owl": "http://www.w3.org/2002/07/owl#",
    "vcard": "http://www.w3.org/2006/vcard/ns#",
    "xsd": "http://www.w3.org/2001/XMLSchema#"
  },
  "@graph": [
    {
      "@type": "dcat:Dataset",
      "@id": "http://data.bibliotheken.nl/id/dataset/rise-alba",
      "dct:title": [
        {
          "@value": "Alba amicorum van de Koninklijke Bibliotheek",
          "@language": "nl"
        },
        {
          "@value": "Alba amicorum of the Dutch Royal Library",
          "@language": "en"
        }
      ],
      "dct:description": {
        "@value": "Description only in English",
        "@language": "en"
      },
      "dcat:theme": { "@id": "http://vocab.getty.edu/aat/300026680" },
      "dcat:landingPage": {
        "@id": "https://www.kb.nl/bronnen-zoekwijzers/kb-collecties/moderne-handschriften-vanaf-ca-1550/alba-amicorum"
      },
      "dct:language": [
        { "@id": "http://publications.europa.eu/resource/authority/language/NLD" },
        { "@id": "http://publications.europa.eu/resource/authority/language/ENG" }
      ],
      "dct:spatial": { "@id": "https://sws.geonames.org/2750405/" },
      "dct:temporal": "1939/1945",
      "dct:publisher": { "@id": "https://example.com" },
      "dct:creator": [
        {
          "@type": "foaf:Person",
          "@id": "https://example.com/creator1",
          "foaf:name": { "@value": "Creator 1", "@language": "en" }
        },
        {
          "@type": "foaf:Person",
          "@id": "https://example.com/creator2",
          "foaf:name": { "@value": "Creator 2", "@language": "en" }
        },
        { "@id": "https://example.com" }
      ],
      "dcat:contactPoint": {
        "@type": "vcard:Kind",
        "vcard:fn": { "@value": "Datasets Manager", "@language": "en" },
        "vcard:hasEmail": { "@id": "mailto:datasets@example.com" }
      },
      "dct:created": { "@value": "2021-05-27", "@type": "xsd:date" },
      "dct:issued": { "@value": "2021-05-28", "@type": "xsd:date" },
      "dct:modified": {
        "@value": "2021-05-27T09:56:21.370767",
        "@type": "xsd:dateTime"
      },
      "dcat:distribution": [
        {
          "@type": "dcat:Distribution",
          "dcat:mediaType": {
            "@id": "https://www.iana.org/assignments/media-types/application/rdf+xml"
          },
          "dcat:accessURL": {
            "@id": "https://data.bibliotheken.nl/id/dataset/rise-alba.rdf"
          },
          "dcat:downloadURL": {
            "@id": "https://data.bibliotheken.nl/id/dataset/rise-alba.rdf"
          },
          "dcat:byteSize": { "@value": "12582912", "@type": "xsd:nonNegativeInteger" },
          "dct:description": "RDF/XML dump",
          "dct:license": {
            "@id": "http://creativecommons.org/publicdomain/zero/1.0/"
          }
        },
        {
          "@type": "dcat:Distribution",
          "dcat:mediaType": {
            "@id": "https://www.iana.org/assignments/media-types/application/ld+json"
          },
          "dcat:accessURL": {
            "@id": "https://data.bibliotheken.nl/id/dataset/rise-alba.jsonld"
          },
          "dcat:downloadURL": {
            "@id": "https://data.bibliotheken.nl/id/dataset/rise-alba.jsonld"
          },
          "dct:conformsTo": { "@id": "https://docs.nde.nl/schema-profile/" },
          "dct:description": "JSON-LD dump",
          "dct:license": {
            "@id": "http://creativecommons.org/publicdomain/zero/1.0/"
          }
        },
        {
          "@type": "dcat:Distribution",
          "dcat:accessURL": {
            "@id": "https://data.bibliotheken.nl/id/dataset/sparql"
          },
          "foaf:page": {
            "@id": "https://data.bibliotheken.nl/KB/Production/sparql"
          },
          "dct:conformsTo": {
            "@id": "https://www.w3.org/TR/sparql11-protocol/"
          },
          "dct:format": {
            "@id": "http://publications.europa.eu/resource/authority/file-type/SPARQLQ"
          },
          "dct:description": "SPARQL endpoint",
          "dct:license": {
            "@id": "http://creativecommons.org/publicdomain/zero/1.0/"
          }
        }
      ]
    },
    {
      "@type": "foaf:Organization",
      "@id": "https://example.com",
      "dct:identifier": "NL-HaKB",
      "foaf:name": {
        "@value": "Koninklijke Bibliotheek",
        "@language": "nl"
      },
      "owl:sameAs": { "@id": "https://ror.org/02w4jbg70" }
    }
  ]
}

6. Tools

This section is non-normative.

Developers can use the NDE Register API to validate datasets and catalogs against the requirements described in this document. The [SHACL] shape graph used to validate datasets and catalogs is available at /shacl.

6.1. Running the shapes yourself

The Schema.org shapes target properties in the https://schema.org/ namespace. Schema.org’s own JSON-LD context maps its terms to http://schema.org/, so a Schema.org dataset description validated against that context matches no shape at all and the report comes back sh:conforms true without anything having been checked. Since Schema.org release 30.1 that context also no longer types mainEntityOfPage, license and the date properties, which turns values that should be IRIs and dates into plain strings.

To validate your own file – and only to validate it, not to publish it – point its @context at https://def.nde.nl/context.jsonld. That context declares the same prefixes as Schema.org’s and restores the typings the shapes rely on, so you get the report the Register API gives you.

{
  "@context": "https://def.nde.nl/context.jsonld",
  "@id": "https://example.org/dataset",
  "@type": "Dataset",
  "name": {"@value": "My dataset", "@language": "nl"},
  "mainEntityOfPage": "https://example.org/about-this-dataset"
}

Keep serving your dataset description itself with "@context": "https://schema.org/": the Register substitutes the context on its side when it reads your description, so there is nothing to change in what you publish.

DCAT-AP-NL 3.0 descriptions need no such step. Their JSON-LD declares the namespaces itself, as in the examples in this document, so you can validate them as they are.

Google’s Rich Results Test (previously Structured Data Testing Tool) can help with testing RDF metadata in general.

7. Changes

This section lists notable changes to this specification.

7.1. Version 1.15.1 (2026-10-13)

• Announce version 2.0 and its effective date (13f75be).

7.2. Version 1.15.0 (2026-10-13)

• Document dct:source on the DCAT dataset shape (ffaee41).

• Read registrations with our own Schema.org JSON-LD context (f154e31).

• Describe the data catalog description in its own words (46739d3).

• Recommend usageInfo IRIs for LDES, IIIF and Linked Art Search APIs (5144c8b).

7.3. Version 1.14.0 (2026-07-16)

• Drop keywords from the dataset requirements (e787d17).

7.4. Version 1.13.0 (2026-07-10)

• Warn on bare compression and non-IANA x- media types in encodingFormat (c01ed4a).

• Accept foaf:Agent as a valid dct:publisher/dct:creator class (cdc139f).

• Clarify spatial coverage should use most specific level (6964f6d).

7.5. Version 1.12.0 (2026-06-24)

• Accept dct:temporal as a dct:PeriodOfTime in temporal warning (5ff7a37).

• Accept archaeological-scale years in temporalCoverage (8c818dc).

• Enforce HTTP(S) IRI for dcat:Dataset and reject blank-node datasets (5b4cdd6).

• Write contentUrl description as plain HTML, link web API spec-side (5670817).

7.6. Version 1.11.3 (2026-05-21)

• Render cardinality for properties without sh:minCount/maxCount (c521c74).

7.7. Version 1.11.2 (2026-05-20)

• Fix v2 Required vs Recommended in attributes table (58e3a69).

• Require schema:license on the Dataset as before (c0c1e68).

• Update Register API URLs (58e3b33).

7.8. Version 1.11.1 (2026-05-15)

• Fix v2.0 labels for sh:or and sh:not shapes (2ef2ac7).

• Fix typo (c6bfa41).

7.9. Version 1.11.0 (2026-04-23)

• State temporal coverage format in description and validate dc:temporal (f71bde4).

7.10. Version 1.10.0 (2026-04-23)

• Add schema:documentation to distribution for documentation page URL (8e30b05).

• Plain-HTML sh:description, spec-side Bikeshed expansion, drop sh:name (28198fe).

• Use HTML anchors for links in sh:description (49642a7).

• Render maxCount 0 and ‘becomes forbidden’ in attribute tables (47af7ce).

7.11. Version 1.9.0 (2026-04-22)

• Downgrade missing organisation identifier to sh:Info (6624d71).

• Recommend schema:about instead of schema:keywords for URIs (fcf9055).

• Consolidate publisher/creator shapes (b533f0a).

7.12. Version 1.8.0 (2026-04-20)

• Require SPARQL protocol URI in usageInfo for SPARQL mediaType (0dfc6c6).

• Align Distribution with DCAT-AP-NL 3.0 (title + description) (e901005).

• Split publisher min/max-count constraints into separate shapes (2e060e4).

7.13. Version 1.7.0 (2026-04-20)

• Map schema:temporalCoverage to dct:PeriodOfTime (a700556).

• Accept ISO 8601 shortened-end intervals in temporalCoverage (61ffdf7).

7.14. Version 1.6.0 (2026-04-16)

• Deprecate schema:genre; make schema:about canonical for dcat:theme (bdbd789).

• Target sh:nodeKind sh:IRI for contentUrl in v2, not xsd:anyURI (1e86b9f).

7.15. Version 1.5.3 (2026-04-15)

• Add Linked Art profile to distribution IRI table (3c01ad5).

7.16. Version 1.5.2 (2026-04-13)

• Align publisher cardinality with DCAT-AP-NL 3.0 (6af64c7).

• Mark ISO-8601 date pattern as v2.0 violation (62d22e1).

• Mark schema:contactPoint as v2.0 violation (7aeab03).

• Validate ISO-8601 dates on DCAT date properties (ee09aec).

7.17. Version 1.5.1 (2026-04-10)

• Correct v2.0 annotation for IRI-constrained properties in spec (63e694a).

• Use single sh:message on SPARQL constraint for Jena compatibility (5e67a50).

• Add resolvable dataset URI requirement and update mainEntityOfPage (59f995d).

7.18. Version 1.5.0 (2026-04-02)

• Recommended a set of canonical license URIs (ec38c3a).

7.19. Version 1.4.0 (2026-04-01)

• Add Content-Type requirement for registration URLs (524dc42).

• Add dct:accrualPeriodicity support for datasets (8eebd71).

• Add maxCount 1 as future change for encodingFormat and mediaType (9364133).

• Preserve user-provided dcat:theme from DCAT input (343b176).

• Remove dct:title from Distribution (d957e44).

• Validate includedInDataCatalog as HTTP IRI (08484c6).

• Validate language tags on title, description, and name properties (d99f2fb).

• Validate spatialCoverage and dct:spatial as HTTP IRI (bbc02b5).

• Skip SHACL validation of inline DataCatalog references (37c9437).

• Rewrite ‘Developer documentation’ section as ‘Usage information’ (ad5c22c).

7.20. Version 1.3.0 (2026-04-01)

• Differentiate API and download distributions per DCAT-AP-NL (ba22143).

• Normalize BCP 47 language codes to EU Language Authority URIs (cbf1932).

• Add Person to conceptual model diagram (cd0b429).

7.21. Version 1.2.0 (2026-03-25)

• Add DCAT-AP-NL 3.0 requirements (510a43c).

7.22. Version 1.1.0 (2026-03-25)

• Express future requirement changes in SHACL and spec (3c3fbb7).