Voorstel voor verbeteren van de features #4
Replies: 4 comments 1 reply
-
|
Dit zou de aansluitdocumentatie enorm verbeteren maar ik heb wel een aantal praktische opmerkingen/vragen hierbij:
Als de insteek is om bijvoorbeeld uitsluitsel te bieden over welke autorisatievelden vereist moeten zijn om bepaalde informatieproducten te raadplegen (zoals geslacht of voorletters bij volledige naam) dan kunnen we daar misschien beter specifieke pagina's of tabellen voor maken. Daarbij komt, als zulke dingen alleen gelden voor een aantal specifieke gevallen kunnen we daar markdown files voor aanmaken zoals nu al gedaan wordt in de huidige documentatie website.
De voorkeur zal zijn om deze feature files daadwerkelijk uit te kunnen voeren en zelfs een summary daarvan te publiceren zoals we nu al doen met de features, daarvoor moeten de features die voor documentatie gebruikt moeten worden dan in de informatie-services geplaatst worden, krijgen we daarmee niet nog meer duplicate features?
|
Beta Was this translation helpful? Give feedback.
-
|
Ik heb deze discussie gestart omdat ik denk dat het goed is om nieuwe functionaliteit voor bestaande apis ook op een expressievere manier te documenteren en niet meer door te gaan op de oude manier.
Mee eens. We kunnen bijv. voor de personen api hiervoor de Haal-Centraal-BRP-bevragen repo blijven gebruiken. Daar designen we de OpenAPI specificatie van de personen api. Dus zouden we ook daar het specificeren en daarmee helder krijgen van gewenste functionaliteit uitvoeren.
Ik denk dat elke business rule moet worden gepubliceerd en op dezelfde manier moet worden gespecificeerd. Er zou geen verschil moeten worden gemaakt tussen interne en externe consumers van interne of externe apis. Ook zo'n interne requirement als het sortering verhaal heeft impact op externe consumers en zou dus ook in de externe documentatie worden opgenomen met voorbeelden.
Ik zou zeggen, ja. Ik zie nu te vaak dat het niet duidelijk is wat de impact is van een gevraagde functionaliteit. Maar dit betekent niet dat elk onderdeel van een feature file extern moet worden gepubliceerd. Bij mij gaat het erom hoe we een functionaliteit beter kunnen specificeren en de impact ervan ontdekken en als side-effect de specificatie hergebruiken als documentatie.
Feature bestanden zijn voor mij niet de enige documentatie. Sommige onderwerpen kun je beter documenteren met diagrammen |
Beta Was this translation helpful? Give feedback.
-
|
Hieronder een voorbeeld van een feature uit de brp-api-gezag repo. In deze feature komen een aantal zaken aan bod die we nog niet besproken hebben en misschien hebben julle daar ideeën over. Sommige features bevatten een flinke lap tekst bij de beschrijving van de Functionaliteit. Dat is op zichzelf geen probleem maar deze tekst bevat in sommige gevallen ook een tabel layout. Zie onderstaand voorbeeld uit Functionaliteit: 3.1 - is er sprake van een recente gebeurtenis - ontkenning
Precondities voor deze vraag:
| 1.1 Staat persoon (minderjarige) als ingezetene in de BRP? | Ja |
| 1.2 Is persoon a. minderjarig en b. niet overleden? | Ja |
| 1.3 Is minderjarige naar het buitenland geëmigreerd geweest? | Nee |
| 1.3a Is minderjarige in buitenland geboren? | Nee of geadopteerd met NL akte |
| 1.4 Uitspraak gezag aanwezig? | Ja |
Omdat de tabel hier in een stuk tekst opgenomen is en niet specifiek als datatabel is opgevoerd kan dit niet op een eenvoudige manier omgezet worden naar markdown. Waardoor deze tabel er in markdown dan erg raar uit komt te zien. Zie onderstaand voorbeeld: Precondities voor deze vraag: | 1.1 Staat persoon (minderjarige) als ingezetene in de BRP? | Ja | | 1.2 Is persoon a. minderjarig en b. niet overleden? | Ja | | 1.3 Is minderjarige naar het buitenland geëmigreerd geweest? | Nee | | 1.3a Is minderjarige in buitenland geboren? | Nee of geadopteerd met NL akte | | 1.4 Uitspraak gezag aanwezig? | Ja | Sommige onderwerpen, zoals de precondities in dit voorbeeld, kunnen we beter op een andere manier opnemen. Bijvoorbeeld door in plaats van een tabelvorm een opsomming te gebruiken. Opsommingen zien er dan zo uit: Functionaliteit: 3.1 - is er sprake van een recente gebeurtenis - ontkenning
Precondities voor deze vraag:
- 1.1 Staat persoon (minderjarige) als ingezetene in de BRP? **Ja**
- 1.2 Is persoon a. minderjarig en b. niet overleden? **Ja**
- 1.3 Is minderjarige naar het buitenland geëmigreerd geweest? **Nee**
- 1.3a Is minderjarige in buitenland geboren? **Nee of geadopteerd met NL akte**
- 1.4 Uitspraak gezag aanwezig? **Ja**Dan ziet de naar markdown geconverteerde tekst er namelijk als volgt uit: Functionaliteit: 3.1 - is er sprake van een recente gebeurtenis - ontkenningPrecondities voor deze vraag:
|
Beta Was this translation helpful? Give feedback.
-
|
Voorbeeld 5: # language: nl
Functionaliteit: 3.1 - is er sprake van een recente gebeurtenis - ontkenning
Precondities voor deze vraag:
- 1.1 Staat persoon (minderjarige) als ingezetene in de BRP? **Ja**
- 1.2 Is persoon a. minderjarig en b. niet overleden? **Ja**
- 1.3 Is minderjarige naar het buitenland geëmigreerd geweest? **Nee**
- 1.3a Is minderjarige in buitenland geboren? **Nee of geadopteerd met NL akte**
- 1.4 Uitspraak gezag aanwezig? **Ja**
Het is mogelijk dat er een uitspraak is gedaan door de rechter, maar door een recentere gebeurtenis het gezag toch weer van rechtswege is verkregen of ingetrokken (ontkenning).
Dit is (mogelijk) het geval bij de volgende gebeurtenissen: adoptie, hertrouwen of ontkenning ouderschap.
Ontkenning ouderschap omvat ontkenning:
- vaderschap (art. 1:200 en 1:201 BW) of
- moederschap (art. 1:202a en 1:202b BW) of
- nietige erkenning (art. 1:204) of
- vernietiging erkenning (art. 1:205 en 1:205a BW)
Het door het huwelijk of geregistreerd partnerschap ontstane ouderschap wordt geacht nimmer gevolg te hebben gehad (art. (1:202b in
verbinding met) art. 1:202 lid 1 BW). Door de nietigheid/vernietiging van de erkenning wordt de erkenning geacht nimmer gevolg te hebben gehad
(art. 1:206 lid 1 BW). Na ontkenning is de ouder niet meer juridisch ouder van het kind, terwijl de ouder volgens een eerdere uitspraak wel het gezag had.
Hoe te achterhalen?
- Ontkenning ouderschap/vernietiging erkenning:
- Indicatie gezag bevat de waarde ‘1’ of ‘12’ en de geslachtsnaam van die ouder komt niet voor of bevat de waarde ‘.’. of de indicatie gezag bevat de waarde ‘2’ of ‘12’
en de geslachtsnaam van die ouder komt niet voor of bevat de waarde ‘.’.
- Een ontkenning ouderschap en/of een vernietiging van een erkenning hebben altijd terugwerkende kracht en er ontstaat een ‘lege’ oudercategorie,
herkenbaar aan het ontbreken van de geslachtsnaam. Als de geslachtsnaam wel voorkomt maar de waarde ‘.’ bevat dan is (nog) niet bekend wie die ouder is.
Gebruikte velden:
- Ouder -> 02.02.40
- Geslachtsnaam van de ouder -> 03.02.40
- Indicatie gezag -> 11.32.10
- Ingangsdatum gezag -> 11.85.10
- Datum ingang familierechtelijke betrekking -> 02.62.10 en 03.62.10
Achtergrond:
Gegeven de persoon 'Nelly' met burgerservicenummer '000000012'
* is meerderjarig, niet overleden en staat niet onder curatele
En de persoon 'Johnnie' met burgerservicenummer '000000024'
* is meerderjarig, niet overleden en staat niet onder curatele
En 'Nelly' en 'Johnnie' zijn met elkaar gehuwd
En de persoon 'Kees' met burgerservicenummer '000000036'
* is ingeschreven in de BRP
* is minderjarig
* is niet geëmigreerd geweest
* is in Nederland geboren
* heeft 'Nelly' als ouder 1
* heeft 'Johnnie' als ouder 2
@gezag-api
Regel: Als vaderschap is ontkend of de erkenning is vernietigd en er was een uitspraak gezag voor die ouder, wordt het gezag van rechtswege bepaald
@gezag-api @skip-verify
Abstract Scenario: er is uitspraak gezag voor ouder 1 en ouder 2 en erkenning door ouder <ouder> is ontkend of vernietigd er is sprake van EenhoofdigOuderlijkGezag
Gegeven voor 'Kees' is een gerechtelijke uitspraak over het gezag gedaan
| indicatie gezag minderjarige (32.10) | ingangsdatum geldigheid (85.10) |
| 12 | morgen - 10 jaar |
En zijn van ouder <ouder> de volgende gegevens <soort wijziging>
| naam | waarde |
| burgerservicenummer (01.20) | |
| geslachtsnaam (02.40) | <naam ouder> |
| geboortedatum (03.10) | |
| datum ingang familierechtelijke betrekking (62.10) | |
| aktenummer (81.20) | 1AF0100 |
Als gezag wordt gezocht
| naam | waarde |
| burgerservicenummer | 000000036 |
Dan heeft de response een persoon
| naam | waarde |
| burgerservicenummer | 000000036 |
En heeft de persoon een 'gezag'
| naam | waarde |
| type | EenhoofdigOuderlijkGezag |
| minderjarige.burgerservicenummer | 000000036 |
| ouder.burgerservicenummer | <ouder bsn> |
Voorbeelden:
| ouder | naam ouder | soort wijziging | ouder bsn |
| 1 | | gewijzigd | 000000024 |
| 1 | . | gewijzigd | 000000024 |
| 1 | | gecorrigeerd | 000000024 |
| 1 | . | gecorrigeerd | 000000024 |
| 2 | | gewijzigd | 000000012 |
| 2 | . | gewijzigd | 000000012 |
| 2 | | gecorrigeerd | 000000012 |
| 2 | . | gecorrigeerd | 000000012 |
@gezag-api
Abstract Scenario: er is uitspraak gezag voogdij en erkenning door ouder 2 is ontkend of vernietigd er is sprake van Voogdij
Gegeven voor 'Kees' is een gerechtelijke uitspraak over het gezag gedaan
| indicatie gezag minderjarige (32.10) | ingangsdatum geldigheid (85.10) |
| D | morgen - 10 jaar |
En zijn van ouder <ouder> de volgende gegevens <soort wijziging>
| naam | waarde |
| burgerservicenummer (01.20) | |
| geslachtsnaam (02.40) | <naam ouder> |
| geboortedatum (03.10) | |
| datum ingang familierechtelijke betrekking (62.10) | |
| aktenummer (81.20) | 1AF0100 |
Als gezag wordt gezocht
| naam | waarde |
| burgerservicenummer | 000000036 |
Dan heeft de response een persoon
| naam | waarde |
| burgerservicenummer | 000000036 |
En heeft de persoon een 'gezag'
| naam | waarde |
| type | Voogdij |
| minderjarige.burgerservicenummer | 000000036 |
En heeft 'gezag' geen derden
Voorbeelden:
| ouder | naam ouder | soort wijziging |
| 1 | | gewijzigd |
| 1 | . | gewijzigd |
| 1 | | gecorrigeerd |
| 1 | . | gecorrigeerd |
| 2 | | gewijzigd |
| 2 | . | gewijzigd |
| 2 | | gecorrigeerd |
| 2 | . | gecorrigeerd | |
Beta Was this translation helpful? Give feedback.
-
|
Sommige feature bevatten * in de gegevenstappen om de leesbaarheid te bevorderen. Dit kunnen we overnemen bij het converteren naar markdown en hier een ingesprongen opsomming van maken. Zie onderstaand voorbeeld. Achtergrond:
Gegeven de persoon 'Nelly' met burgerservicenummer '000000012'
* is meerderjarig, niet overleden en staat niet onder curatele
En de persoon 'Johnnie' met burgerservicenummer '000000024'
* is meerderjarig, niet overleden en staat niet onder curatele
En 'Nelly' en 'Johnnie' zijn met elkaar gehuwd
En de persoon 'Kees' met burgerservicenummer '000000036'
* is ingeschreven in de BRP
* is minderjarig
* is niet geëmigreerd geweest
* is in Nederland geboren
* heeft 'Nelly' als ouder 1
* heeft 'Johnnie' als ouder 2
|
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
Voorbeeld 1:
Voorbeeld 2:
Voorbeeld 3:
Voorbeeld 4:
Beta Was this translation helpful? Give feedback.
All reactions