common.yaml

openapi: 3.0.0
info:
  title: Generieke componenten voor Haal Centraal APIs
  description: |
    De definitie van generieke components die worden gebruikt door de Haal Centraal APIs

    DatumOnvolledig is toegevoegd als CamelCase tegenhanger van Datum_onvolledig (deprecated).
    Deze constructie (t.b.v. evolvability) zorgt ervoor dat
    - je geen duplicaat krijgt van een schema en
    - maakt het mogelijk voor een provider om wel al te linken naar deze versie (voor bijvoorbeeld de nieuwe HalPaginationLinks en HalPaginationLinksMetLast schemas) zonder Datum_onvolledig ook te moeten vervangen.
      Deze constructie is wel een overtreding van DD5.21 (een allOf zonder extra properties toevoegingen).
  version: '1.3.0'
  contact:
    name: Haal Centraal Common
    url: https://github.com/VNG-Realisatie/Haal-Centraal-Common
  license:
    name: European Union Public License, version 1.2 (EUPL-1.2)
    url: https://eupl.eu/1.2/nl/
paths: {}
components:
  headers:
    api_version:
      schema:
        type: string
        description: Geeft een specifieke API-versie aan in de context van een specifieke aanroep.
        example: 1.0.0
    warning:
      schema:
        type: string
        description: 'zie RFC 7234. In het geval een major versie wordt uitgefaseerd, gebruiken we warn-code 299 ("Miscellaneous Persistent Warning") en het API end-point (inclusief versienummer) als de warn-agent van de warning, gevolgd door de warn-text met de human-readable waarschuwing'
        example: '299 https://service.../api/.../v1 "Deze versie van de API is verouderd en zal uit dienst worden genomen op 2018-02-01. Raadpleeg voor meer informatie hier de documentatie: https://omgevingswet.../api/.../v1".'
    contentCrs:
      description: CRS van de meegegeven geometrie. epsg:28992 mapt op het RD New Nederlands coordinatenstelsel.
      schema:
        $ref: '#/components/schemas/CrsEnum'
# Dit is RD, het enige coordinatenstelsel dat het kadaster nu kan leveren
# Toevoegen van enumeratiewaarden leidt niet tot breaking changes bij consumers
    X_Pagination_Page:
      schema:
        type: integer
        description: Huidige pagina.
        example: 3
    X_Pagination_Limit:
      schema:
        type: integer
        description: Aantal resultaten per pagina.
        example: 20
    X_Rate_Limit_Limit:
      schema:
        type: integer
    X_Rate_Limit_Remaining:
      schema:
        type: integer
    X_Rate_Limit_Reset:
      schema:
        type: integer
  parameters:
    api-version:
      name: api-version
      in: header
      required: false
      description: "Bevat de major-versie van de aan te roepen API conform [Landelijke API-strategie](https://geonovum.github.io/KP-APIs/#versioning)."
      schema:
        type: integer
        example: 1
    expand:
      name: expand
      in: query
      required: false
      description: "Hiermee kun je opgeven welke gerelateerde resources meegeleverd moeten worden, en hun inhoud naar behoefte aanpassen. Hele resources of enkele properties geef je in de expand parameter kommagescheiden op. Properties die je wil ontvangen geef je op met de resource-naam gevolgd door de property naam, met daartussen een punt. In de definitie van het antwoord kun je bij _embedded zien welke gerelateerde resources meegeleverd kunnen worden. Zie [functionele specificaties](https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/v1.3.0/features/expand.feature)."
      schema:
        type: string
    fields:
      name: fields
      in: query
      required: false
      description: "Hiermee kun je de inhoud van de resource naar behoefte aanpassen door een door komma's gescheiden lijst van property namen op te geven. Bij opgave van niet-bestaande properties wordt een 400 Bad Request teruggegeven. Wanneer de fields parameter niet is opgegeven, worden alle properties met een waarde teruggegeven. Zie [functionele specificaties](https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/v1.3.0/features/fields.feature)"
      schema:
        type: string
    uuid:
      name: uuid
      in: path
      description: "Een UUID is een nummer van 128 bits (= 16 bytes). UUID wordt weergegeven in 32 ??hexadecimale cijfers. Deze cijfers zijn ingedeeld in vijf groepen, in ongelijk aantal en gescheiden door koppeltekens: 8-4-4-4-12 In zijn geheel wordt een UUID dus door 36 tekens gevormd, waarvan 32 hexadecimale karakters en vier streepjes: 550e8400-e29b-41d4-a716-446655440000"
      required: true
      schema:
        type: string
        maxLength: 36
    peildatum:
      name: peildatum
      in: query
      description: "De datum waarop de resource wordt opgevraagd."
      required: false
      schema:
        type: string
        format: date
        example: "2018-09-09"
    datumVan:
      name: datumVan
      in: query
      description: "De begindatum van de periode waarover de resource wordt opgevraagd."
      required: false
      schema:
        type: string
        format: date
        example: "2018-09-09"
    datumTotEnMet:
      name: datumTotEnMet
      in: query
      description: "De einddatum van de periode waarover de resource wordt opgevraagd."
      required: false
      schema:
        type: string
        format: date
        example: "2018-10-09"
    page:
      description: Pagina nummer
      name: page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    pageSize:
      name: pageSize
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    contentCrs:
      name: Content-Crs
      in: header
      required: false
      description: CRS van de meegegeven geometrie. epsg:28992 mapt op het RD New Nederlands coordinatenstelsel.
      schema:
        $ref: '#/components/schemas/CrsEnum'
    acceptCrs:
      name: Accept-Crs
      in: header
      required: false
      description: Gewenste CRS van de coördinaten in de response.
      schema:
        $ref: '#/components/schemas/CrsEnum'
  responses:
    '204':
      description: No content
      headers:
        api-version:
          $ref: "#/components/headers/api_version"
    '400':
      description: Bad Request
      headers:
        api-version:
          $ref: "#/components/headers/api_version"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/BadRequestFoutbericht"
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1
            title: Ten minste één parameter moet worden opgegeven.
            status: 400
            detail: The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modification.
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: paramsRequired
            invalidParams:
              - type: https://www.vng.nl/realisatie/api/validaties/integer
                name: verblijfplaats__huisnummer
                code: integer
                reason: Waarde is geen geldige integer.
    '401':
      description: Unauthorized
      headers:
        api-version:
          $ref: "#/components/headers/api_version"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Foutbericht"
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2
            title: Niet correct geauthenticeerd.
            status: 401
            detail: The request requires user authentication. The response MUST include a WWW-Authenticate header field (section 14.47) containing a challenge applicable to the requested resource.
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: authentication
    '403':
      description: Forbidden
      headers:
        api-version:
          $ref: "#/components/headers/api_version"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Foutbericht"
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4
            title: U bent niet geautoriseerd voor deze operatie.
            status: 403
            detail: The server understood the request, but is refusing to fulfill it.
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: autorisation
    '404':
      description: Not Found
      headers:
        api-version:
          $ref: "#/components/headers/api_version"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Foutbericht"
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5
            title: Opgevraagde resource bestaat niet.
            status: 404
            detail: The server has not found anything matching the Request-URI.
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: notFound
    '406':
      description: Not Acceptable
      headers:
        api-version:
          $ref: "#/components/headers/api_version"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Foutbericht"
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7
            title: Gevraagde contenttype wordt niet ondersteund.
            status: 406
            detail: The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to thr accept headers sent in the request
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: notAcceptable
    '409':
      description: Conflict
      headers:
        api-version:
          $ref: "#/components/headers/api_version"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Foutbericht"
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10
            title: Conflict
            status: 409
            detail: The request could not be completed due to a conflict with the current state of the resource
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: conflict
    '410':
      description: Gone
      headers:
        api-version:
          $ref: "#/components/headers/api_version"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Foutbericht"
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.11
            title: Gone
            status: 410
            detail: The request could not be completed due to a conflict with the current state of the resource
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: gone
    '412':
      description: Precondition failed
      headers:
        api-version:
          $ref: "#/components/headers/api_version"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Foutbericht"
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.13
            title: Precondition Failed
            status: 412
            detail: The precondition given in one or more of the request-header fields evaluated to false when it was tested on the server.
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: preconditionFailed
    '415':
      description: Unsupported Media Type
      headers:
        api-version:
          $ref: "#/components/headers/api_version"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Foutbericht"
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16
            title: Unsupported Media Type
            status: 415
            detail: The server is refusing the request because the entity of the request is in a format not supported by the requested resource for the requested method.
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: unsupported
    '422':
      description: Unprocessable entity
      headers:
        api-version:
          $ref: "#/components/headers/api_version"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Foutbericht"
          example:
            type: https://tools.ietf.org/html/rfc4918#section-11.2
            title: Aanvraag kan niet verwerkt worden
            status: 422
            detail: The server understands the content type of the request entity and the syntax of the request entity is correct but was unable to process the contained instructions.
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: unprocessableEntity
    '429':
      description: Too Many Requests
      headers:
        api-version:
          $ref: "#/components/headers/api_version"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Foutbericht"
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
            title: Too many request
            status: 429
            detail: The user has sent too many requests in a given amount of time (rate limiting).
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: tooManyRequests
    '500':
      description: Internal Server Error
      headers:
        api-version:
          $ref: "#/components/headers/api_version"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Foutbericht"
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1
            title: Interne server fout.
            status: 500
            detail: The server encountered an unexpected condition which prevented it from fulfilling the request.
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: serverError
    '501':
      description: Not Implemented
      headers:
        api-version:
          $ref: "#/components/headers/api_version"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Foutbericht"
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2
            title: Not Implemented
            status: 501
            detail: The server does not support the functionality required to fulfill the request.
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: notImplemented
    '503':
      description: Service Unavailable
      headers:
        api-version:
          $ref: "#/components/headers/api_version"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Foutbericht"
          example:
            type: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4
            title: Bronservice {bron} is tijdelijk niet beschikbaar.
            status: 503
            detail: The service is currently unable to handle the request due to a temporary overloading or maintenance of the server.
            instance: https://datapunt.voorbeeldgemeente.nl/api/v1/resourcenaam?parameter=waarde
            code: notAvailable
    'default':
      description: Er is een onverwachte fout opgetreden
      headers:
        api-version:
          $ref: "#/components/headers/api_version"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Foutbericht"
  schemas:
    Href:
      type: string
      example: "https://datapunt.voorbeeldgemeente.nl/api/v{major-versie}/resourcename/{resource-identificatie}"
    HalLink:
      description: De Link Object zoals gespecificeerd in https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5; Deze link kan als templated link worden aangeboden. [URI-templating is hier beschreven](https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/v1.3.0/features/uri-templating.feature).
      type: object
      required:
        - href
      properties:
        href:
          $ref: "#/components/schemas/Href"
        templated:
          type: boolean
        title:
         description: "Voor mens leesbaar label bij de link"
         type: string
    HalCollectionLinks:
      type: object
      description: |
        HalCollectionLinks bevat de self link die elke HAL Resource minimaal moet hebben in zijn _links property
      properties:
        self:
          $ref: "#/components/schemas/HalLink"
    HalPaginationLinks:
      description: |
        HalPaginationLinks bevat de link properties die nodig zijn om te kunnen navigeren in een collectie:

        - first: uri voor het opvragen van de eerste pagina van deze collectie
        - previous: uri voor het opvragen van de vorige pagina van deze collectie
        - next: uri voor het opvragen van de volgende pagina van deze collectie
      allOf:
      - $ref: "#/components/schemas/HalCollectionLinks"
      - type: object
        properties:
          first:
            $ref: "#/components/schemas/HalLink"
          previous:
            $ref: "#/components/schemas/HalLink"
          next:
            $ref: "#/components/schemas/HalLink"
      example:
        self:
          href: /resourcenaam?page=4
        first:
          href: /resourcenaam?page=1
          title: Eerste pagina
        previous:
          href: /resourcenaam?page=3
          title: Vorige pagina
        next:
          href: /resourcenaam?page=5
          title: Volgende pagina
    HalPaginationLinksMetLast:
      description: |
        HalPaginationLinksMetLast bevat de link properties die nodig zijn om te kunnen navigeren in een eindige collectie:

        - first: uri voor het opvragen van de eerste pagina van deze collectie
        - previous: uri voor het opvragen van de vorige pagina van deze collectie
        - next: uri voor het opvragen van de volgende pagina van deze collectie
        - last: uri voor het opvragen van de laatste pagina van deze collectie
      allOf:
      - $ref: "#/components/schemas/HalPaginationLinks"
      - type: object
        properties:
          last:
            $ref: "#/components/schemas/HalLink"
      example:
        self:
          href: /resourcenaam?page=4
        first:
          href: /resourcenaam?page=1
          title: Eerste pagina
        previous:
          href: /resourcenaam?page=3
          title: Vorige pagina
        next:
          href: /resourcenaam?page=5
          title: Volgende pagina
        last:
          href: /resourcenaam?page=8
          title: Laatste pagina
    Foutbericht:
      type: object
      description: Terugmelding bij een fout. JSON representatie in lijn met [RFC7807](https://tools.ietf.org/html/rfc7807).
      properties:
        type:
          type: string
          format: uri
          description: Link naar meer informatie over deze fout
        title:
          type: string
          description: Beschrijving van de fout
        status:
          type: integer
          description: Http status code
        detail:
          type: string
          description: Details over de fout
        instance:
          type: string
          format: uri
          description: Uri van de aanroep die de fout heeft veroorzaakt
        code:
          type: string
          description: Systeemcode die het type fout aangeeft
          minLength: 1
    InvalidParams:
      type: object
      description: Details over fouten in opgegeven parameters
      properties:
        type:
          type: string
          format: uri
          example: "https://www.vng.nl/realisatie/api/{major-versie}/validaties/integer"
        name:
          type: string
          description: Naam van de parameter
          example: "verblijfplaats__huisnummer"
        code:
          type: string
          description: Systeemcode die het type fout aangeeft
          minLength: 1
          example: "integer"
        reason:
          type: string
          description: Beschrijving van de fout op de parameterwaarde
          example: "Waarde is geen geldige integer."
    BadRequestFoutbericht:
      allOf:
      - $ref: "#/components/schemas/Foutbericht"
      - type: "object"
        properties:
          invalidParams:
            description: Foutmelding per fout in een parameter. Alle gevonden fouten worden één keer teruggemeld.
            type: array
            items:
              $ref: "#/components/schemas/InvalidParams"
    DatumOnvolledig:
      type: "object"
      description: "Gegevens over de datums die mogelijk niet volledig zijn."
      properties:
        dag:
          type: "integer"
          description: "Als de dag van de datum bekend is wordt dit element gevuld, ook als de volledige datum bekend is."
          minimum: 1
          maximum: 31
          example: 3
        datum:
          type: "string"
          description: "Als de volledige datum bekend is wordt de datum gevuld die in de date definitie past."
          format: "date"
          example: "1989-05-03"
        jaar:
          type: "integer"
          description: "Als het jaar van de datum bekend is wordt dit element gevuld, ook als de volledige datum bekend is."
          maximum: 9999
          example: 1989
        maand:
          type: "integer"
          description: "Als de maand van een datum bekend is wordt dit element gevuld, ook als de volledige datum bekend is."
          minimum: 1
          maximum: 12
          example: 5
    Datum_onvolledig:
      deprecated: true
      allOf:
          - $ref: "#/components/schemas/DatumOnvolledig"
    Waardelijst:
      type: "object"
      description: "Generieke waardelijst met waarden om een code en omschrijving op te nemen."
      properties:
        code:
          type: "string"
          description: "6"
        waarde:
          type: "string"
          description: "Huurrecht (zakelijk)"
    Waardetabel:
      type: "object"
      properties:
        code:
          type: "string"
          example: "6030"
        omschrijving:
          type: "string"
          example: "Nederland"
    Geometry:
      description: GeoJSON geometry
      required:
      - type
      type: object
      properties:
        type:
          description: The geometry type
          type: string
          enum:
          - Point
          - MultiPoint
          - LineString
          - MultiLineString
          - Polygon
          - MultiPolygon
          - Feature
          - FeatureCollection
          - GeometryCollection
      discriminator:
        propertyName: type
      externalDocs:
        url: https://tools.ietf.org/html/rfc7946#section-3.1
    Point2D:
      description: A 2D point
      type: array
      items:
        type: number
      maxItems: 2
      minItems: 2
    Point:
      description: GeoJSON point geometry
      type: object
      allOf:
      - $ref: '#/components/schemas/Geometry'
      - required:
        - coordinates
        type: object
        properties:
          coordinates:
            $ref: '#/components/schemas/Point2D'
      externalDocs:
        url: https://tools.ietf.org/html/rfc7946#section-3.1.2
    MultiPoint:
      description: GeoJSON multi-point geometry
      type: object
      allOf:
      - $ref: '#/components/schemas/Geometry'
      - required:
        - coordinates
        type: object
        properties:
          coordinates:
            type: array
            items:
              $ref: '#/components/schemas/Point2D'
      externalDocs:
        url: https://tools.ietf.org/html/rfc7946#section-3.1.3
    LineString:
      description: GeoJSON line-string geometry
      type: object
      allOf:
      - $ref: '#/components/schemas/Geometry'
      - required:
        - coordinates
        type: object
        properties:
          coordinates:
            type: array
            items:
              $ref: '#/components/schemas/Point2D'
            minItems: 2
      externalDocs:
        url: https://tools.ietf.org/html/rfc7946#section-3.1.4
    MultiLineString:
      description: GeoJSON multi-line-string geometry
      type: object
      allOf:
      - $ref: '#/components/schemas/Geometry'
      - required:
        - coordinates
        type: object
        properties:
          coordinates:
            type: array
            items:
              type: array
              items:
                $ref: '#/components/schemas/Point2D'
      externalDocs:
        url: https://tools.ietf.org/html/rfc7946#section-3.1.5
    Polygon:
      description: GeoJSON polygon geometry
      type: object
      allOf:
      - $ref: '#/components/schemas/Geometry'
      - required:
        - coordinates
        type: object
        properties:
          coordinates:
            type: array
            items:
              type: array
              items:
                $ref: '#/components/schemas/Point2D'
      externalDocs:
        url: https://tools.ietf.org/html/rfc7946#section-3.1.6
    MultiPolygon:
      description: GeoJSON multi-polygon geometry
      type: object
      allOf:
      - $ref: '#/components/schemas/Geometry'
      - required:
        - coordinates
        type: object
        properties:
          coordinates:
            type: array
            items:
              type: array
              items:
                type: array
                items:
                  $ref: '#/components/schemas/Point2D'
      externalDocs:
        url: https://tools.ietf.org/html/rfc7946#section-3.1.7
    GeometryCollection:
      description: GeoJSON multi-polygon geometry
      type: object
      allOf:
      - $ref: '#/components/schemas/Geometry'
      - required:
        - geometries
        type: object
        properties:
          geometries:
            type: array
            items:
              $ref: '#/components/schemas/Geometry'
      externalDocs:
        url: https://tools.ietf.org/html/rfc7946#section-3.1.8
    GeoJSONGeometry:
      type: object
      oneOf:
      - $ref: "#/components/schemas/Point"
      - $ref: "#/components/schemas/MultiPoint"
      - $ref: "#/components/schemas/LineString"
      - $ref: "#/components/schemas/MultiLineString"
      - $ref: "#/components/schemas/Polygon"
      - $ref: "#/components/schemas/MultiPolygon"
      - $ref: "#/components/schemas/GeometryCollection"
    CrsEnum:
      description: CRS van geometrie. epsg:28992 mapt op het RD New Nederlands coordinatenstelsel.
      type: string
      enum:
        - epsg:28992
      default: epsg:28992
      # Dit is RD, het enige coordinatenstelsel dat het kadaster nu (19-05-2020) kan leveren
      # Toevoegen van enumeratiewaarden leidt niet tot breaking changes bij consumers
      # Voor 1.3.0 de default toegevoegd. Daarmee voorkomen we dat de Content-Crs verplicht opgegeven moet worden zolang er maar 1 waarde is