components:
  responses:
    Invalid:
      content:
        application/ld+json:
          example:
          - '@id': _:b7
            '@type':
            - http://www.w3.org/ns/shacl#ValidationResult
            http://www.w3.org/ns/shacl#resultSeverity:
            - '@id': http://www.w3.org/ns/shacl#Violation
            http://www.w3.org/ns/shacl#sourceConstraintComponent:
            - '@id': http://www.w3.org/ns/shacl#MinCountConstraintComponent
            http://www.w3.org/ns/shacl#sourceShape:
            - '@id': _:df_28_15
          - '@id': _:df_28_15
            http://www.w3.org/ns/shacl#class:
            - '@id': http://schema.org/Organization
            http://www.w3.org/ns/shacl#minCount:
            - '@type': http://www.w3.org/2001/XMLSchema#integer
              '@value': "1"
            http://www.w3.org/ns/shacl#node:
            - '@value': schema:PublisherShape
            http://www.w3.org/ns/shacl#path:
            - '@id': http://schema.org/publisher
          - '@id': _:b7
            http://www.w3.org/ns/shacl#focusNode:
            - '@id': http://data.bibliotheken.nl/id/dataset/rise-alba
            http://www.w3.org/ns/shacl#resultMessage:
            - '@value': Less than 1 values
            http://www.w3.org/ns/shacl#resultPath:
            - '@id': http://schema.org/publisher
          - '@id': _:report
            '@type':
            - http://www.w3.org/ns/shacl#ValidationReport
            http://www.w3.org/ns/shacl#conforms:
            - '@type': http://www.w3.org/2001/XMLSchema#boolean
              '@value': "false"
            http://www.w3.org/ns/shacl#result:
            - '@id': _:b10
        text/turtle:
          example: |-
            _:b11 a <http://www.w3.org/ns/shacl#ValidationResult>;
              <http://www.w3.org/ns/shacl#resultSeverity> <http://www.w3.org/ns/shacl#Violation>;
              <http://www.w3.org/ns/shacl#sourceConstraintComponent> <http://www.w3.org/ns/shacl#MinCountConstraintComponent>;
              <http://www.w3.org/ns/shacl#sourceShape> _:df_28_15.
            _:df_28_15 <http://www.w3.org/ns/shacl#path> <http://schema.org/publisher>;
              <http://www.w3.org/ns/shacl#minCount> 1;
              <http://www.w3.org/ns/shacl#class> <http://schema.org/Organization>;
              <http://www.w3.org/ns/shacl#node> "schema:PublisherShape".
            _:b11 <http://www.w3.org/ns/shacl#focusNode> <http://data.bibliotheken.nl/id/dataset/rise-alba>;
              <http://www.w3.org/ns/shacl#resultPath> <http://schema.org/publisher>;
              <http://www.w3.org/ns/shacl#resultMessage> "Less than 1 values".
            _:report a <http://www.w3.org/ns/shacl#ValidationReport>;
              <http://www.w3.org/ns/shacl#conforms> false;
              <http://www.w3.org/ns/shacl#result> _:b11.
      description: One or more dataset descriptions are invalid according to the <a
        href="https://netwerk-digitaal-erfgoed.github.io/requirements-datasets/">Requirements
        for Datasets</a>. The response body contains a list of [SHACL](https://www.w3.org/TR/shacl/)
        violations.
    Valid:
      content:
        application/ld+json:
          example:
          - '@id': _:report
            '@type':
            - http://www.w3.org/ns/shacl#ValidationReport
            http://www.w3.org/ns/shacl#conforms:
            - '@type': http://www.w3.org/2001/XMLSchema#boolean
              '@value': "true"
        text/turtle:
          example: |-
            _:report a <http://www.w3.org/ns/shacl#ValidationReport>;
              <http://www.w3.org/ns/shacl#conforms> true.
      description: "All dataset descriptions are valid according to the <a href=\"https://netwerk-digitaal-erfgoed.github.io/requirements-datasets/\">Requirements
        for Datasets</a>.\nNote that `sh:conforms` is different from the dataset description’s
        validity: `sh:conforms` is `true` only if no violations, warnings or infos
        are returned.\nA dataset description is considered valid if it has no violations,
        even if warnings are present. \nHowever, warnings cause `sh:conforms` to be
        `false`."
  securitySchemes:
    bearerAuth:
      description: API access token for administrative operations
      scheme: bearer
      type: http
info:
  contact:
    email: bob.coret@netwerkdigitaalerfgoed.nl
    name: Dutch Digital Heritage Network
    url: https://datasetregister.netwerkdigitaalerfgoed.nl/faq.php
  description: Dutch Digital Heritage Network Dataset Register REST API
  title: Dataset Register
  version: latest
openapi: 3.0.3
paths:
  /allowed-domains:
    get:
      description: |-
        Check whether the domain of the given URL is on the allow list.
        Only URLs on allowed domains can be registered via POST /datasets.
      parameters:
      - description: URL whose domain to check
        example: https://example.com/dataset.ttl
        in: query
        name: url
        required: true
        schema:
          type: string
      responses:
        "200":
          description: The URL’s domain is on the allow list.
        "400":
          description: Missing or invalid URL parameter.
        "404":
          description: The URL’s domain is not on the allow list.
      summary: Check whether a URL’s domain is on the allow list
      tags:
      - Onboarding
    post:
      description: |-
        Add a domain to the allow list, so that URLs on that domain (or any of its subdomains)
        can be registered via POST /datasets. This operation requires authentication
        via a Bearer token.

        Pass either a registrable domain (e.g. `example.com`) or a specific subdomain
        (e.g. `sub.example.com`) to allow only that subdomain. Submitting a subdomain
        whose registrable parent is already on the list is a no-op, since the parent
        already covers it.
      requestBody:
        content:
          application/json:
            examples:
              valid:
                summary: Add a domain
                value:
                  domain: example.com
            schema:
              properties:
                domain:
                  description: Registrable domain or full hostname to add to the allow
                    list.
                  type: string
              required:
              - domain
              type: object
        required: true
      responses:
        "204":
          description: The domain has been added to the allow list.
        "400":
          description: Missing or invalid domain.
        "401":
          description: Missing or invalid Authorization header.
      security:
      - bearerAuth: []
      summary: Add a domain to the allow list
      tags:
      - Administration
  /datasets:
    delete:
      description: |-
        Delete a registration from the Dataset Register, including all dataset descriptions
        that were fetched from the registered URL. This operation requires authentication
        via a Bearer token.
      parameters:
      - description: Registration URL to delete
        example: https://example.com/catalog
        in: query
        name: url
        required: true
        schema:
          type: string
      responses:
        "204":
          description: Registration and all linked datasets have been deleted successfully.
        "400":
          description: Missing or invalid URL parameter.
        "401":
          description: Missing or invalid Authorization header.
        "404":
          description: No registration found for the given URL.
      security:
      - bearerAuth: []
      summary: Delete a dataset registration
      tags:
      - Administration
    post:
      description: |-
        Submit dataset description(s) to the Dataset Register. Each dataset description will be validated before it is added to the Dataset Register.

        Only URLs that are on the allow list can be registered. Please [contact us](mailto:bob.coret@netwerkdigitaalerfgoed.nl) to have your domain added.
      requestBody:
        content:
          application/ld+json:
            examples:
              invalid:
                summary: An invalid dataset
                value:
                  '@id': https://example.com/invalid-dataset
              valid:
                summary: A valid dataset
                value:
                  '@id': https://example.com/dataset
            schema:
              properties:
                '@id':
                  description: URL where the dataset description(s) can be found.
                  type: string
              required:
              - '@id'
              type: object
      responses:
        "202":
          content:
            application/ld+json: {}
          description: All dataset descriptions at the submitted URL are valid according
            to the <a href="https://netwerk-digitaal-erfgoed.github.io/requirements-datasets/">Requirements
            for Datasets</a>. The datasets will added to the Dataset Register shortly.
        "400":
          description: One or more dataset descriptions are invalid according to the
            <a href="https://netwerk-digitaal-erfgoed.github.io/requirements-datasets/">Requirements
            for Datasets</a>. The response body contains a list of [SHACL](https://www.w3.org/TR/shacl/)
            violations.
        "403":
          description: The submitted URL is not on the domain name allow list. [Contact
            us](mailto:bob.coret@netwerkdigitaalerfgoed.nl) to have your institution’s
            domain name added.
        "404":
          description: The URL cannot be resolved.
        "406":
          description: The URL can be resolved but it contains no datasets.
      summary: Add dataset description to the Dataset Register
      tags:
      - Registration
  /datasets/validate:
    post:
      description: Validate dataset description(s) according to the <a href="https://netwerk-digitaal-erfgoed.github.io/requirements-datasets/">Requirements
        for Datasets</a>.
      operationId: validate-body
      requestBody:
        content:
          application/ld+json:
            examples:
              valid:
                summary: A valid dataset in the request body
                value:
                  '@context': https://schema.org/
                  '@id': http://data.bibliotheken.nl/id/dataset/rise-alba
                  '@type': Dataset
                  license: http://creativecommons.org/publicdomain/zero/1.0/
                  name: Alba amicorum van de Koninklijke Bibliotheek
                  publisher:
                    '@id': https://example.com/publisher
                    '@type': Organization
                    name: Koninklijke Bibliotheek
            schema:
              type: object
          text/turtle:
            examples:
              valid:
                summary: A valid dataset in the request body
                value: |-
                  @prefix schema: <https://schema.org/> .
                  <http://data.bibliotheken.nl/id/dataset/rise-alba>
                    a schema:Dataset ;
                    schema:name "Alba amicorum van de Koninklijke Bibliotheek" ;
                    schema:license <http://creativecommons.org/publicdomain/zero/1.0/> ;
                    schema:publisher <https://example.com/publisher> .

                  <https://example.com/publisher>
                    a schema:Organization ;
                    schema:name "Koninklijke Bibliotheek" .
            schema:
              type: string
      responses:
        "200":
          content:
            application/ld+json:
              example:
              - '@id': _:report
                '@type':
                - http://www.w3.org/ns/shacl#ValidationReport
                http://www.w3.org/ns/shacl#conforms:
                - '@type': http://www.w3.org/2001/XMLSchema#boolean
                  '@value': "true"
            text/turtle:
              example: |-
                _:report a <http://www.w3.org/ns/shacl#ValidationReport>;
                  <http://www.w3.org/ns/shacl#conforms> true.
          description: "All dataset descriptions are valid according to the <a href=\"https://netwerk-digitaal-erfgoed.github.io/requirements-datasets/\">Requirements
            for Datasets</a>.\nNote that `sh:conforms` is different from the dataset
            description’s validity: `sh:conforms` is `true` only if no violations,
            warnings or infos are returned.\nA dataset description is considered valid
            if it has no violations, even if warnings are present. \nHowever, warnings
            cause `sh:conforms` to be `false`."
        "400":
          content:
            application/ld+json:
              example:
              - '@id': _:b7
                '@type':
                - http://www.w3.org/ns/shacl#ValidationResult
                http://www.w3.org/ns/shacl#resultSeverity:
                - '@id': http://www.w3.org/ns/shacl#Violation
                http://www.w3.org/ns/shacl#sourceConstraintComponent:
                - '@id': http://www.w3.org/ns/shacl#MinCountConstraintComponent
                http://www.w3.org/ns/shacl#sourceShape:
                - '@id': _:df_28_15
              - '@id': _:df_28_15
                http://www.w3.org/ns/shacl#class:
                - '@id': http://schema.org/Organization
                http://www.w3.org/ns/shacl#minCount:
                - '@type': http://www.w3.org/2001/XMLSchema#integer
                  '@value': "1"
                http://www.w3.org/ns/shacl#node:
                - '@value': schema:PublisherShape
                http://www.w3.org/ns/shacl#path:
                - '@id': http://schema.org/publisher
              - '@id': _:b7
                http://www.w3.org/ns/shacl#focusNode:
                - '@id': http://data.bibliotheken.nl/id/dataset/rise-alba
                http://www.w3.org/ns/shacl#resultMessage:
                - '@value': Less than 1 values
                http://www.w3.org/ns/shacl#resultPath:
                - '@id': http://schema.org/publisher
              - '@id': _:report
                '@type':
                - http://www.w3.org/ns/shacl#ValidationReport
                http://www.w3.org/ns/shacl#conforms:
                - '@type': http://www.w3.org/2001/XMLSchema#boolean
                  '@value': "false"
                http://www.w3.org/ns/shacl#result:
                - '@id': _:b10
            text/turtle:
              example: |-
                _:b11 a <http://www.w3.org/ns/shacl#ValidationResult>;
                  <http://www.w3.org/ns/shacl#resultSeverity> <http://www.w3.org/ns/shacl#Violation>;
                  <http://www.w3.org/ns/shacl#sourceConstraintComponent> <http://www.w3.org/ns/shacl#MinCountConstraintComponent>;
                  <http://www.w3.org/ns/shacl#sourceShape> _:df_28_15.
                _:df_28_15 <http://www.w3.org/ns/shacl#path> <http://schema.org/publisher>;
                  <http://www.w3.org/ns/shacl#minCount> 1;
                  <http://www.w3.org/ns/shacl#class> <http://schema.org/Organization>;
                  <http://www.w3.org/ns/shacl#node> "schema:PublisherShape".
                _:b11 <http://www.w3.org/ns/shacl#focusNode> <http://data.bibliotheken.nl/id/dataset/rise-alba>;
                  <http://www.w3.org/ns/shacl#resultPath> <http://schema.org/publisher>;
                  <http://www.w3.org/ns/shacl#resultMessage> "Less than 1 values".
                _:report a <http://www.w3.org/ns/shacl#ValidationReport>;
                  <http://www.w3.org/ns/shacl#conforms> false;
                  <http://www.w3.org/ns/shacl#result> _:b11.
          description: One or more dataset descriptions are invalid according to the
            <a href="https://netwerk-digitaal-erfgoed.github.io/requirements-datasets/">Requirements
            for Datasets</a>. The response body contains a list of [SHACL](https://www.w3.org/TR/shacl/)
            violations.
      summary: Validate dataset description(s) in the request body
      tags:
      - Validation
    put:
      description: |-
        Validate dataset description(s) according to the <a href="https://netwerk-digitaal-erfgoed.github.io/requirements-datasets/">Requirements for Datasets</a> that are available at the submitted URL. That URL may resolve:

        - a single dataset which will be validated;
        - multiple datasets, each of which will be validated;
        - multiple datasets in a data catalog, which will be validated in full.
      operationId: validate
      requestBody:
        content:
          application/ld+json:
            examples:
              invalid:
                summary: An invalid dataset
                value:
                  '@id': https://example.com/invalid-dataset
              valid:
                summary: A valid dataset
                value:
                  '@id': https://example.com/dataset
            schema:
              properties:
                '@id':
                  description: URL where the dataset description(s) can be found.
                  type: string
              required:
              - '@id'
              type: object
      responses:
        "200":
          content:
            application/ld+json:
              example:
              - '@id': _:report
                '@type':
                - http://www.w3.org/ns/shacl#ValidationReport
                http://www.w3.org/ns/shacl#conforms:
                - '@type': http://www.w3.org/2001/XMLSchema#boolean
                  '@value': "true"
            text/turtle:
              example: |-
                _:report a <http://www.w3.org/ns/shacl#ValidationReport>;
                  <http://www.w3.org/ns/shacl#conforms> true.
          description: "All dataset descriptions are valid according to the <a href=\"https://netwerk-digitaal-erfgoed.github.io/requirements-datasets/\">Requirements
            for Datasets</a>.\nNote that `sh:conforms` is different from the dataset
            description’s validity: `sh:conforms` is `true` only if no violations,
            warnings or infos are returned.\nA dataset description is considered valid
            if it has no violations, even if warnings are present. \nHowever, warnings
            cause `sh:conforms` to be `false`."
        "400":
          content:
            application/ld+json:
              example:
              - '@id': _:b7
                '@type':
                - http://www.w3.org/ns/shacl#ValidationResult
                http://www.w3.org/ns/shacl#resultSeverity:
                - '@id': http://www.w3.org/ns/shacl#Violation
                http://www.w3.org/ns/shacl#sourceConstraintComponent:
                - '@id': http://www.w3.org/ns/shacl#MinCountConstraintComponent
                http://www.w3.org/ns/shacl#sourceShape:
                - '@id': _:df_28_15
              - '@id': _:df_28_15
                http://www.w3.org/ns/shacl#class:
                - '@id': http://schema.org/Organization
                http://www.w3.org/ns/shacl#minCount:
                - '@type': http://www.w3.org/2001/XMLSchema#integer
                  '@value': "1"
                http://www.w3.org/ns/shacl#node:
                - '@value': schema:PublisherShape
                http://www.w3.org/ns/shacl#path:
                - '@id': http://schema.org/publisher
              - '@id': _:b7
                http://www.w3.org/ns/shacl#focusNode:
                - '@id': http://data.bibliotheken.nl/id/dataset/rise-alba
                http://www.w3.org/ns/shacl#resultMessage:
                - '@value': Less than 1 values
                http://www.w3.org/ns/shacl#resultPath:
                - '@id': http://schema.org/publisher
              - '@id': _:report
                '@type':
                - http://www.w3.org/ns/shacl#ValidationReport
                http://www.w3.org/ns/shacl#conforms:
                - '@type': http://www.w3.org/2001/XMLSchema#boolean
                  '@value': "false"
                http://www.w3.org/ns/shacl#result:
                - '@id': _:b10
            text/turtle:
              example: |-
                _:b11 a <http://www.w3.org/ns/shacl#ValidationResult>;
                  <http://www.w3.org/ns/shacl#resultSeverity> <http://www.w3.org/ns/shacl#Violation>;
                  <http://www.w3.org/ns/shacl#sourceConstraintComponent> <http://www.w3.org/ns/shacl#MinCountConstraintComponent>;
                  <http://www.w3.org/ns/shacl#sourceShape> _:df_28_15.
                _:df_28_15 <http://www.w3.org/ns/shacl#path> <http://schema.org/publisher>;
                  <http://www.w3.org/ns/shacl#minCount> 1;
                  <http://www.w3.org/ns/shacl#class> <http://schema.org/Organization>;
                  <http://www.w3.org/ns/shacl#node> "schema:PublisherShape".
                _:b11 <http://www.w3.org/ns/shacl#focusNode> <http://data.bibliotheken.nl/id/dataset/rise-alba>;
                  <http://www.w3.org/ns/shacl#resultPath> <http://schema.org/publisher>;
                  <http://www.w3.org/ns/shacl#resultMessage> "Less than 1 values".
                _:report a <http://www.w3.org/ns/shacl#ValidationReport>;
                  <http://www.w3.org/ns/shacl#conforms> false;
                  <http://www.w3.org/ns/shacl#result> _:b11.
          description: One or more dataset descriptions are invalid according to the
            <a href="https://netwerk-digitaal-erfgoed.github.io/requirements-datasets/">Requirements
            for Datasets</a>. The response body contains a list of [SHACL](https://www.w3.org/TR/shacl/)
            violations.
        "404":
          description: The URL cannot be resolved.
        "406":
          description: The URL can be resolved but it contains no datasets.
      summary: Validate dataset description(s)s at a URL
      tags:
      - Validation
  /shacl:
    get:
      description: Get the <a href="https://www.w3.org/TR/shacl/">SHACL shape graph</a>
        that is used to validate dataset descriptions.
      responses:
        "200":
          content:
            application/ld+json:
              example: |-
                [
                  {
                    "@id": "http://terms.netwerkdigitaalerfgoed.nl/ns/register#DatasetShape",
                    "@type": [
                      "http://www.w3.org/ns/shacl#NodeShape"
                    ],
                    "http://www.w3.org/ns/shacl#name": [
                      {
                        "@value": "Datasetbeschrijving",
                        "@language": "nl"
                      },
                      {
                        "@value": "Dataset description",
                        "@language": "en"
                      }
                    ]
                  }
                ]
            text/turtle:
              example: |-
                <http://terms.netwerkdigitaalerfgoed.nl/ns/register#DatasetShape> a <http://www.w3.org/ns/shacl#NodeShape>.
                    <http://www.w3.org/ns/shacl#name> "Datasetbeschrijving"@nl, "Dataset description"@en;
                    <http://www.w3.org/2000/01/rdf-schema#comment> "Een datasetbeschrijving bestaat uit een elementen die de dataset beschrijft"@nl;
                    <http://www.w3.org/ns/shacl#targetClass> <http://schema.org/Dataset>;
                    <http://www.w3.org/ns/shacl#nodeKind> <http://www.w3.org/ns/shacl#IRI>;
                    <http://www.w3.org/ns/shacl#property> <http://terms.netwerkdigitaalerfgoed.nl/ns/register#SchemaNameProperty>, <http://terms.netwerkdigitaalerfgoed.nl/ns/register#SchemaLicenseProperty>, <http://terms.netwerkdigitaalerfgoed.nl/ns/register#SchemaDescriptionProperty>, <http://terms.netwerkdigitaalerfgoed.nl/ns/register#SchemaPublisherPrope
          description: A SHACL shape
      summary: Get the SHACL shape that is used to validate dataset descriptions.
      tags:
      - Validation
servers:
- description: Dataset Register API
  url: https://datasetregister.netwerkdigitaalerfgoed.nl/api
- description: Local development Dataset Register API
  url: http://localhost:3000
tags:
- description: Check whether a URL is eligible for registration before submitting
    it.
  name: Onboarding
- description: |-
    Validate dataset descriptions against the [Requirements for Datasets](https://docs.nde.nl/requirements-datasets/).
    Read-only; safe to call as often as you like.
  name: Validation
- description: Register or update dataset descriptions in the Dataset Register.
  name: Registration
- description: Operations restricted to NDE-issued Bearer tokens. Most integrators
    will not need these.
  name: Administration
