Git Product home page Git Product logo

regels-bij-activiteiten's Introduction

Regels bij activiteiten

lint oas generate sdks generate postman collection

Deze API is relevant bij uitvoering van de Omgevingswet, i.h.b. bij het opstellen en onderhouden van zgn. toepasbare regels. Het verschaft de toepasbare regelmaker actuele informatie over de juridische regels en bijbehorende werkingsgebieden en activiteiten waarvoor toepasbare regels opgesteld of aangepast gaan worden.
De API maakt het mogelijk om gegevens op te vragen, bij een applicatie die invulling geeft aan de Omgevingswetbeleidcomponent, ook wel aangeduid als plansoftware, over (Omgevingswet-)activiteiten en/of (bijbehorende) juridische regels, regelteksten en locaties. Die gegevens maken deel uit van de vastlegging van omgevingsdocumenten, zoals een omgevingsplan, met genoemde applicatie. Het betreft regels en annotaties zoals die op het moment van opvragen vastgelegd zijn (in de plansoftware); er kan dus sprake zijn van nog niet vastgestelde of gepubliceerde gegevens. Het betreft dan bijvoorbeeld een beoogde wijziging van een omgevingsplan.
Beoogd gebruik is vooral het inzicht krijgen in activiteiten en bijbehorende regels en locaties door een applicatie die invulling geeft aan de Toepasbare regelscomponent, ook wel aangeduid als toepasbare regelsoftware, t.b.v. het kunnen opstellen en aanpassen van toepasbare regels.
Naast het gebruik als API is ook voorzien in het gebruik van de specificaties om bestandsuitwisseling van genoemde gegevens mogelijk te maken van plansoftware naar toepasbare regelsoftware.

Voor wie is dit van belang?

Belanghebbenden ('stakeholders') zijn ten eerste de gebruikers van plansoftware en van toepasbare regelssoftware die in samenhang juridische en toepasbare regels opstellen en beheren. Dit betreft organisaties die bevoegd zijn om omgevingsdocumenten, zoals omgevingsplannen, op te stellen: de bevoegde gezagen i.c. gemeenten, waterschappen, provincies en rijksoverheidsdepartementen, en organisaties waaraan zij het opstellen en wijzigen van die regels hebben uitbesteed, zoals (ruimtelijk) adviesburo's en rijksoverheidsorganisaties (zoals Rijkswaterstaat).
De tweede groep belanghebbenden zijn de leveranciers van plansoftware en van toepasbare regelssoftware aangezien deze software het gebruik van de API mogelijk moet maken.
Daarnaast zijn belanghebbend de koepelorganisaties van genoemde bevoegde gezagen (VNG, UvW resp. IPO) teneinde te borgen dat hun leden kunnen beschikken over de mogelijkheden die deze API beoogd te bieden.
Tot slot is de VNG tevens belanghebbende als beheerder van de API namens genoemde koepelorganisaties.

Positie in GEMMA

De API ontsluit het register dat beheerd wordt met de (referentiecomponent) Omgevingswetbeleidcomponent v.w.b. activiteiten en daarbij behorende regels. Ofschoon elke applicatie gebruik kan maken van deze API is het gebruik daarvan gericht op de (referentiecomponent) Toepasbare regelscomponent. Beide componenten zijn uitgewerkt in de GEMMA-deelarchitectuur 'Gemeentelijke applicatie-architectuur Omgevingswet'.

Compliancy cq. conformiteit

Deze standaard is officieel gepubliceerd als versie 1.0 en is kaderstellend voor de bedoelde informatie-uitwisseling. Onderkend wordt dat er nog geen ervaring is met het gebruik van deze standaard en het uitvoeren van de Omgevingswet met deze en andere standaarden nog volop in ontwikkeling is. Voortschrijdend inzicht en praktijkervaringen worden in volgende versies verwerkt zoals dat bij het beheer van standaarden gebruikelijk is.
Voor het voldoen van applicaties aan deze versie van de standaard betekent dit het volgende.
Een applicatie ('plansoftware') die invulling geeft aan de Omgevingswetbeleidcomponent is in staat om als provider de API te ondersteunen en/of conform de API-specificaties een bestand te exporteren (t.b.v. bestandsuitwisseling) dan wel een daaraan gelijkwaardige leverancierseigen oplossing te bieden voor bestandsexport mits daarbij de software-keuzes van afnemers gerespecteerd worden.
Een applicatie ('toepasbare regelsoftware') die invulling geeft aan de Toepasbare regelscomponent is in staat om als consumer de API te ondersteunen en/of een bestand te importeren dat conform de API-specificaties is ingericht (i.v.m. bestandsuitwisseling) dan wel een gelijkwaardige leverancierseigen oplossing te bieden voor bestandsimport mits daarbij de software-keuzes van afnemers gerespecteerd worden.
Dus, als de leverancier de standaard als provider of consumer nog niet ondersteunt en nog geen leverancierseigen oplossing kan bieden voor de door de klant gebruikte te koppelen consumer- resp. provider-software, dan dient ze koppeling met die software mogelijk te maken door het alsnog gaan ondersteunen van de standaard als provider resp. consumer dan wel door het alsnog bieden van een leverancierseigen oplossing voor bestandsuitwisseling met die software.
Deze compliancy-afspraken waarborgen dat een hierboven, als eerste, genoemde belanghebbende haar eigen keuzes kan maken voor plansoftware en voor toepasbare regelsoftware waarbij interoperabiliteit daartussen gegarandeerd is. Het waarborgt verder dat software-leveranciers vooralsnog met technisch relatief eenvoudige oplossingen in interoperabiliteit kunnen voorzien wat onevenredige investeringen in software-ontwikkeling voorkomt gezien de beperkte mate van volwassenheid waarin het Omgevingswetdomein zich nog bevindt.

Toelichting op bestandsuitwisseling

In de bestanden openapi.json en openapi_draft4.json zijn twee (functioneel gelijke) varianten van het json-schema te vinden. Dit kan toegepast worden bij bestandsuitwisseling. In deze bestanden komen de hal-specifieke componenten uit openapi.yaml niet voor. Bij bestandsuitwisseling maken we in tegenstelling tot berichtuitwisseling dus geen gebruik van de hal standaard.

Zonder selectie resulteert het opvragen als bestand in het opnemen van alle regelteksten en bijbehorende annotaties (locaties, 'juridische regels voor iedereen', activiteiten e.d. zoals beheerd in de plansoftware) of bijvoorbeeld alle locaties. Selectie van de te verkrijgen gegevens is echter wel mogelijk:

  • de regelteksten en bijbehorende annotaties van een specifiek omgevingsdocument;
  • de regelteksten en bijbehorende annotaties van één of meer activiteiten;
  • de regelteksten en bijbehorende annotaties van een specifiek werkpakket (element van regeltekst).

Default worden alle regelteksten, ook die vervallen zijn, in het bestand opgenomen. Geselecteerd kan worden dat alleen niet-vervallen regelteksten opgenomen worden.

Voor de inhoud van een dergelijk bestand gelden enkele aanvullende afspraken:

  • Van een activiteit die deel uitmaakt van de selectie (van gewenste gegevens) worden tevens de bovenliggende activiteit(en) met bijbehorende 'juridische regels (voor iedereen)' en regelteksten geleverd. Dit gaat tot aan de (bovenliggende landelijke) activiteit op het tweede niveau in de functionele structuur (zoals "nl.imow-mnre1034.activiteit.ActInOmgevingsplan").
  • Van een activiteit worden wel de Id’s van gerelateerde activiteiten geleverd maar niet de gegevens daarvan (tenzij de gerelateerde activiteit tot de selectie behoort).
  • Indien één of meer activiteiten geselecteerd zijn, dan worden van de daarbij behorende 'juridische regels voor iedereen' alleen de activiteitlocatieaanduidingen bij die activiteiten (en de bovenliggende activiteiten) geleverd, niet de activiteitlocatieaanduidingen naar andere activiteiten.
  • De als embedded gespecificeerde gegevens worden in de bestandsuitwisseling niet als embedded opgenomen. Gerelateerde gegevens worden opgenomen in de desbetreffende resources waarnaar m.b.v. de ID verwezen wordt.

Bij bestandsuitwisseling wordt het RD/Amersfoort(EPSG:28992) coördinatenstelsel gebruikt.

Zie ter illustratie van één en ander het voorbeeldbestand.

Privacy en Security

De gegevens die middels deze API worden uitgewisseld zijn niet privacygevoelig. Geen van de gegevens die met deze API worden uitgewisseld hebben betrekking op personen of kunnen naar personen herleid worden.

Aangezien deze API binnengemeentelijk berichtenverkeer van niet privacygevoelige gegevens betreft worden er geen aanvullende security eisen gesteld.

Documentatie

Bronnen

Contactpersonen:

Licentie

Copyright © VNG Realisatie 2018 Licensed under the EUPL

regels-bij-activiteiten's People

Contributors

arjankloosterboer avatar johanboer avatar melsk-r avatar

Stargazers

 avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar

Forkers

johanboer melsk-r

regels-bij-activiteiten's Issues

Toelichting van 'werkpakketCode' in 'regeltekst' is niet correct

Een deel van de toelichting van het attribuut 'werkppakketCode' in 'regeltekst' is verloren gegaan. Het bevat nu alleen de volgende tekst:

Een unieke aanduiding van de verzameling samenhangende activiteiten gericht op het publiceren van een nieuwe versie van een omgevingsdocument.

Er kunnen tegelijkertijd meerdere trajecten gaande zijn waarin bijvoorbeeld een omgevingsplan gewijzigd wordt, die elk leiden tot een apart te publiceren nieuwe versie van het omgevingsplan. De werkpakketcode biedt de mogelijkheid om de regelteksten te m

API-specificatie voldoende duidelijk voor bestandsuitwisseling?

We hebben destijds besproken dat elke leverancier de API minimaal ondersteunt in de vorm van bestandsuitwisseling (kunnen leveren dan wel verwerken van een bestand met gegevens volgens de structuur van de API). Is het voldoende duidelijk hoe de API-specificatie toegepast moet worden als je de gegevens in een bestand wil uitwisselen? Welke additionele afspraken, richtlijnen of requirements zijn hiervoor nog nodig? Bijv. characterset?

Activiteitlocatieaanduiding bij Juridische regel

Deze is nu 'platgeslagen' (zie derde ontwerpbeslissing) in drie 'elementen': activiteitregelkwalificatie [0..n], gekwalificeerdelocaties [1--n?] en, tsja, waar zijn de activiteiten gebleven? Ik zie ze niet in Swagger. Wel in het UGM maar dan als relatie van JuridischeRegel. Dit is onjuist. De Activiteitlocatieaanduiding is een gegevensgroep die nul tot n keer voor komt en telkens bestaat uit één regelkwalificatie, één activiteit en één of meer locaties. Die drie horen telkens bij elkaar, in elke instantie van de gegevensgroep. Dit is nu uit elkaar getrokken waardoor bijvoorbeeld niet meer bekend is welke regelkwalificatie voor welke activiteit voor welke locaties geldt. Ook in het UGM moet dit aangepast worden.

Als DSO-stelselarchitect zou ik graag zien dat deze API zoveel mogelijk overeenkomt met de DSO-API voor het bevragen van omgevingsdocumenten

... zodat leveranciers van (plan- en vooral) toepasbare regel-software dergelijke opvraagfunctionaliteit maar één keer hoeven te ontwikkelen.
Deze vraag is door één van de stelselarchitecten gesteld in het Interbestuurlijk Architectuuroverleg (van het DSO) op 22 februari jl.

In OZON zijn de omgevingsdocumenten (waaronder omgevingsplannen) met annotaties 'opgeslagen'. Met de API “Omgevingsdocument opvragen” kan een omgevingsdocument daaruit opgevraagd worden. Qua mogelijkheden lijkt dat op de voorliggende API, waarbij de laatstgenoemde beperkt is tot een deel van de gegevens van het omgevingsdocument. Daar waar het over dezelfde gegevens gaat, zou de API-specificatie ook hetzelfde moeten zijn, tenzij er goede redenen zijn om daarvan af te wijken. Voor software-ontwikkelaars heeft dat genoemde voordelen.

Acceptatiecriteria

  • [ ]
  • [ ]

Definition of done

  • functionele specificatie
  • Open API specificatie
  • gegenereerde code
  • testgevallen
  • referentie-implementatie

test

...zodat [vul aan].

Acceptatiecriteria

  • [ ]
  • [ ]

Definition of done

  • functionele specificatie
  • Open API specificatie
  • gegenereerde code
  • testgevallen
  • referentie-implementatie

Waarom zijn locatiegroepen "plat geslagen"? Dit kan tot ernstige performance problemen leiden

Impediment

Door locatiegroepen niet te ondersteunen moeten in plaats daarvan gebruik gemaakt worden van de multi-variant van geometriën. Bij locaties die uit veel geometriën bestaan en een groot gebied beslaan leidt dit tot performance problemen. Bijvoorbeeld het Natuurnetwerk Nederland van een provincie bestaat uit gedetailleerde geometrie die de hele provincie beslaat die een omvang kan hebben in de orde van 100MB. Als zo'n locatie als multipolygon wordt geleverd dan zorgt deze grote geometrie voor performance problemem bij het tekenen en zoeken omdat deze geometrie bij iedere zoek- en tekenactie verwerkt moet worden, maakt niet uit hoever je bent ingezoomd. Door deze locatie als groep van multipolygonen aan te leveren
raak je alleen de multi-polygonen die "in beeld zijn", namelijk als je op een bepaald gebied bent ingezoomd zoals meestal het geval is.

Als leverancier wil ik graag een voorbeeldbestand hebben

... zodat ik daarmee kan testen of mijn applicatie dit goed kan verwerken of exporteren.

Deze vraag is gesteld in het koppelvlak-leveranciersoverleg van 27 januari jl. Bij voorkeur een voorbeeldbestand (van de bestandsuitwisseling o.b.v. de API) voor Gemeentestad, de STOP/TPOD-voorbeeld-gemeente van Geonovum.

Acceptatiecriteria

  • [ ]
  • [ ]

Definition of done

  • functionele specificatie
  • Open API specificatie
  • gegenereerde code
  • testgevallen
  • referentie-implementatie

De url waarden van de server beschrijving bovenin de specificatie is niet correct

De url waarden van de server beschrijving bovenin de specificatie (zie hieronder) komt niet overeen met de naam van de API.

servers:
  - description: "SwaggerHub API Auto Mocking"
    url: https://virtserver.swaggerhub.com/VNGRealisatie/api/plan_sw___toepasbare_regel_sw/v0
  - description: "Referentie-implementatie"
    url: https://www.voorbeeldgemeente.nl/api/plan_sw___toepasbare_regel_sw/v0

Juridische regel opnemen in Regeltekst

Te overwegen is om de resource JuridischeRegelsVoorIedereen als aparte resource te laten vervallen en de inhoud daarvan als embedded op te nemen in de resource Regelteksten (i.t.t. de 2e overweging in het document Ontwerpbeslissingen). De Juridische regel is dan (in de API) als het ware een gegevensgroep met een kardinalieit 1-n van de Regeltekst. In de praktijk zal een juridische regel altijd opgevraagd worden in combinatie met de bijbehorende regeltekst (een juridische regel sec verschaft onvoldoende informatie). En bijna elke regeltekst zal bestaan uit precies één juridische regel. Het onderscheiden van twee resources met eigen endpoints (operations) lijkt dan weinig efficient. Deze structuur van de API is een manier van uitdrukken van de semantiek van het conceptueel informatiemodel en legt daaraan geen beperkingen op.

Enkele array properties mogen ten onrechte leeg blijven

De properties:

  • 'gerelateerdeActiviteitIdentificaties' ('Activiteit');
  • 'omvattendeLocatieIdentificaties' ('Locatie');
  • 'normeertActiviteiten' ('JuridischeRegelVoorIedereen');
  • 'themas' ('JuridischeRegelVoorIedereen');
  • 'gerelateerdeRegeltekstIdentificaties' ('Regeltekst')

mogen leeg zijn. Ze bevatten de construct 'minItems' met de waarde 0 of ontberen deze construct.
Aangezien 0 de default waarde is zijn beide situaties aan elkaar gelijk.

Deze situatie is echter incorrect. Ik zie nl. geen redenen waarom een van deze properties aanwezig zou mogen zijn zonder een waarde te hebben.

Is er een argument om 'origineel coördinatensysteem' toch op te nemen?

Er wordt aangegeven dat men het attribute ‘origineel coördinatensysteem’ in de resource ‘locatie’ opgenomen wil hebben. Op dit moment hebben we dat nog niet opgenomen omdat het de praktijk is om dit als 'acceptCRS' en ‘contentCRS’ in de header van de berichten op te nemen. De vraag is echter of er redenen zijn waarom je dit juist toch in de content zou willen opnemen?

Welke locatie is relevant?

Het CimOW en de API kennen locaties bij meerdere objecttypen: Regeltekst en Juridische regel en bij Activiteitlocatieaanduiding van Regel voor iedereen. Het CimTR kent alleen de locatie bij een activiteit. Het laatste is per activiteit de verzameling van locaties van de Activiteitlocatieaanduidingen bij de Activiteit. Laatstgenoemde locatie-relatie lijkt dus i.i.g. noodzakelijk. Zijn de andere twee locatie-relaties ook noodzakelijk in de API? Of willen we de API generiek houden: alles er in wat in het Cim staat. En wordt per uitvoering bepaald wat daadwerkelijk opgevraagd wordt?

Naamgeving van relaties kritisch reviewen.

Hier en daar zijn door platslaan attributes elders terecht gekomen waardoor er een noodzaak was de namen te wijzigen. Ook is in de OAS3 specificatie bij relaties tussen resources niet de namen van die relaties gebruikt maar van de daaraan gekoppelde resources, echter bij meerdere relaties naar dezelfde andere resource zijn de namen gedifferentieerd. Verzoek is om de gekozen naamgeving kritisch tegen het daglicht te houden.

Omgevingsnormen met normwaarde-locaties opnemen?

Indien in een regeltekst een norm gesteld is dan kunnen de daarvoor geldende normwaarden verschillen binnen het werkingsgebied van de regeltekst. Denk bijvoorbeeld aan maximale bouwhoogten die binnen het ambtsgebied kunnen verschillen. Dergelijke normwaarden hoeven niet in de regeltekst vermeld te worden. Ze staan dan 'in de kaart' en worden in een GIO aangeleverd (in het STOP/TPOD-bestand). Een norm met dergelijke normwaarden en bijbehorende locaties zit nu niet in het informatiemodel en dus niet in de API. Toch lijkt me de locatie van een dergelijke normwaarde relevant voor toepasbare regels. Je wilt toch iets kunnen vragen als 'Bouwt u niet hoger dan 15 meter?' Die '15' is de normwaarde en geldt voor bepaalde plekken in het ambtsgebied. Op andere plekken is het 10, 20 of meer meter. Dus wil je die plekken cq. locaties weten, lijkt me.
Overigens komt dit in het CimTR niet voor. Vreemd? Of is dit meer iets voor toepasbare regelbeheer dus voor die applicatie?

Moet het atribute 'hoogte' wel opgenomen worden?

In de resource 'locatie' is het attribuut ‘hoogte’ opgenomen. De hoogte is in een aantal coördinatensystemen echter al onderdeel van dat systeem (bijv. EPSG 7415). De vraag is dus of dit attribute echt opgenomen moet worden.

Foutveroorzakende karakters in descriptions

In het SIM zit in de omschrijving van de 'gerelateerd' relatie die loopt van 'activiteit' naar 'activiteit' een karakter dat een fout veroorzaakt in de GitHub:

afbeelding

Hetzelfde geldt voor de omschrijving van de relatie 'is' die eveneens van 'activiteit' naar 'activiteit' loopt:

afbeelding

Verwijder resp. vervang deze karakters.

Procedurenummer of -aanduiding en/of status

In het overleg op 1-10-2020 is ingebracht dat ook een procedurenummer of -aanduiding meegegeven moet kunnen worden (optioneel) op het niveau van de gegevenslevering d.w.z. niet per activiteit e.d. Er moet ook op proceduregeselecteerd cq. opgevraagd kunnen worden. Dit zit m.i. nog niet in de API. Waar en hoe zou dit verwerkt moeten worden?
Ook is ingebracht dat er sprake zou moeten zijn van een "status-gegeven dat overeenkomt met een herkenbare status in de plansoftware", waarop ook geselecteerd kan worden. Zit er m.i. ook nog niet in. Is dit hetzelfde als die procedure-aanduiding? Zo nee, toevoegen, en waar dan?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.