Vanuit AVG mag een basisregistratie alleen gegevens leveren waarvoor er doelbinding is. Maar de basisregistratie kent niet de autorisaties van de gebruiker. Je wil dan niet toestaan dat een gebruiker alle gegevens opvraagt.

Voorstel is om daarom het gebruik van de fields parameter te verplichten. Analoog aan verbieden van expand=true.

N.B. Op dit moment blijken er voor StUF vraagberichten veel leveranciers scope="alles" te gebruiken (luie developers). Dit willen we m.i. niet voor de API toestaan.

##Verander tabel-entiteiten in domeinwaarden (discussie 24/9 fieldlab).

Schema componenten voor tabelentiteit en enumeraties krijgen vaste extensie
Schema componenten voor tabel-entiteiten en enumeraties krijgen extensie "_tabel" en "_enum".

Ratio
Er kunnen gegevensgroepen, tabel-entiteiten en enumeraties zijn met dezelfde naam. Bijvoorbeeld gegevensgroep Nationaliteit bevat een tabel-entiteit Nationaliteit.
Om deze schema componenten uniek en herkenbaar te maken krijgt de naam van de schemacomponent voor een tabel de suffix "_tabel" (bijvoorbeeld Nationaliteit_tabel) en krijgt de schemacomponent voor elke enumeratie de suffix "_enum" (bijvoorbeeld Geslacht_enum).

Impediment

Het gebruik van 'Append' om hiermee ook de Ouder-, Partner- en Kind-objecten direct in het resultaat terug te krijgen, leidt in het gebruik m.i. tot onnodige belasting aan provider-kant. Reken hierbij bijvoorbeeld ook mee dat deze mogelijkheid gecombineerd kan worden met het ontvangen van gegevens op een bepaalde peildatum. Dit alles in de wetenschap dat het hier gaat om (veelvuldige) bevragingen van ingeschreven personen; de BRP is immers een populaire bron.

NB. Niet duidelijk wordt in hoeverre de 'Append' doorwerkt; hoe wordt omgegaan met de 'gerelateerde van de gerelateerde'. Blijft de levering hier dan beperkt tot de identificerende gegevens?

Daarnaast gelden hier ook de privacy-regels; heeft de afnemer überhaupt wel recht tot het inzien van de gegevens van een gerelateerde persoon; valt deze binnen z'n doelbinding? Andere vraag is of het gebruik van de 'Append' zelf afgeschermd kan worden; per afnemer aan te geven wel/niet? Zoja, waar kunnen dit soort autorisaties straks worden ingeregeld? Komt hiervoor een Autorisatie-voorziening binnen NLX en wat is het bereik hiervan?

De mogelijkheid van 'eager loading' is bovendien erg verleidelijk in het gebruik. Ongeacht of deze gegevens in het proces nodig zijn, is het wel 'makkelijk' om deze direct op te vragen. Ongewenst gebruik ligt op de loer, legt groeter nadruk op logging&handhaving van de privacy-regels.

Mijn advies is om de implementatie op dit punt eenvoudig te houden en de verleiding tot ongewenst gebruik te voorkomen door de 'Expand' niet aan te bieden en alleen 'lazy loading' van gerelateerden toe te passen. Als afnemer ontvang je (voor zover geautoriseerd) alleen de identificerende gegevens van een gerelateerde. Indien de detailgegevens van een gerelateerde noodzakelijk zijn voor de afhandeling van een taak of proces, dan de API voor deze gerelateerde ook aan te roepen.

[assign aan ..., voeg label 'impediment' toe, kies bij 'projects' voor "organisatie en impediments"]

Voor historie zou ik graag willen:

• Dat deze zo veel mogelijk aansluit op de resourcedefinitie, zodat de resource én de historie daarin herkenbaar is
• Deze zo eenvoudig mogelijk te gebruiken is

Ik wil daarom voorstellen dat we relevante historievelden standaard in de resource opnemen. Dus ook bij de actuele opvraging wordt dan de begindatum en einddatum opgenomen.
Ook zou ik willen dat we de "van" en "tot en met" attributen consequent dezelfde naam geven. Dit maakt de selectie ook duidelijker, omdat de query parameter dan dezelfde naam heeft als het attribuut waarop de selectie wordt gedaan.

We hebben nu vier plekken met historie: verblijfsplaats, partner, verblijfstitel en bewoners.
Verblijfsplaats en verblijfstitel zijn gegevensgroepen. We kunnen de historie-attributen in deze gegevensgroepen opnemen.
Partner is een relatieklasse "partnerschap", waarin bijvoorbeeld al de soort relatie (huwelijk of geregistreerd partnerschap) staat. Hieraan kunnen we ook de historie-attributen toevoegen.

De de gegevensgroepen (verblijfsplaats en verblijfstitel) worden in het historie-antwoord meerdere keren opgenomen (één per historisch voorkomen), bijvoorbeeld:
"verblijfsplaats" : [
{
"geldigVan": "1996-10-03",
"geldigTotEnMet": "2004-10-31",
"postcode": "1234AA",
"huisnummer": 10
},
{
"geldigVan": "2004-11-01",
"postcode": "5679XX",
"geldigTotEnMet": null,
"huisnummer": 20
} ]

Hiermee is het antwoord dus een "gewone" ingeschrevennatuurlijkpersoon, met alleen het verblijfsadres een aantal keer herhaald.

Vraag hierbij is hoe om te gaan met de nummeraanduiding. Ik stel voor deze hier ook op te nemen in de gegevensgroep. Alternatief zou zijn een resource "bewoning" te maken waarin alleen de begin- en einddatum van de bewoning zit (en de relatie naar de nummeraanduiding).

In de ingeschreven natuurlijk persoon zit een element gemeenteVanInschrijving, dat gedefinieerd is als N4. Dit moet gevuld worden met de gemeentecode.

Vanuit linked data (HATEOAS) geredeneerd is een gemeente een resource en moet (kan je redeneren dat) deze geïdentificeerd worden met een uri.

Wat doen we hier? Opnemen als N4 (conform informatiemodel) of opnemen als uri? En als het een uri is, dan opnemen als relatie (in JSON HAL element _links) of als "normaal" element?

In de informatiemodellen (zoals RSGB) zijn sommige attributen verplicht. Hier betekent dit dat dit attribuut er altijd moet zijn. Bijvoorbeeld een ingeschreven natuurlijk persoon heeft altijd een naam.

Betekent dit dat deze attributen ook verplicht moeten zijn in de response op GET /ingeschrevennatuurlijkpersonen?

Ratio voor het verplichten van elementen: de consumer kan er zeker van zijn dat het element bestaat en een waarde heeft
Ratio voor niet verplichten: we moeten dan zeker zijn dat er in de registratie ook daadwerkelijk altijd een waarde is. Bericht niet onnodig restricten

In hoeverre willen we inverse relaties opnemen. De ingeschreven persoon kan eigenaar zijn van een maatschappelijke activiteit. Ook de relaties "is zakelijk gerechtigde van" en "heeft als voornaamste zakelijk gerechtigde" bestaan nu. De laatste 2 zijn volgens mij BRK-elaties die onbderhouden worden door het kadaster (en dus niet opgenomen zouden moeten worden. De eerste (is eigenaar van) is een NHR-relatie die onderhouden wordt door de KvK.
De "is functionaris van" relatie wordt volgens mij ook onderhouden door het NHR.

Vooralsnog neem ik deze relaties niet op en ik denk dat we hier een expliciete design decision aan moeten weiden.

Impediment

Hoe kan een Reisdocument en een Verblijfsplaats worden opgenomen als linked element als het geen eigen endpoint (path) heeft?

Impediment

In de functionele specificaties lees ik geen inperkingen op het gebruik van het zoeken op eigenschappen van een persoon. Ik lees wel iets over het beperken van het aantal zoekresultaten per zoekvraag in combinatie met de mogelijkheid tot pagineren.

Dit zet de deur wagenwijd open om te gaan 'rechercheren' ('ik zoek iets, maar weet niet precies wat') of de bron via de Bevraging-API 'leeg te trekken'? Lijkt me beide ongewenst in het geval van het bevragen van ingeschreven personen.

Dit nog afgezien van eventuele performance-vraagstukken; zeker als ik lees dat 'Standaard alle attributen van een persoon in het antwoord worden terug gegeven' en ook de toepassing van de 'Append' mogelijk lijkt.

In plaats hiervan zou ik volgende willen voorstellen:

1. Indien het aantal zoekresultaten de limiet overschrijdt, geen zoekresultaten terug geven maar de afnemer dwingen om gerichtere zoekcriteria op te geven.
2. De toepassing van zoekcriteria te sturen door hier bedrijfsregels op te zetten; alleen zoeken op 'Ja&' niet toestaan. Dit bv. altijd te combineren met een geboortedatum of postcode/huisnummer.
3. De mogelijkheid van Pagineren niet te ondersteunen.

Dit alles met in het achterhoofd dat dit een Bevraging-API betreft gericht op het ondersteunen van een afnemers bij het uitvoeren van een specifieke taak. En dit geen 'Verzamel-API' of 'Rechercheer'-API is. Als bv. aan deze laatste behoefte bestaat bij beperkt aantal afnemers, dan zou ik hiervoor een andere API maken. Houd de Bevraging-API zo simpel en toegepast mogelijk.

NB. Zelfde vraagstuk hebben we ondervonden bij Operatie BRP. Indien afnemers behoefte hebben aan massale levering van persoonsgegevens, dan deze te leveren via andere methode dan deze bevraging-API (bv. selectie).

M.n. bij gegevensgroepen zijn er een aantal erg lange namen van attributen in het RSGB. Bijvoorbeeld verblijfadresIngeschrevenNatuurlijkPersoon, nationaliteitIngeschrevenNatuurlijkPersoon, geboorteIngeschrevenNatuurlijkPersoon, enz.

Kunnen die in de uitwisseling zo worden opgenomen, of is het wenselijk ze in te korten?

Bijvoorbeeld:
verblijfadresIngeschrevenNatuurlijkPersoon ==> verblijfadres,
nationaliteitIngeschrevenNatuurlijkPersoon ==> nationaliteit,
geboorteIngeschrevenNatuurlijkPersoon ==> geboorte,
enz.

zodat ik ook gerelateerde gegevens kan gebruiken bij de opgevraagde resource.

Op dit moment bestaat er nog geen API koppelvlak voor het ontsluiten van (bijv.) BAG gegevens. Maar vanuit BRP resources (ingeschreven natuurlijk persoon) zijn er wel relaties naar BAG gegevens. De API voor het opvragen van de ingeschreven persoon moet dus URI's kunnen samenstellen die verwijzen naar de betreffende BAG-objecten en waar deze BAG-objecten ook daadwerkelijk op te vragen zijn. Dus voor alle gelinkte resources moet er binnen het Bevragen ingeschreven personen koppelvlak (ten minste tijdelijk) een resource API beschreven (ontsloten) zijn.

Acceptatiecriteria

• Voor elke gelinkte resource is er een GET-operatie op de resource beschikbaar
• Voor een gelinkte resource buiten het BRP-domein wordt alleen het opvragen van de actuele status van de enkele resource gespecificeerd

Definition of done

• functionele specificatie
• Open API specificatie
• gegenereerde code
• testgevallen

We willen vaststellen dat uit de Open API Specificaties (we gebruiken versie 3) code kan worden gegenereerd.

Is er tooling om dit te doen voor java op basis van Open API Specificaties versie 3?

Impediment

Geslachtsaanduiding in de OAS is niet verplicht maar de enum bevat "onbekend". Mij is onduidelijk wat het verschil is tussen een lege waarde (het attribuut is immers niet verplicht) en de waarde "onbekend".

We hebben nu als wildcard karakter % beschreven, zoals dat in RSGB-bevragingen 1.0 stond.
In de DSO API strategie staat dat voor vrije tekst zoeken * en ? gebruikt worden.

Beter om API strategie te volgen, ook al gaat het hier niet om vrije tekst zoeken (elastic/fuzzy search)

Dan ook ondersteunen ? (één enkel willekeurig karakter)

Burgerservicenummer is niet uniek. Sommige burgerservicenummers zijn dubbel uitgegeven. Blijkt ook uit testset van GBA waarin een burgerservicenummer twee keer voorkomt voor verschillende personen.

Dan kan het burgerservicenummer ook niet de identifier zijn voor een enkele persoon.

Dus moet endpoint /ingeschrevennatuurlijkpersonen/{burgerservicenummer} worden gewijzigd.

Voorstel hiervoor uuid te gebruiken.

Dit wordt in API strategie ook als best practice aanbevolen:

UUID’s
Het wordt aanbevolen om voor resources die een vertrouwelijk karakter hebben het concept van een UUID (Universally-Unique IDentifier) te gebruiken.

Dan wordt endpoint /ingeschrevennatuurlijkpersonen/{uuid}

We moeten dan wel nadenken hoe dit voor clients moet werken. Bijvoorbeeld een app die op vanuit van digid het burgerservicenummer wil gebruiken om de gegevens van de ingelogde persoon te tonen. Hiervoor moet dan de zoekfunctie gebruikt worden. Maar wellicht wil je niet toestaan dat een burger de zoekfunctie voor personen gebruikt en alleen maar één persoon terug mag krijgen?

Impediment

Als INP wil ik ouders kunnen hebben (en kinderen) die niet persé zijn ingeschreven. Op dit moment kan een INP alleen INP als ouders en kinderen hebben.

...zodat we voldoen aan wettelijke eisen.

Acceptatiecriteria

• In de API specificaties is beschreven dat de provider alleen gegevens terug mag geven als er autorisatie is voor de resource
• In de API specificaties is beschreven dat de provider alleen voorkomens van de resource mag teruggeven waar de gebruiker voor geautoriseerd is
• In de API specificaties is beschreven dat de provider alleen properties terug mag geven in het antwoord waar de gebruiker voor geautoriseerd is

Definition of done

• functionele specificatie
• Open API specificatie
• gegenereerde code
• testgevallen

...zodat ik kan zien welke personen gedurende welke periode op een verblijfsadres zijn/waren ingeschreven.

Acceptatiecriteria

• consumer moet kunnen kiezen om wel of geen overleden personen in het antwoord terug te krijgen
• consumer moet periode van tot en met op kunnen geven

Definition of done

• functionele specificatie
• Open API specificatie
• gegenereerde code
• testgevallen

Het verblijfadres van een ingeschreven natuurlijk persoon is in het RSGB gemodelleerd als gegevensgroep met twee attributen (adresherkomst en locatiebeschrijving) plus relaties naar de nummeraanduiding, woonplaats en naar ligplaatsen/standplaatsen/verblijfsobjecten.

In json HAL levert dat een complexe constructie op met _links en _embedded van de relaties binnen de groep verblijfsadres.

Er zijn hiervoor verschillende opties, zoals het platslaan van de groepsattributen (adresherkomst en locatiebeschrijving) in de relaties, of door verblijfsadres te beschouwen als nested resource.

Voor de verblijfsplaats van een ingeschreven persoon zijn er relaties naar nummeraanduiding, standplaats, ligplaats, verblijfsobject, enz. Standplaats, ligplaats, verblijfsobject zijn zelf ook weer gerelateerd aan een nummeraanduiding. In het projectoverleg is opgemerkt dat er in feite alleen/vooral behoefte is aan de nummeraanduiding en het vermoeden dat dit ook alleen zo in GBA zit. Wijkt RSGB hier af van GBA? Dus hoe zit dit in LO GBA?

...zodat ik de gegevens van een persoon kan vinden.

Acceptatiecriteria

• Het is mogelijk te kiezen om ook of juist geen overleden personen terug te krijgen
• Het is mogelijk te zoeken (filteren) op de volgende eigenschappen van de persoon:
  * woonplaatsnaam
  * naamOpenbareRuimte
  * huisnummer
  * huisletter
  * huisnummertoevoeging
  * locatieaanduiding
• Bij het zoeken/filteren op naamOpenbareRuimte mag een wildcard worden gebruikt

Definition of done

• functionele specificatie
• Open API specificatie
• gegenereerde code
• testgevallen

Impediment

Hij parsed niet = Invalide YAML. Ook zie ik een hoop dubbellingen.

Zie: http://rebilly.github.io/ReDoc/?url=https://github.com/VNG-Realisatie/Bevragingen-ingeschreven-personen/blob/master/api-specificatie/BRPB1.0.yaml

...zodat ik mijn burgers op de juiste wijze kan aanspreken in correspondentie.

Oplossing: We voegen een veld "aanschrijfwijze" toe aan de resource ingeschrevenNatuurlijkPersoon. In dit veld wordt de naam samengesteld op basis van aanduidingAanschrijving, de naam van de persoon (incl. adelijke titel enz.) en de naam van de partner.

Het algoritme voor het samenstellen moet worden beschreven in de API specificaties.

Zie ook betreffende beslissing in e design decisions

Acceptatiecriteria

• De resource /ingeschrevennatuurlijkpersonen bevat een property "aanschrijfwijze"
• Bij deze property is beschreven hoe het wordt samengesteld uit de verschillende properties van de persoon en de partner.
• Properties van de persoon die niet meer relevant zijn, omdat die alleen gebruikt worden voor de aanschrijfwijze, worden uit het antwoord voor zoeken gehaald.

Definition of done

• functionele specificatie
• Open API specificatie
• gegenereerde code
• testgevallen

...zodat de leefwereld leidend wordt in plaats van de administratieve werkelijkheid.

Acceptatiecriteria

• [ ]
• [ ]

Definition of done

• functionele specificatie
• Open API specificatie
• gegenereerde code
• testgevallen

Er kunnen op twee manieren onvolledige datums nodig zijn:

1. Bij het zoeken (query parameter in de request url)
2. In het antwoord

In RSGB-bevragingen v1.0 wordt hier op twee verschillende manieren mee omgegaan:

1. in de query parameter is het één string met format 'dd-mm-jjjj', 'mm-jjjj' of 'jjjj'.
2. in het antwoord is het een gegevensgroep met drie elementen dag, maand en jaar

Bij RSGB-bevragingen wordt de keuze echter niet beschreven bij design decisions, maar dit zijn wel keuzes die verantwoord moeten worden.

Ik zou er voor willen pleiten om één consistente oplossing te kiezen voor beide situaties.
Ik zou ook willen pleiten om meer aan te sluiten op het "normale" datumformaat, dus niet 'dd-mm-jjjj', maar 'jjjj-mm-dd'

Aan de hand van #36 is gebleken dat relatie informatie nodig is voor "NP heeft als partner NP". Denk dat dit voor alle relaties gaat gelden. Volgens hoort dit ook zo volgens het IM.

...zodat ik deze gegevens kan gebruiken.

Acceptatiecriteria

• De persoon waarvan gegevens worden geraadpleegd kan worden geselecteerd op basis van het burgerservicenummer
• Het is mogelijk de verblijfsplaatshistorie van de persoon te raadplegen
• Het is mogelijk de partnerhistorie van de persoon te raadplegen
• Het is mogelijk de verblijfstitelhistorie van de persoon te raadplegen

Definition of done

• functionele specificatie
• Open API specificatie
• gegenereerde code
• testgevallen

...zodat ik een werkend voorbeeld kan zien en zelf kan opzetten.

Acceptatiecriteria

• Implementatie gebruikt de OAS uit Imvertor voor zover mogelijk
• Implementatie is publiekelijk beschikbaar

Definition of done

• Code op Github
• Code uitgerold op omgeving t.b.v. publieke bereikbaarheid

Impediment

Het IM lijkt te hinten op maximaal 1 verblijfsplaats (als dit hetzelfde is als Verblijfsadres). De OAS geeft echter aan dat het veld "verblijfsplaatsen" heet, echter is er toch maar 1 object mogelijk.

https://github.com/VNG-Realisatie/Bevragingen-ingeschreven-personen/blob/master/api-specificatie/BRPB1.0.yaml#L918

        verblijfsplaatsen:
          type: "object"

...zodat ik gerichter kan zoeken, en de kans minder groot is dat mijn zoekvraag niet wordt ondersteund.

Acceptatiecriteria

• Deze mogelijkheid wordt geboden bij zoeken op persoonskenmerken.

Definition of done

• functionele specificatie
• Open API specificatie
• gegenereerde code
• testgevallen

...zodat de gegevens van een persoon kan vinden.

Acceptatiecriteria

• Het is mogelijk te kiezen om ook of juist geen overleden personen terug te krijgen
• Het is mogelijk te kiezen om ook of juist geen niet-ingezeten terug te krijgen
• Het is mogelijk te zoeken (filteren) op de volgende eigenschappen van de persoon:
  * geslachtsnaam
  * geboortedatum
  * voornamen
  * voorvoegselGeslachtsnaam
  * geslachtsaanduiding
  * geboorteplaats
• Bij het zoeken/filteren op geslachtsnaam mag een wildcard worden gebruikt
• Bij het zoeken/filteren op voornamen mag een wildcard worden gebruikt
• Bij het zoeken/filteren op geboortedatum mag een onvolledige datum worden gebruikt

Definition of done

• functionele specificatie
• Open API specificatie
• gegenereerde code
• testgevallen

... (voordat deze in master staat) zodat ik hier niet tegen aan loop als ik wil gaan ontwikkelen.

Nu is parameter inclusiefnietingezetenen opgenomen bij het zoeken op naam. Default worden alleen ingezetenen gezocht.
Ook is parameter gemeenteVanInschrijving opgenomen. Hiermee kan alleen binnen de eigen gemeente worden gezocht. Daarmee kan evt. ook worden gezocht op specifiek RNI (gemeenteVanInschrijving=1999)

Is dit de gewenste oplossing voor de functionele vraag? Is het dus nodig om te kunnen kiezen tussen:

• Zoeken van alleen ingezetenen van de eigen gemeente
• Zoeken van ingezetenen in de eigen en andere gemeenten, maar geen niet-ingezetenen
• Zoeken van alle ingeschreven personen incl. niet-ingezetenen

Is het niet voldoende om te kunnen:

• Zoeken van alleen ingezetenen van de eigen gemeente
• Zoeken in alle ingeschreven personen (ingezetenen en niet-ingezetenen)

Hoe gaan we in z'n algemeenheid om met personen die een indicatie geheimhouding hebben?

N.a.v. #67 (comment)

Impediment

Specificatie op dit moment kan maximaal 1 "ouders" aan van een INP, als object i.p.v. een lijst van ouders.

https://github.com/VNG-Realisatie/Bevragingen-ingeschreven-personen/blob/master/api-specificatie/BRPB1.0.yaml#L910

        ouders:
          type: "object"
          description: "De ingezetene, zijnde de ouder, waarnaar de KIND-OUDER-RELATIE\
            \ verwijst"
          properties:
            href:
              type: "string"
              format: "uri"

Entiteittype met complex datatype als id. Hoe deze resource benaderen (uri opbouw)? Uuid? Of concatenatie van subelementen?

...zodat ik weet wat ik hiermee kan bereiken, welke applicaties deze API moeten kunnen gebruiken, hoe dit past in mijn architectuur, wat ik aan infrastructuur moet organiseren, enz.

Doelgroepen:

• informatiemanager (gemeente)
• architect (gemeente)
• inkoper (gemeente)
• product manager (leverancier)

Activiteiten:

• per doelgroep informatiebehoefte bepalen
• bepalen publicatievorm (bijv. gemmaonline pagina's, pdf, GitHub md pagina's, ...
• afstemmen "sjabloon" met andere API projecten (Gemma zaken)
• schrijven functionele documentatie
• review

Acceptatiecriteria
TODO: uitzoeken bij de doelgroepen wat precies hun informatiebehoefte is

• [ ]
• [ ]

Definition of done

• functionele specificatie

Nu is parameter inclusiefnietingezetenen opgenomen bij het zoeken op naam. Default worden alleen ingezetenen gezocht.
Ook is parameter gemeenteVanInschrijving opgenomen. Hiermee kan alleen binnen de eigen gemeente worden gezocht.
Is dit de gewenste oplossing voor de functionele vraag? Is het dus nodig om te kunnen kiezen tussen:

1. Zoeken van alleen ingezetenen van de eigen gemeente
2. Zoeken van ingezetenen in de eigen en andere gemeenten, maar geen niet-ingezetenen
3. Zoeken van alle ingeschreven personen incl. niet-ingezetenen

Volgens de OpenAPI spec is het aangeraden om de API spec documenten openapi.yaml en/of openapi.json te noemen, in plaats van de huidige BRPB1.0.yaml

Concreet geven we dat bij de ZDS services invulling in de papieren standaard. Aanleiding hiertoe is de (generieke) client die op basis van een resource URL de API spec opvraagt die geserveerd wordt om vervolgens operaties op de API uit te kunnen voeren.

Vraag

Op dit moment staat de OAS toe dat er meer dan 1 partner is van een INP. Klopt dit?

Impediment

Verblijfsplaats is niet verplicht maar datumBeginGeldigheidVerblijfplaats wel. Klinkt inconsistent.

...zodat ik minimaal de verplichte gegevens terug krijg.

Ergo, anders is een valide antwoord, een leeg antwoord. Tevens is het vrij gebruikelijk om verplichte attributen op response niveau gelijk te houden aan die op (mogelijk) schrijf niveau (=1 definitie van een resource ~ Objecttype)

Betreft:
https://github.com/VNG-Realisatie/Bevragingen-ingeschreven-personen/blob/master/docs/design_decisions.md#de-response-heeft-geen-verplichte-properties

De response heeft geen verplichte properties
Alle properties in de response worden in de Open API Specificaties gedefinieerd als optioneel, ook wanneer de betreffende attributen in het informatiemodel verplicht zijn.

Ratio De hoeveelheid businesslogica in interface beperken. Zorgen dat zoveel mogelijk antwoord gegeven kan worden, ook wanneer een verwachte property geen waarde heeft. Het alternatief, het opnemen van de reden van geen waarde (zoals StUF:noValue) is dan niet nodig, wat het gebruik van de API eenvoudiger maakt.

Wat van deze attributen getoond wordt aan een eventuele gebruikersinterface staat hier los van. Een consistente lees/schrijf interface is veel waardevoller voor een ontwikkelaar (we gooien immers een "State" -S van REST- over de lijn).

In RSGB schijnt het briefadres te zijn gemodelleerd als correspondentieadres. Dit wordt verwarrend gevonden, omdat correspondentieadres ook een plusgegeven/kerngegeven kan zijn. Er is in de berichtuitwisseling wel behoefte aan het briefadres, niet aan een niet-authentiek correspondentieadres dat bijvoorbeeld in een procesapplicatie kan zijn opgeslagen. Hoe kunnen we hiermee omgaan?

Er is nu nog geen attribuut in onderzoek opgenomen in de API-specificaties.

Hoe hiermee omgaan?

N.a.v. #67 (comment)

...zodat duidelijk is waarom een issue gesloten wordt.

Nu is er een lijst met issues en wordt er af en toe een willekeurige set aan changes in de vorm van een nieuw OAS bestandje toegevoegd. Het is dan compleet onduidelijk welke wijzigingen zijn gedaan en waarom deze zijn gedaan. Ik kan echt de helft van de wijzigingen niet relateren aan bestaande issues...

Originally posted by @CathyDingemanse in https://github.com/VNG-Realisatie/Bevragingen-ingeschreven-personen/issue_comments#issuecomment-428562691

Hieronder de opmerkingen van Frank, Johan en Joeri

Impediment

https://github.com/VNG-Realisatie/Bevragingen-ingeschreven-personen/blob/master/api-specificatie/BRPB1.0.yaml#L683

        datumEindeGeldigheidVerblijfstiel:
          type: "string"
          title: "Datum einde geldigheid verblijfstiel"
          description: "Einde geldigheid van de verblijfstitel"

"[...] tiel" moet "titel" zijn.

...zodat resources eenduidig worden ontsloten.

Concreet is dit issue gemaakt door deze ontwerp keuze:

Er wordt per combinatie van query parameters voor het zoeken van ingeschreven natuurlijk personen een endpoint gedefineerd. Bijvoorbeeld "/ingeschrevennatuurlijkpersonenpostcode" en "/ingeschrevennatuurlijkpersonengeslachtsnaam".

Als ik het goed begrijp krijg je dus:

/ingeschrevennatuurlijkpersonenpostcode/?postcode=1234AA
/ingeschrevennatuurlijkpersonengeslachtsnaam/?geslachtsachternaam=Janssen

Dit lijkt mij een onwenselijke situatie. Er ontstaan zo 2 endpoints, die dezelfde resource ontsluiten, waardoor een specifiek object ook middels verschillende endpoints opvraagbaar zijn en identificeerbaar zijn. Tevens krijg je dus een oneindige lijst aan endpoints die bepaalde query parameters toe staan, die allemaal dezelfde resource terug geven? Waarom hebben we dan nog query parameters?

Volgens mij moet je ten alle tijde 1 endpoint hebben per resource:

/ingeschrevennatuurlijkpersonen/?<query params>

En mocht het voor business logica nodig zijn om slechts bepaalde query parameters, of combinatie van query parameters, toe te staan, dan moet hier (op de query parameters) gewoon validatie op komen. Er komt dan een foutmelding als je een verkeerde combinatie maakt, en de mogelijke query parameters zijn netjes gedocumenteerd.

Het klopt overigens dat het niet mogelijk is in de OAS programmatisch vast te leggen welke combinaties mogelijk zijn en welke niet. Dit komt neer op een stukje documentatie. Voer voor een andere discussie is wellicht waarom je slechts bepaalde combinaties wil toe staan.

zodat ik de gegevens van een persoon kan vinden..

Acceptatiecriteria

• Het is mogelijk te kiezen om ook of juist geen overleden personen terug te krijgen
• Het is mogelijk te zoeken (filteren) op de volgende eigenschappen van de persoon:
  * postcode
  * huisnummer
  * huisletter
  * huisnummertoevoeging
  * locatieaanduiding
  * periode (van, tot en met)

Definition of done

• functionele specificatie
• Open API specificatie
• gegenereerde code
• testgevallen

We hebben nu niet-consistente manier van zoeken op een woonplaats:
Geboorteplaats == string (naam van de plaats)
Gemeentevaninschrijving == integer (gemeentecode)

In het geval van geboorteplaats is dat noodzakelijk, want dat kan ook een plaats buiten Nederland zijn.

Accepteren we dit verschil? Of willen we dit gelijktrekken? Wil je dus zoeken op Gemeentevaninschrijving als string of als code?