Design rules die waren goedgekeurd opgenomen #138

JohanBoer · 2022-04-29T10:51:08Z

No description provided.

melsk-r · 2022-05-24T11:50:16Z

Design rules/Diversen.md

+
+### DR4.2 Neem voor properties geen waarden op met een speciale betekenis
+
+We nemen geen waarden op met een speciale betekenis die afwijkt van de normale betekenis van het gegeven.


Volgens mij is er van 'opnemen' sowieso geen sprake maar meer van toestaan. N.m.m. dus wijzigen in:

We staan voor een gegeven geen waarden toe met een speciale betekenis, een betekenis die afwijkt van de normale betekenis van het gegeven.

melsk-r · 2022-05-24T11:52:49Z

Design rules/Diversen.md

+bijvoorbeeld datum "0000-00-00" om aan te geven dat een datum onbekend is
+bijvoorbeeld landcode "0000" om aan te geven dat het land onbekend is
+
+Ratio: Als er informatie beschikbaar is moet die als zondanig onderkend en gemodelleerd worden.


Bijvoorbeeld door in de bovenstaande voorbeelden een datumOnbekend en landOnbekend te modelleren.

Wellicht in deze DR ook verwijzen naar DR 2.9.

melsk-r · 2022-05-24T12:01:46Z

Design rules/Diversen.md

+
+Er wordt hier uit twee componenten overgeërfd wat niet correct is.
+
+Voorbeeld van het foutief gebruik van allOf:


Dit voorbeeld gaat niet in tegen deze Design Rule. Er is immers slechts 1 component waarnaar gerefereerd wordt.
Ik denk dat dit een andere Design Rule is.

melsk-r · 2022-05-24T12:03:48Z

Design rules/Diversen.md

+Datum opname : 29-04-2021
+Datum wijziging : 29-04-2021
+
+## DR4.4 Als meerdere componenten dezelfde properties bevatten (generalisatie) gebruik dan de 'allOf' om deze samenhang vorm te geven.


Voeg 1 '#' toe anders staat deze paragraaf op hetzelfde niveau als de paragraaf in regel 6.

melsk-r · 2022-05-24T12:04:05Z

Design rules/Diversen.md

+               example: 300
+```
+
+## DR4.5 Plaats bij het gebruik van 'allOf' het hergebruikte component als eerste.


Voeg 1 '#' toe anders staat deze paragraaf op hetzelfde niveau als de paragraaf in regel 6.

melsk-r · 2022-05-24T12:04:14Z

Design rules/Diversen.md

+Datum opname : 29-04-2021
+Datum wijziging : 29-04-2021
+
+## DR4.6 Bij het gebruik van 'allOf' is er slechts 1 component waarnaar gerefereerd wordt


Voeg 1 '#' toe anders staat deze paragraaf op hetzelfde niveau als de paragraaf in regel 6.

melsk-r · 2022-05-24T12:06:04Z

Design rules/Diversen.md

+
+
+
+Wanneer er meerdere componenten zijn met meerdere dezelfde properties, moet er hergebruik worden gemaakt via een 'allOf' constructie. Dit sluit aan op object oriëntatie in de verschillende programmeeromgevingen.


Waar dienen de bovenstaande witregels voor?
Als deze en onderstaande regels niet bij DR4.6 horen dan wellicht een aparte Design Rule opvoeren of een paragraaf zonder Design Rule opvoeren.

Ik zie trouwens dat deze regels een kopie zijn van de regels 41 t/m 45 dus wellicht kunnen ze weg.

melsk-r · 2022-05-24T12:09:14Z

Design rules/Naamgeving.md

+
+## DR1.7 Wanneer pas je enkelvoud of meervoud toe in propery-namen
+
+Als het een propertynaam is die verwijst naar eenb gerelateerde resource dan wanneer wordt de resourcenaam enkelvoud als de gerelateerde resource één keer kan voorkomen. Wanneer de gerelateerde resource meerdere keren kan voorkomen, wordt de resourcenaam in meervoud gebruikt.


Als het een propertynaam is die verwijst naar een gerelateerde resource dan wanneer wordt de resourcenaam in enkelvoud uitgedrukt als de gerelateerde resource slechts één keer kan voorkomen. Wanneer de gerelateerde resource meerdere keren kan voorkomen, wordt de resourcenaam in meervoud uitgedrukt.

melsk-r · 2022-05-24T12:10:22Z

Design rules/Waarden.md

+### DR2.1 Voor het uitdrukken van tijdsduur gebruiken we de ISO-8601 standaard
+Een toelichting is [hier](https://nl.wikipedia.org/wiki/ISO_8601) te vinden.
+
+_**Ratio:**_


Voeg regel 12 en 14 samen zodat Ratio's consistent worden opgemaakt.

melsk-r · 2022-05-24T12:12:03Z

Design rules/Waarden.md

+
+### DR2.3 Dynamische domeinwaarden worden in de query-parameters met de code opgenomen
+
+Voor een query-parameter waarin een entry uit een waardelijst of een landelijke tabel als selectie-criterium wordt gebruikt wordt de code van de entry gebruikt.


'Voor een query-parameter ...' --> 'Voor de waarden van een query-parameter ...'

melsk-r · 2022-05-24T12:17:17Z

Design rules/Waarden.md

+
+## DR2.6 Beperk de lengte van enumeratiewaarden
+
+De lengte van enumeratiewaarden wordt beperkt. Bijvoorbeeld "Opstalhouder Nutsvoorzieningen op gedeelte van perceel" krijgt als waarde "nutsvoorzieningen_gedeelte". Het is aan de API-designer en de betreffende community om de toe te passen waarden te bepalen. Gebruik alleen enumeraties als de waarde kort, zelfbeschrijvend en stabiel is.


De laatste zin van deze alinea riekt naar een eigen Design Rule. Het kenmerk 'stabiel' heeft nl. niets met de lengte van doen.
Dat daargelaten zou ik trouwens verwachten dat die zin als volgt was gedefinieerd:

Gebruik alleen enumeratiewaardes die kort, zelfbeschrijvend en stabiel zijn.

melsk-r · 2022-05-24T12:18:05Z

Design rules/Waarden.md

+
+De lengte van enumeratiewaarden wordt beperkt. Bijvoorbeeld "Opstalhouder Nutsvoorzieningen op gedeelte van perceel" krijgt als waarde "nutsvoorzieningen_gedeelte". Het is aan de API-designer en de betreffende community om de toe te passen waarden te bepalen. Gebruik alleen enumeraties als de waarde kort, zelfbeschrijvend en stabiel is.
+
+Als er behoefte is aan lange enumeratiewaarde is een referentielijst mogelijk een beter alternatief. Ook als de waarden van de betreffende lijst mutabel is is een referentielijst een betere keuze.


'enumeratiewaarde' --> 'enumeratiewaarden'

melsk-r · 2022-05-24T12:18:38Z

Design rules/Waarden.md

+
+Als er behoefte is aan lange enumeratiewaarde is een referentielijst mogelijk een beter alternatief. Ook als de waarden van de betreffende lijst mutabel is is een referentielijst een betere keuze.
+
+Mocht het toch van belang zijn de lange omschrijving te delen met de comsumer-developer, dan kan deze lange omschrijving opgenomen worden in de description van de enumeratie. Indien gewenst zou deze lange omschrijving dan additioneel aangeboden kunnen worden als property.


'comsumer-...' --> 'consumer-...'

melsk-r · 2022-05-24T12:19:23Z

Design rules/Waarden.md

+'''
+
+_**Ratio:**_
+Vanuit developer-perspectief zijn lange enumeratiewaarde onprettig om mee te werken. Ook het tonen van enumeratiewaarden in de User Interface wordt complex als de enumartiewaarden te onnodig lang zijn.


'enumartiewaarden' --> 'enumeratiewaarden'
'te onnodig lang' --> 'onnodig te lang'

melsk-r · 2022-05-24T12:20:36Z

Design rules/Waarden.md

+  description: De volledige naam van de taal
+'''
+
+_**Ratio:**_


Voeg regel 78 en 79 samen.

melsk-r · 2022-05-24T12:20:57Z

Design rules/Waarden.md

+
+Gebruik enumeratiewaarden die betekenisvol en begrijpelijk zijn. Dus niet M en V, maar man en vrouw. Hierbij moet een afweging gemaakt worden met het toepassen van Design Rule DR2.6
+
+_**Ratio:**_


Voeg regel 88 en 89 samen.

melsk-r · 2022-05-24T12:21:42Z

Design rules/Waarden.md

+
+## DR2.8 Overweeg een enumeratiewaarde weer te geven als string in een bevraging-API
+
+Het toepassen van een enumratie brengt het risico van tight coupling en breaking changes met zich mee.


'enumratie' --> 'enumeratie'

melsk-r · 2022-05-24T12:22:56Z

Design rules/Waarden.md

+
+Indien een attribuut in het informatiemodel voorkomt als enumeratie, maar de corresponderende property komt alleen voor in de response op een bevraging om aan gebruikers te worden getoond dan is het niet nodig het ook in de API specificaties als een enumeratie te definiëren.
+
+Wanneer de enumeratiewaarde gebruikt wordt in code (algoritmes), definieer dan betekenisvolle maar bondige enumeratiewaarden.


Dit lijkt mij al in DR2.7 verwoord en mag hier dus worden verwijderd.

melsk-r · 2022-05-24T12:23:34Z

Design rules/Waarden.md

+
+Wanneer de enumeratiewaarde gebruikt wordt in code (algoritmes), definieer dan betekenisvolle maar bondige enumeratiewaarden.
+
+_**Ratio:**_


Voeg regel 99 en 101 samen.

melsk-r · 2022-05-24T12:27:23Z

Design rules/Waarden.md

+
+Wanneer het gevuld zijn van een datum functionele betekenis heeft, ook wanneer deze volledig onbekend is, wordt een indicator opgenomen om dit aan te geven. Als bv een datum veld de waarde "00000000" bevat en dat betekenis heeft wordt niet deze ongeldige waarde opgenomen in een date-veld, maar wordt een indicator toegevoegd.
+
+Indien in het onderstaande voorbeeld er helemaal niets bekend is van de overlijdensdatum, maar er is wel bekend dat de persoon overleden is, dan kan dat nergens uit worden afgeleid. Uit de reponse kan je niet opmaken of de overlijdensdatum leeg is omdat iemand  niet is overleden of omdat de overlijdensdatum niet bekend is.


'... omdat iemand niet is ...' --> '... omdat iemand niet is ...' (spatie verwijderd)

melsk-r · 2022-05-24T12:30:53Z

Design rules/Waarden.md

+          type: string
+```
+
+_**Ratio:**_


Hier geef je als Ratio een voorbeeld, de ratio is volgens mij echter nooit een voorbeeld maar legt uit waarom we dit zo doen. Hier zou je i.i.g. al aan kunnen geven dat we op deze wijze voldoen aan DR4.2 maar wellicht kunnen we codeertechnische redenen aanvoeren waarom dit beter is. Zo vermoed ik dat tegen deze wijze van modelleren eenvoudiger te programmeren is.

Voeg ook regel 141 en 142 samen.

melsk-r · 2022-07-01T09:36:26Z

i.v.m. issue #131 stel ik voor om aan het bestand 'Design rules/Diversen.md' nog de volgende Design Rule toe te voegen.
Graag m.n. nog even aandacht voor de zin

Om de developer de gelegenheid te geven dat gedrag ook te sturen MAG er aan de parameters van berichten de parameter 'includeNullValues' worden toegevoegd.

Ik vraag me nl. af of in dat geval de betreffende parameter niet toegevoegd MOET worden.

DR4.7 T.b.v. verkrijging totale response tijdens development mag de property 'nullable' op optionele velden gespecificeerd worden

Optionele velden worden over het algemeen niet terug gegeven in de response van een REST bericht als ze leeg zijn. Om een overzicht te krijgen van alle mogelijk terug te ontvangen velden kan het voor developers handig zijn deze velden tijdens ontwikkeling wel terug te krijgen als alternatief voor het bekijken van de OAS specificaties in Swagger en/of Redoc. Ten einde die behoefte te ondersteunen mag in de OAS specificatie daarom op een optioneel veld de property 'nullable' gedefinieerd worden met de waarde 'true'.

Daarmee wordt gedefinieerd dat een veld met een lege waarde teruggegeven MAG worden. Om de developer de gelegenheid te geven dat gedrag ook te sturen MAG er aan de parameters van berichten de parameter 'includeNullValues' worden toegevoegd. Dat dient dan te gebeuren in de volgende vorm:

  - name: includeNullValues
    in: query
    description: Bepaald of Null waarden opgenomen moeten worden in de response.
    required: false
    schema:
        type: boolean
        default: false

Het heeft dus standaard de waarde 'false' wat betekent dat een developer als het gebruik wil maken van deze optie deze parameter expliciet moet opgeven met de waarde 'true'.

TODO: Definiëren hoe hiermee om te gaan in relatie tot lege array's.

Design rules die waren goedgekeurd opgenomen

22047e2

JohanBoer requested review from melsk-r and michielverhoef April 29, 2022 10:51

JohanBoer requested a review from HenriKorver May 23, 2022 09:01

melsk-r reviewed May 24, 2022

View reviewed changes

Design rules/Waarden.md

description: De volledige naam van de taal

'''

_**Ratio:**_

Copy link

Contributor

melsk-r May 24, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Voeg regel 78 en 79 samen.

melsk-r reviewed May 24, 2022

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Design rules die waren goedgekeurd opgenomen #138

Design rules die waren goedgekeurd opgenomen #138

JohanBoer commented Apr 29, 2022

melsk-r May 24, 2022

melsk-r May 24, 2022 •

edited

Loading

melsk-r May 24, 2022

melsk-r May 24, 2022

melsk-r May 24, 2022

melsk-r May 24, 2022

melsk-r May 24, 2022 •

edited

Loading

melsk-r May 24, 2022

melsk-r May 24, 2022

melsk-r May 24, 2022

melsk-r May 24, 2022

melsk-r May 24, 2022

melsk-r May 24, 2022

melsk-r May 24, 2022 •

edited

Loading

melsk-r May 24, 2022

melsk-r May 24, 2022

melsk-r May 24, 2022

melsk-r May 24, 2022

melsk-r May 24, 2022

melsk-r May 24, 2022

melsk-r May 24, 2022 •

edited

Loading

melsk-r commented Jul 1, 2022


		### DR4.2 Neem voor properties geen waarden op met een speciale betekenis

		We nemen geen waarden op met een speciale betekenis die afwijkt van de normale betekenis van het gegeven.


		Er wordt hier uit twee componenten overgeërfd wat niet correct is.

		Voorbeeld van het foutief gebruik van allOf:




		Wanneer er meerdere componenten zijn met meerdere dezelfde properties, moet er hergebruik worden gemaakt via een 'allOf' constructie. Dit sluit aan op object oriëntatie in de verschillende programmeeromgevingen.


		## DR1.7 Wanneer pas je enkelvoud of meervoud toe in propery-namen

		Als het een propertynaam is die verwijst naar eenb gerelateerde resource dan wanneer wordt de resourcenaam enkelvoud als de gerelateerde resource één keer kan voorkomen. Wanneer de gerelateerde resource meerdere keren kan voorkomen, wordt de resourcenaam in meervoud gebruikt.


		### DR2.3 Dynamische domeinwaarden worden in de query-parameters met de code opgenomen

		Voor een query-parameter waarin een entry uit een waardelijst of een landelijke tabel als selectie-criterium wordt gebruikt wordt de code van de entry gebruikt.


		## DR2.6 Beperk de lengte van enumeratiewaarden

		De lengte van enumeratiewaarden wordt beperkt. Bijvoorbeeld "Opstalhouder Nutsvoorzieningen op gedeelte van perceel" krijgt als waarde "nutsvoorzieningen_gedeelte". Het is aan de API-designer en de betreffende community om de toe te passen waarden te bepalen. Gebruik alleen enumeraties als de waarde kort, zelfbeschrijvend en stabiel is.


		De lengte van enumeratiewaarden wordt beperkt. Bijvoorbeeld "Opstalhouder Nutsvoorzieningen op gedeelte van perceel" krijgt als waarde "nutsvoorzieningen_gedeelte". Het is aan de API-designer en de betreffende community om de toe te passen waarden te bepalen. Gebruik alleen enumeraties als de waarde kort, zelfbeschrijvend en stabiel is.

		Als er behoefte is aan lange enumeratiewaarde is een referentielijst mogelijk een beter alternatief. Ook als de waarden van de betreffende lijst mutabel is is een referentielijst een betere keuze.


		Als er behoefte is aan lange enumeratiewaarde is een referentielijst mogelijk een beter alternatief. Ook als de waarden van de betreffende lijst mutabel is is een referentielijst een betere keuze.

		Mocht het toch van belang zijn de lange omschrijving te delen met de comsumer-developer, dan kan deze lange omschrijving opgenomen worden in de description van de enumeratie. Indien gewenst zou deze lange omschrijving dan additioneel aangeboden kunnen worden als property.


		Gebruik enumeratiewaarden die betekenisvol en begrijpelijk zijn. Dus niet M en V, maar man en vrouw. Hierbij moet een afweging gemaakt worden met het toepassen van Design Rule DR2.6

		_Ratio:_


		## DR2.8 Overweeg een enumeratiewaarde weer te geven als string in een bevraging-API

		Het toepassen van een enumratie brengt het risico van tight coupling en breaking changes met zich mee.


		Indien een attribuut in het informatiemodel voorkomt als enumeratie, maar de corresponderende property komt alleen voor in de response op een bevraging om aan gebruikers te worden getoond dan is het niet nodig het ook in de API specificaties als een enumeratie te definiëren.

		Wanneer de enumeratiewaarde gebruikt wordt in code (algoritmes), definieer dan betekenisvolle maar bondige enumeratiewaarden.


		Wanneer het gevuld zijn van een datum functionele betekenis heeft, ook wanneer deze volledig onbekend is, wordt een indicator opgenomen om dit aan te geven. Als bv een datum veld de waarde "00000000" bevat en dat betekenis heeft wordt niet deze ongeldige waarde opgenomen in een date-veld, maar wordt een indicator toegevoegd.

		Indien in het onderstaande voorbeeld er helemaal niets bekend is van de overlijdensdatum, maar er is wel bekend dat de persoon overleden is, dan kan dat nergens uit worden afgeleid. Uit de reponse kan je niet opmaken of de overlijdensdatum leeg is omdat iemand niet is overleden of omdat de overlijdensdatum niet bekend is.

Design rules die waren goedgekeurd opgenomen #138

Are you sure you want to change the base?

Design rules die waren goedgekeurd opgenomen #138

Conversation

JohanBoer commented Apr 29, 2022

Choose a reason for hiding this comment

melsk-r May 24, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

melsk-r May 24, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

melsk-r May 24, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

melsk-r May 24, 2022 • edited Loading

Choose a reason for hiding this comment

melsk-r commented Jul 1, 2022

DR4.7 T.b.v. verkrijging totale response tijdens development mag de property 'nullable' op optionele velden gespecificeerd worden

melsk-r May 24, 2022 •

edited

Loading

melsk-r May 24, 2022 •

edited

Loading

melsk-r May 24, 2022 •

edited

Loading

melsk-r May 24, 2022 •

edited

Loading