Als leverancier wil ik dat de API specificatie alle relevante validatie teksten bevat uit het informatiemodel

[joeribekker]

...zodat er geen verkeerde implementaties worden gedaan op basis van een incomplete API specificatie.

Voorbeeld: Het attribuut CATALOGUS.domein heeft in de API specificatie enkel de tekst:

Het ImZTC (informatiemodel ZaakTypeCatalogus) bevat echter deze tekst:

Helemaal onderaan staat opeens dat de waardeverzameling enkel hoofdletters bevat.

Je ziet hier precies wat al vanaf het begin speelt: Ontwikkelaars lezen het informatiemodel niet. Dat valt niemand kwalijk te nemen maar des te meer reden om een nog betere API specificatie op te stellen en de API-specificatie als standaard te hanteren (ipv het informatiemodel)

Ik denk dat het goed is om elk attribuut eens langs te lopen en meer relevante informatie bij het attribuut op te nemen. Minimaal zou de "waardeverzameling" geautomatiseerd opgenomen worden in de API specificatie.

[terborg]

Volledig mee eens. Als ontwikkelaars het informatiemodel niet lezen, dan lezen ze vast ook de OAS niet, daarom lijkt het me een idee als we nog een stap verder gaan en de constraints encoden in de spec zelf. In jouw voorbeeld zouden we pattern: kunnen gebruiken en de ontwikkelaars van tests zouden kunnen voorzien (zoveel mogelijk volledig op basis van de spec).

properties:
  ...
  domein:
    description: Een afkorting waarvan … 
    type: string
    minLength: 1
    maxLength: 5
    pattern: "^[A-Z]{1,5}$"
    example: ABC
    externalDocs:
      description: Meer informatie over dit veld
      url: https://link-naar-docs/../meer-info-over-domein
...
examples:
  voorbeeld-200:
    value:
      ...
      domein: XYZ
  voorbeeld-400:
    value:
      ...
      domein: xyz