As a developer, I want to have standardized schema descriptions for eigenschappen

[sergei-maertens]

so that I can re-use existing tooling without having to make the conversion myself.

The Eigenschap resource in the catalogi API has a section describing the format of the property, see https://catalogi-api.vng.cloud/api/v1/schema/#operation/eigenschap_read:

{
  "url": "http://example.com",
  "naam": "string",
  "definitie": "string",
  "specificatie": {
    "groep": "string",
    "formaat": "tekst",
    "lengte": "string",
    "kardinaliteit": "str",
    "waardenverzameling": [
      "string"
    ]
  },
  "toelichting": "string",
  "zaaktype": "http://example.com"
}

The specificatie object lays out the data format, where formaat can be tekst, getal, datum or datum_tijd.

This entire specification is actually well-suited for json-schema - this is also already what is used in OpenAPI specification for this very same API.

So, my proposal is to use json-schema for the specificatie rather than the self-invented format:

{
  "specificatie": {
    "groep": "voorbeeld",
    "type": "string|number|array",
    "minLength": 1,
    "maxLength": 5,
    "minimum": 0,
    "maximum": 10,
    "enum": [
      "value1",
      "value2",
    ],
    "maxItems": 2,
    "minItems": 1,
    "items": {
      "type": "string|number",
      "format": "date|date-time"
    }
  }
}

Analysis:

• formaat becomes type, optionally having format information.
  • tekst maps to type=string
  • getal maps to type=number
  • datum maps to type=string, format=date
  • datum_tijd maps to type=string, format=date-time
• lengte is a weird one, because it seems to define an exact length and it's interpreted differently for strings/numbers etc.
  • for type=string, you get minLength and maxLength
  • for type=number, you have a number of properties at your disposal
  • for type=string, format=date|date-time - this is defined in json-schema as the ISO-8601 formats, so lengte is not relevant at all anymore
• kardinaliteit is handled by specifying the specificatie as a scalar type, or as an array type: type=array. If you specify type=array, you then specify the formaat of a single item using items. Array provides maxItems, minItems to express exact cardinality
• waardenverzameling maps directly to enum

[michielverhoef]

Ik beantwoord even in het Nederlands, er komen teveel kromme zinnen uit mijn toetsenbord als ik het in het Engels probeer ;-)

De huidige structuur is 1 op 1 overgenomen van het RGBZ/ImZTC. Dit maakt het voor Informatiemanagers en beheerders makkelijker om de OAS te snappen, het RGBZ/ImZTC is de meesten van hen wel bekend.

Op zich begrijp ik de user story en zie ik de meerwaarde. Wat we wel in het oog moeten houden is dat de informatiemodellen RGBZ en ImZTC niet technisch maar functioneel zijn. Door in een deel van de OAS een functionele structuur als technische structuur op te nemen zou dat misschien verwarrend kunnen zijn. In ieder geval neem ik dit mee naar de gebruikersgroep, dan mogen die er ook wat van vinden.

[sergei-maertens]

Foundation for Public code (waar Open Zaak dus mee werkt) & ook in Nederland algemeen geloof ik dat het uitgangspunt was om internationale standaarden te gebruiken waar mogelijk, in plaats van "zelf wat te bedenken". Dit kadert hier perfect in naar mijn mening, je hebt hier een kans om nauwer bij die principes aan te sluiten en iets "zelf bedachts" weg te halen. Het biedt daarnaast dus (inhoudelijk) de mogelijkheid om rijkere formaatdefinities te hanteren.

Het RGBZ/ImZTC als inspiratiebron lijkt me dat niet dwars te zitten.

De huidige structuur is 1 op 1 overgenomen van het RGBZ/ImZTC. Dit maakt het voor Informatiemanagers en beheerders makkelijker om de OAS te snappen, het RGBZ/ImZTC is de meesten van hen wel bekend.

Is de API specificatie nu developer first, of IM-er first? :wink:

[MNIJ]

Dit issue is een beetje oud, maar nog steeds relevant. Voor nu zullen we het in ieder geval met de huidige specificatie moeten doen. Ik loop dan wel tegen de vraag aan wat te doen met eigenschap.specificatie.lengte voor datum en datum/tijd velden.

Volgens de definitie in ImZTC moet een eigenschap van type datum de lengte 8 hebben. Dat impliceert dat bijvoorbeeld de datum van vandaag als "20220728" in de API berichten moet staan. Maar alle andere datumvelden in de ZGW zijn in het formaat "2022-07-28", wat 10 karakters is.

Hetzelfde geldt voor datum/tijd, daar schrijft ImZTC de lengte 14 voor, dus "20220728134022" terwijl ZGW normaal gesproken ISO notatie voor datum/tijd volgt, waarbij je dit zou noteren als "2022-07-28T11:40:22Z", wat 20 karakters is (let ook op het tijdverschil door tijdzone) of zelfs 24 als milliseconden ook worden meegenomen, wat wel gebruikelijk is.

@sergei-maertens , hoe gaan jullie hier mee om? Een andere datumnotatie voor deze velden dan de rest van de applicatie? Of afwijkende waarden voor eigenschap.specificatie.lengte gebruiken? Of deze lengte waarde negeren?

[sergei-maertens]

2022-07-28T09:40:22+02:00 kan ook nog - en dan red je het dus niet met 20 karakters (en dat is ook geldig volgens ISO-8601!).

Mijn visie in het algemeen over dit onderwerp is sowieso "(algemeen geaccepteerde) internationale standaarden" > "landelijke standaarden" > "maatwerk 'standaarden'".

In de praktijk ben ik niet meer betrokken bij partijen die actief eigenschappen gebruiken - we proberen eigenlijk zoveel mogelijk gerelateerde gegevens via de ZaakObject relatieklasse aan een zaak te koppelen, en hierbij gebruik te maken van de Objecten API standaard. Deze volgt wel json-schema (widely accepted/popular ;) ) waarbij ISO-8601 gebruikt wordt voor datums/tijden/durations.

Echter, in Open Zaak passen we dezelfde validaties toe van de referentie-implementatie:

• datum: lengte 8
• datumtijd: lengte 14

Daar wordt dus (helaas) ImZTC gevolgd.

[MNIJ]

Dank je, dat vermoedde ik al.

Wij hebben Eigenschappen wel geïmplementeerd in onze ZTC en ZRC implementatie, maar tot nu toe hebben we ze niet daadwerkelijk toegepast in onze afhandelcomponenten. Daar gaan we waarschijnlijk niet geheel aan ontkomen en zullen ons dus ook maar met lichte tegenzin houden aan deze specificaties.

[sergei-maertens]

@HenriKorver @hdksi - we zijn weer een stukje eigenschappen aan het implementeren en hikken tegen deze issues aan. Staat dit nog ergens op de roadmap?

[HenriKorver]

@sergei-maertens: Nee, dit ticket heeft helaas geen urgentie, mede doordat de doorontwikkeling van de referentie-implementatie gepauzeerd is. Alleen blokkerende issues en bugs worden nog behandeld. Het is inderdaad niet fraai dat datum/tijd-velden een afwijkend formaat (o.a. lengte) hebben als ze als Eigenschap zijn gedefinieerd. Echter het is naar mijn mening geen blokkerend issue. Als dat wel het geval is, dan hoor ik dat graag!

[sergei-maertens]

Het gebrek aan validatie + business rule en inconsistent gedrag leidt tot implementatiebugs en het probleem wordt pas zichtbaar op het moment dat gegevens weer uitgelezen en gepresenteerd moeten worden.

Dit leidt tot data-corruptie en ik vind dit best wel ernstig voor een API die als primaire doel heeft om gegevens te ontsluiten.

[HenriKorver]

Bedankt voor je reactie, ik begrijp je punt nu beter. We kunnen in de aanvullende specificatie de volgende regel toevoegen.

ztc-015: Als in de resource EIGENSCHAP het attribuut formaat de waarde "datum" heeft, dan moet het attribuut lengte gelijk zijn aan 8. En als het attribuut formaat de waarde "datum-tijd" heeft, dan moet het attribuut lengte gelijk zijn aan 14.

Met deze regel kunnen inconsistent gedrag en implementatiebugs vermeden worden, ook al is het niet fraai dat in de extra eigenschappen van een zaak de datum/tijd-velden een afwijkend formaat hebben.

Eens?

[sergei-maertens]

Ik zou ook voorbeelden geven, want je wil wel YYYYMMDD etc afdwingen, anders wordt data alsnog verkeerd geïnterpreteerd.

Als pleister kan ik hier voor nu mee leven - discussie over wie het fout doet zou hierdoor moeten beslecht worden. Als developer wringt het nog, maar ik als alle doorontwikkeling bevroren is, dan heb ik geen andere keus dan het hiermee eens te zijn.

[HenriKorver]

Ik zou ook voorbeelden geven, want je wil wel YYYYMMDD etc afdwingen, anders wordt data alsnog verkeerd geïnterpreteerd.

Gedaan, zie de uitwerking van ztc-015 in de aanvullende specificatie. Is het zo naar wens?

[sergei-maertens]

Fijn!

Ik zou nog een verwijzing maken in de zrc regels, want de waarden worden pas ingestuurd via de zaken API. Het formaat dient dan ook in de zaken api getoetst te worden tegen de definitie van de eigenschap in de catalogi api.

Ik denk dat het ook nuttig is om te vermelden dat de datum-tijd waarden in de Europe/Amsterdam tijdszone zijn. Een limitatie van dit formaat is namelijk dat je geen UTC-offset kan opnemen en dat leidt tot gekke problemen bij zomertijd/wintertijd.

Bijvoorbeeld 16:00 UTC op een datum in wintertijd wordt 17:00 in de zaakeigenschap maar 18:00 in de zomertijd. Berekening in backends/databases zijn typisch in UTC

[HenriKorver]

Bedankt voor de aanscherpingen, ik neem ze mee!