Json schema's keuzerelaties vallen weg

[kad-kolman]

Het json schema wordt gegenereerd aan de hand van https://geonovum.github.io/uml2json/document.html (zie https://github.com/Imvertor/Imvertor-Maven/issues/443). Echter, hierin wordt niet omschreven hoe om te gaan met keuzes.

Dat betekend dat momenteel in de vertaling keuzerelaties niet vertaald worden en wegvallen.

De bijgevoegde afbeelding wordt vertaald naar het volgende: EmailOfWebPagina: $anchor: "EmailOfWebPagina" $ref: "https://register.geostandaarden.nl/jsonschema/uml2json/0.1/schema_definitions.json#/$defs/LinkObject"

Hiervoor moet een passende oplossing voor bedacht worden.

Wij zouden voorstellen dat een keuze naar oneOf (https://json-schema.org/draft/2020-12/json-schema-core#section-10.2.1.3) wordt vertaald waarbij de lijst bestaat uit refs naar de bijbehorende schema's van de keuze-opties (met credits naar @Jesse Bakker).

[ArjanLoeffen]

De referentie naar https://register.geostandaarden.nl/jsonschema/uml2json/0.1/schema_definitions.json#/$defs/LinkObject is correct; het is het gevolg van een configuratie setting: bp-by-reference-encodings = /req/by-reference-link-object Dit is uitgelegd in https://geonovum.github.io/uml2json/document.html#_b2bfa230-4fcd-9de0-b457-19b187542a54 Als Kadaster dit anders wil vormgeven in de json serialisatie kunnen we de configuratie aanpassen. De default regel is

    <!-- 
        Best Practice for OGC - UML to JSON Encoding Rules 
        Clause 7.8
        options: 
        /req/by-reference-uri
        /req/by-reference-link-object
    -->
    <parameter name="bp-by-reference-encodings">/req/by-reference-link-object</parameter>

Zie https://github.com/Imvertor/Imvertor-Maven/blob/a23fb01f159e5d366526bab750ed48f64212d5cf/src/main/resources/input/OGC/cfg/schemarules/JSON-OGC.xml#L54 Zie ook discussie op: https://github.com/Geonovum/shapeChangeTest/issues/52

[ThiesMesdag]

Als ik het goed begrijp is met de huidige by-reference-link-object instelling de Json goed omdat je bij een keuze altijd maar een van de keuze elementen mag kiezen en dan maakt het niet uit welke keuze dat is. Dus "een link" is valide json. Je kan daarmee alleen iets afdwingen over het soort link. Het json schema vindt elke link goed, omdat verwachte target niet is gespecificeerd.
Met een by-rerference-uri wordt het wel expliciet, any of email-uri of contactformulier-uri zoals in het voorbeeld?

Aanvullend hoe wordt relatiesoort leidend ondersteund in de Json? Wordt dan de relatienaam gebruikt in plaats van de target rolnaam?

[ArjanLoeffen]

Met een by-rerference-uri wordt het wel expliciet, any of email-uri of contactformulier-uri zoals in het voorbeeld?

@PalmJanssen weet jij dat?

Aanvullend hoe wordt relatiesoort leidend ondersteund in de Json? Wordt dan de relatienaam gebruikt in plaats van de target rolnaam?

De noodzakelijke info wordt geleverd door de relatie of de rol. Dat wordt bepaald in de EP compiler, die de waarde van <mim:relatiemodelleringtype> uitleest. De Json ziet vervolgens gewoon de EP tussenstap resultaten en weet niks van het type relatiemodellering. Dus ja, rolnaam of relatienaam zijn in dat perspectief uitwisselbaar.

[ThiesMesdag]

De aanpassing van de bp-by-reference-encodings hebben nog niet gebracht wat we willen voor de relaties tussen objecttypen.

Op de onderstaande manier is het ik het goed te gebruiken in een OpenAPI-specification en kunnen we er bijvoorbeeld met een tool als Swagger erdoor heen klikken.

   "Stuk" : {
      "$anchor" : "Stuk",
      "description" : "begrip: http://tax.kadaster.nl/id/begrip/_Stuk",
      "type" : "object",
      "properties" : {
        "omvat" : {
          "type" : "array",
          "items" : {
            "$ref" : "#/$defs/Stukdeel"
          },
          "minItems" : 1,
          "uniqueItems" : true
        }
      },
      "required" : [ "omvat" ]
    },   "Stuk" : {
      "$anchor" : "Stuk",
      "description" : "begrip: http://tax.kadaster.nl/id/begrip/_Stuk",
      "type" : "object",
      "properties" : {
        "omvat" : {
          "type" : "array",
          "items" : {
            "$ref" : "#/$defs/Stukdeel"
          },
          "minItems" : 1,
          "uniqueItems" : true
        }
      },
      "required" : [ "omvat" ]
    },

Bij een keuze zouden dan dus alle gerelateerde items expliciet als OneOf moeten worden genoemd.

[ThiesMesdag]

Op verzoek van Paul in het Engels:

For a properly usable Json, it is necessary that when the model has a relationship from object type A to zero, one or more object type B, this is also enforced in the schema. In the current specification document, only object type A has a relationship to an object type can be described and not that it must explicitly be object type B.

In the following way, it I it is good for use in an OpenAPI specification and we can follow the links with a tool like Swagger.

  "Parcel" : {
      "$anchor" : "Parcel",
      "description" : "begrip: http://catalogus.kadaster.nl/id/begrip/Perceel",
      "type" : "object",
      "properties" : {
        "owner" : {
          "type" : "array",
          "items" : {
            "$ref" : "#/$defs/Person"
          },
          "minItems" : 1,
          "uniqueItems" : true
        }
      },
      "required" : [ "owner" ]
    },

[PalmJanssen]

doorgezet naar https://github.com/Geonovum/uml2json/issues/54

[ArjanLoeffen]

Ik denk dat het voorbeeld "$ref" : "#/$defs/Person" een inline voorbeeld is. En dat is toch maximaal expliciet?

[PalmJanssen]

k denk dat het voorbeeld "$ref" : "#/$defs/Person" een inline voorbeeld is. En dat is toch maximaal expliciet?

zeker. Maar dus wel een inline. Bij by reference is die target specificatie er niet.

[ThiesMesdag]

Het issue na het testen was dat nergens de inline werd gegenereerd in de Json, maar overal een by reference link, ook na aanpassen van de Kadaster: bp-by-reference-encodings wordt /req/by-reference-uri. Dus ook bij relaties die geen keuze zijn.

Kan dat ook aan het ontbreken van de rolnamen liggen omdat wij relatienamen gebruiken? Of gaat het genereren van de inline relatie op een andere manier fout.

Als het generenen van de inline relatie wel goed gaat zouden we bij een keuze een [any-of] inline relatie1 of inline relatie2 verwachten.

[PalmJanssen]

De officiele UML2JSON specs kent de relatie(naam) niet als property. Daar is dan ook geen TV op gespecificeerd. Hoe Imvertor dat doet weet ik niet. Ik neem aan een toepassing die wel die TV mogelijk maakt op een relatie. Imvertor gaat mogelijk default uit (als er niets staat) van by reference bij een relatie. Net zoals de UML2JSON spec doet: https://geonovum.github.io/uml2json/document.html#toc63