Geconstateerde afwijken t.o.v. de Haal Centraal Design Decisions

[melsk-r]

De huidige versie van de Haal Centraal BAG specificaties wijkt op de volgende punten af van de Haal Centraal Design Decisions en behoeft aanpassing of heroverweging:

• DD1.6 Naamgeving van properties worden beïnvloed door de kardinaliteit

  • In 'openapi.yaml' kennen de componenten 'AdresMogelijkOnjuist', 'AdresseerbaarObjectMogelijkOnjuist', 'OpenbareRuimteMogelijkOnjuist', 'NummeraanduidingMogelijkOnjuist', 'WoonplaatsMogelijkOnjuist', 'PandMogelijkOnjuist' de property 'toelichting'.
    Dit is echter een array en zou volgens de Design Decision dus 'toelichtingen' moeten heten.

  • In 'openapi.yaml' kent het component 'AdresseerbaarObjectMogelijkOnjuist' de properties 'nummeraanduidingIdentificaties' en 'pandIdentificaties'. Aangezien het bij beiden geen array betreft voldoet deze niet aan de Design Decision. Het lijkt er echter op dat hier sprake is van een uitzondering op de Design Decision. De namen van de properties verwijzen nl. naar properties in het component 'AdresseerbaarObject' teneinde daar iets over te kunnen zeggen en moeten om die reden gelijk zijn aan de namen in dat laatste component.

• DD1.10 Naamgeving van enumeratiewaarden wordt ontdaan van spaties en bijzondere tekens
  De enumerations in de volgende componenten bevatten nog spaties:

  • 'AdresseerbaarObjectStatusEnum'
  • 'GebruiksdoelEnum'
  • 'StatusNaamgevingEnum'
  • 'StatusPandEnum'
  • 'StatusWoonplaatsEnum'

  daarnaast is de naamgeving inconsistent aangezien sommige enumeraties wel starten met hoofdletters en anderen niet.

• DD1.12 Redundantie in propertynamen wordt verwijderd.
  De property 'nummeraanduidingIdentificaties' bevat de property 'nummeraanduidingIdentificatie'. Deze kan hernoemd worden naar eenvoudigweg' de naam 'identificatie'.

• DD2.4 Gebruik zo mogelijk boolean i.p.v. een enumeration
  Het enumeration component 'StatusNaamgevingEnum' kent slechts 1 waarde (nl. 'Naamgeving uitgegeven').
  Indien geen andere waarden worden verwacht in de toekomst dan kan de naam van de property die dit component gebruikt wellicht gewijzigd worden in iets als 'naamgevingUitgegeven' met een boolean waarde.

[melsk-r]

• DD1.3 Schema componentnamen zijn in UpperCamelCase
  I.v.m. deze Design Decision en n.a.v. verwijderen vaste naamgeving componenten met underscore VNG-Realisatie/Haal-Centraal-common#76 zijn nu in de specs op diverse plaatsen de underscores uit de componentnamen verwijderd. De vraag is of dat bij de componenten:

  • api_version
  • X_Pagination_Page
  • X_Pagination_Limit

  ook niet zou moeten gebeuren?

[strijm]

@melsk-r
M.i. levert het wijzigen van bovenstaande in de API specificatie breaking changes op. Deze wijzigingen kunnen daarom pas bij een volgende major versie meegenomen worden.

[fsamwel]

wat betreft de status waarden, hierover is door het Kadaster aangegeven dat deze waarden as is moeten worden doorgegeven. Daar waren we destijds niet blij over, maar hebben we geaccepteerd. De vraag is dan of het terecht is dat dit enumeraties zijn, wanneer de volledige beschrijving doorgeven blijkbaar zo belangrijk is (niet vervangen kan worden door een enumeratiecode).