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