brp-api / haal-centraal-brp-bevragen Goto Github PK
View Code? Open in Web Editor NEWHome Page: https://brp-api.github.io/Haal-Centraal-BRP-bevragen/
License: Other
Home Page: https://brp-api.github.io/Haal-Centraal-BRP-bevragen/
License: Other
Hoe gaan we in z'n algemeenheid om met personen die een indicatie geheimhouding hebben?
N.a.v. #67 (comment)
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
Er is nu nog geen attribuut in onderzoek opgenomen in de API-specificaties.
Hoe hiermee omgaan?
N.a.v. #67 (comment)
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?
... (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.
Is dit de gewenste oplossing voor de functionele vraag? Is het dus nodig om te kunnen kiezen tussen:
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:
Is het niet voldoende om te kunnen:
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.
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.
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?
...zodat ik kan zien welke personen gedurende welke periode op een verblijfsadres zijn/waren ingeschreven.
Acceptatiecriteria
Definition of done
Entiteittype met complex datatype als id. Hoe deze resource benaderen (uri opbouw)? Uuid? Of concatenatie van subelementen?
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.
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?
datumEindeGeldigheidVerblijfstiel:
type: "string"
title: "Datum einde geldigheid verblijfstiel"
description: "Einde geldigheid van de verblijfstitel"
"[...] tiel" moet "titel" zijn.
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?
Hoe kan een Reisdocument
en een Verblijfsplaats
worden opgenomen als linked element als het geen eigen endpoint (path) heeft?
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?
...zodat ik de gegevens van een persoon kan vinden.
Acceptatiecriteria
Definition of done
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.
...zodat de leefwereld leidend wordt in plaats van de administratieve werkelijkheid.
Acceptatiecriteria
Definition of done
Hij parsed niet = Invalide YAML. Ook zie ik een hoop dubbellingen.
...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
Definition of done
Er kunnen op twee manieren onvolledige datums nodig zijn:
In RSGB-bevragingen v1.0 wordt hier op twee verschillende manieren mee omgegaan:
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'
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.
verblijfsplaatsen:
type: "object"
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.
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 deze gegevens kan gebruiken.
Acceptatiecriteria
Definition of done
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
Definition of done
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".
...zodat ik een werkend voorbeeld kan zien en zelf kan opzetten.
Acceptatiecriteria
Definition of done
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.
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
...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)
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).
...zodat ik gerichter kan zoeken, en de kans minder groot is dat mijn zoekvraag niet wordt ondersteund.
Acceptatiecriteria
Definition of done
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"]
Verblijfsplaats
is niet verplicht maar datumBeginGeldigheidVerblijfplaats
wel. Klinkt inconsistent.
zodat ik de gegevens van een persoon kan vinden..
Acceptatiecriteria
Definition of done
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 we voldoen aan wettelijke eisen.
Acceptatiecriteria
Definition of done
Op dit moment staat de OAS toe dat er meer dan 1 partner is van een INP. Klopt dit?
...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...
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:
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).
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)
...zodat de gegevens van een persoon kan vinden.
Acceptatiecriteria
Definition of done
...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:
Activiteiten:
Acceptatiecriteria
TODO: uitzoeken bij de doelgroepen wat precies hun informatiebehoefte is
Definition of done
##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).
Specificatie op dit moment kan maximaal 1 "ouders" aan van een INP, als object i.p.v. een lijst van ouders.
ouders:
type: "object"
description: "De ingezetene, zijnde de ouder, waarnaar de KIND-OUDER-RELATIE\
\ verwijst"
properties:
href:
type: "string"
format: "uri"
...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.
Voor historie zou ik graag willen:
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).
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.