search

lvbag / BAG-API

Welkom op het platform waar de technische documentatie over de BAG API Individuele Bevragingen gepubliceerd wordt.
55 stars 19 forks source link

OpenAPI v3 definitions of APIs not importable in Azure API Management #8

Closed Antiohne closed 3 years ago

Antiohne commented 4 years ago

I tried to import the schemas of the BAG APIs into Azure API Management (APIM). APIM complained about every single API:

Parsing error(s): The input OpenAPI file is not valid for the OpenAPI specification https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md (schema https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v3.0/schema.yaml).

Below you can find the errors APIM reported per API. I validated the schemas with an online validator and that validator doesn't report issues. I will also open a Microsoft support ticket because maybe the APIs hit a known restriction of APIM.

Adresgegevens https://github.com/lvbag/BAG-API/blob/master/Technische%20specificatie/Yaml's/20191209-1-lvbag-individuele-bevragingen-20180601/generated-specification/v1/adresgegevens.yaml

One or more fields contain incorrect values: Parsing error(s): Schema Gemeente must contain property specified in the discriminator gemeente in the required field list. [#/components/schemas/Gemeente/discriminator] Schema AdresseerbaarObject must contain property specified in the discriminator adresseerbaarObjectType in the required field list. [#/components/schemas/AdresseerbaarObject/discriminator] Data and type mismatch found. [#/components/schemas/Woonplaats/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkWoonplaatsInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/OpenbareRuimte/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkOpenbareRuimteInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Nummeraanduiding/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkNummeraanduidingInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/eindGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/eindGeldigheid/example]

Adressen https://github.com/lvbag/BAG-API/blob/master/Technische%20specificatie/Yaml's/20191209-1-lvbag-individuele-bevragingen-20180601/generated-specification/v1/adressen.yaml

One or more fields contain incorrect values: SOAP Operation URL should contain action as '/?soapAction=...'

Api-Info https://github.com/lvbag/BAG-API/blob/master/Technische%20specificatie/Yaml's/20191209-1-lvbag-individuele-bevragingen-20180601/generated-specification/v1/api-info.yaml

One or more fields contain incorrect values: SOAP Operation URL should contain action as '/?soapAction=...'

Bronhouders https://github.com/lvbag/BAG-API/blob/master/Technische%20specificatie/Yaml's/20191209-1-lvbag-individuele-bevragingen-20180601/generated-specification/v1/bronhouders.yaml

One or more fields contain incorrect values: Parsing error(s): Data and type mismatch found. [#/paths/~1bronhouders/get/parameters/7/schema/example] Data and type mismatch found. [#/paths/~1bronhouders/post/parameters/0/schema/example] Schema Gemeente must contain property specified in the discriminator gemeente in the required field list. [#/components/schemas/Gemeente/discriminator] Data and type mismatch found. [#/components/parameters/geldigOp/schema/example]

Ligplaatsen https://github.com/lvbag/BAG-API/blob/master/Technische%20specificatie/Yaml's/20191209-1-lvbag-individuele-bevragingen-20180601/generated-specification/v1/ligplaatsen.yaml

One or more fields contain incorrect values: Parsing error(s): Data and type mismatch found. [#/paths/~1ligplaatsen~1{identificatie}/get/parameters/1/example] Data and type mismatch found. [#/paths/~1ligplaatsen/post/parameters/0/example] Schema Gemeente must contain property specified in the discriminator gemeente in the required field list. [#/components/schemas/Gemeente/discriminator] Data and type mismatch found. [#/components/schemas/Ligplaats/allOf/1/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkLigplaatsInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Nummeraanduiding/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkNummeraanduidingInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Woonplaats/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkWoonplaatsInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/OpenbareRuimte/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkOpenbareRuimteInOnderzoek/properties/documentdatum/example] Schema AdresseerbaarObject must contain property specified in the discriminator adresseerbaarObjectType in the required field list. [#/components/schemas/AdresseerbaarObject/discriminator] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/eindGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/eindGeldigheid/example] Data and type mismatch found. [#/components/parameters/geldigOp/example]

Nummeraanduidingen https://github.com/lvbag/BAG-API/blob/master/Technische%20specificatie/Yaml's/20191209-1-lvbag-individuele-bevragingen-20180601/generated-specification/v1/nummeraanduidingen.yaml

One or more fields contain incorrect values: Parsing error(s): Data and type mismatch found. [#/paths/~1nummeraanduidingen~1{nummeraanduidingIdentificatie}/get/parameters/1/example] Data and type mismatch found. [#/paths/~1nummeraanduidingen/get/parameters/8/example] Schema Gemeente must contain property specified in the discriminator gemeente in the required field list. [#/components/schemas/Gemeente/discriminator] Data and type mismatch found. [#/components/schemas/Nummeraanduiding/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkNummeraanduidingInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Woonplaats/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkWoonplaatsInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/OpenbareRuimte/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkOpenbareRuimteInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/eindGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/eindGeldigheid/example] Data and type mismatch found. [#/components/parameters/geldigOp/example]

Objectrelaties https://github.com/lvbag/BAG-API/blob/master/Technische%20specificatie/Yaml's/20191209-1-lvbag-individuele-bevragingen-20180601/generated-specification/v1/objectrelaties.yaml

One or more fields contain incorrect values: Parsing error(s): Data and type mismatch found. [#/paths/~1objectrelaties/get/parameters/8/example] Schema Gemeente must contain property specified in the discriminator gemeente in the required field list. [#/components/schemas/Gemeente/discriminator] Data and type mismatch found. [#/components/schemas/Woonplaats/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkWoonplaatsInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/OpenbareRuimte/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkOpenbareRuimteInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Nummeraanduiding/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkNummeraanduidingInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Ligplaats/allOf/1/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkLigplaatsInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Standplaats/allOf/1/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkStandplaatsInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Verblijfsobject/allOf/1/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkVerblijfsobjectInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Pand/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkPandInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/eindGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/eindGeldigheid/example] Schema AdresseerbaarObject must contain property specified in the discriminator adresseerbaarObjectType in the required field list. [#/components/schemas/AdresseerbaarObject/discriminator] Data and type mismatch found. [#/components/parameters/geldigOp/example]

Openbareruimten https://github.com/lvbag/BAG-API/blob/master/Technische%20specificatie/Yaml's/20191209-1-lvbag-individuele-bevragingen-20180601/generated-specification/v1/openbareruimten.yaml

One or more fields contain incorrect values: Parsing error(s): Data and type mismatch found. [#/paths/~1openbareruimten~1{openbareRuimteIdentificatie}/get/parameters/1/example] Data and type mismatch found. [#/paths/~1openbareruimten/get/parameters/3/example] Schema Gemeente must contain property specified in the discriminator gemeente in the required field list. [#/components/schemas/Gemeente/discriminator] Data and type mismatch found. [#/components/schemas/OpenbareRuimte/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkOpenbareRuimteInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Woonplaats/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkWoonplaatsInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/eindGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/eindGeldigheid/example] Data and type mismatch found. [#/components/parameters/geldigOp/example]

Panden https://github.com/lvbag/BAG-API/blob/master/Technische%20specificatie/Yaml's/20191209-1-lvbag-individuele-bevragingen-20180601/generated-specification/v1/panden.yaml

One or more fields contain incorrect values: Parsing error(s): Data and type mismatch found. [#/paths/~1panden~1{identificatie}/get/parameters/1/example] Data and type mismatch found. [#/paths/~1panden/post/parameters/0/example] Data and type mismatch found. [#/components/schemas/Pand/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkPandInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/eindGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/eindGeldigheid/example] Data and type mismatch found. [#/components/parameters/geldigOp/example]

Standplaatsen https://github.com/lvbag/BAG-API/blob/master/Technische%20specificatie/Yaml's/20191209-1-lvbag-individuele-bevragingen-20180601/generated-specification/v1/standplaatsen.yaml

One or more fields contain incorrect values: Parsing error(s): Data and type mismatch found. [#/paths/~1standplaatsen~1{identificatie}/get/parameters/1/example] Data and type mismatch found. [#/paths/~1standplaatsen/post/parameters/0/example] Schema Gemeente must contain property specified in the discriminator gemeente in the required field list. [#/components/schemas/Gemeente/discriminator] Data and type mismatch found. [#/components/schemas/Standplaats/allOf/1/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkStandplaatsInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Nummeraanduiding/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkNummeraanduidingInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Woonplaats/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkWoonplaatsInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/OpenbareRuimte/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkOpenbareRuimteInOnderzoek/properties/documentdatum/example] Schema AdresseerbaarObject must contain property specified in the discriminator adresseerbaarObjectType in the required field list. [#/components/schemas/AdresseerbaarObject/discriminator] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/eindGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/eindGeldigheid/example] Data and type mismatch found. [#/components/parameters/geldigOp/example]

Verblijfsobjecten https://github.com/lvbag/BAG-API/blob/master/Technische%20specificatie/Yaml's/20191209-1-lvbag-individuele-bevragingen-20180601/generated-specification/v1/verblijfsobjecten.yaml

One or more fields contain incorrect values: Parsing error(s): Data and type mismatch found. [#/paths/~1verblijfsobjecten~1{identificatie}/get/parameters/1/example] Data and type mismatch found. [#/paths/~1verblijfsobjecten/get/parameters/1/example] Data and type mismatch found. [#/paths/~1verblijfsobjecten/post/parameters/0/example] Schema Gemeente must contain property specified in the discriminator gemeente in the required field list. [#/components/schemas/Gemeente/discriminator] Data and type mismatch found. [#/components/schemas/Verblijfsobject/allOf/1/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkVerblijfsobjectInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Nummeraanduiding/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkNummeraanduidingInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Woonplaats/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkWoonplaatsInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/OpenbareRuimte/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkOpenbareRuimteInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Pand/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkPandInOnderzoek/properties/documentdatum/example] Schema AdresseerbaarObject must contain property specified in the discriminator adresseerbaarObjectType in the required field list. [#/components/schemas/AdresseerbaarObject/discriminator] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/eindGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/eindGeldigheid/example] Data and type mismatch found. [#/components/parameters/geldigOp/example]

Woonplaatsen https://github.com/lvbag/BAG-API/blob/master/Technische%20specificatie/Yaml's/20191209-1-lvbag-individuele-bevragingen-20180601/generated-specification/v1/woonplaatsen.yaml

One or more fields contain incorrect values: Parsing error(s): Data and type mismatch found. [#/paths/~1woonplaatsen~1{identificatie}/get/parameters/1/example] Data and type mismatch found. [#/paths/~1woonplaatsen/get/parameters/1/example] Data and type mismatch found. [#/paths/~1woonplaatsen/post/parameters/0/example] Schema Gemeente must contain property specified in the discriminator gemeente in the required field list. [#/components/schemas/Gemeente/discriminator] Data and type mismatch found. [#/components/schemas/Woonplaats/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/KenmerkWoonplaatsInOnderzoek/properties/documentdatum/example] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/Voorkomen/properties/eindGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/beginGeldigheid/example] Data and type mismatch found. [#/components/schemas/HistorieInOnderzoek/properties/eindGeldigheid/example] Data and type mismatch found. [#/components/parameters/geldigOp/example]

Antiohne commented 4 years ago

I received an answer of Microsoft support regarding these errors. The data and type mismatch errors are caused because of a regression (bug) in the API Management instances. The instances will be fixed in a week and our own instances are already patched.

The error "Schema Gemeente must contain property specified in the discriminator gemeente in the required field list." is an actual logical error in the schema. Any property mentioned in "discriminator" must be defined as a required property in the schema. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#discriminatorObject. I received the suggestion that I can either remove the "discriminator" property from the schema or add "gemeente" as a required property to the "Gemeente" schema.

I commented out the discriminator property for the adresgegevens.yaml schema (gemeente and adresseerbaarObjectType) and now get only the following error:

One or more fields contain incorrect values: SOAP Operation URL should contain action as '/?soapAction=...'

I asked Microsoft support if they can explain the origin of this specific error.

Antiohne commented 4 years ago

Based on a quick check of the OpenAPI v3 specification about the use of the discriminator object I think that the necessary schema change is adding the propertyName to the required list. If the intended behavior is occurring I don't know.

Below you fill find the two changes needed for adresgegevens.yaml.

Gemeente:
      title: Gemeente
      required:
      - code
      - gemeente
      type: object
      properties:
        code:
          title: code
          maxLength: 4
          minLength: 4
          pattern: ^[0-9]{4}$
          type: string
          description: Een officiele code die aan een gemeente is toegekend, ontleend
            is aan tabel 33 en zoals bijgehouden in de LVBAG. Dit gegeven is geen
            officieel BAG gegeven en wordt niet als kenmerk van het BAG object Woonplaats
            object bijgehouden. Het wordt als hulpgegven meegeleverd.
          example: "0518"
        naam:
          title: naam
          maxLength: 80
          minLength: 1
          pattern: ^[\u0020-\u007E;\u00A0-\u00FF;\u0100-\u0113;\u0116-\u012B;\u012E-\u014D;\u0150-\u017E;\u02C7;\u02D8-\u02DB;\u02DD;\u2015;\u2018-\u2019;\u201C-\u201D;\u20AC;\u2122;\u2126;\u215B-\u215E;\u2190-\u2193;\u266A;]*
          type: string
          description: Een officiele naam die aan een gemeente is toegekend.
          example: Gemeente Apeldoorn
      discriminator:
        propertyName: gemeente

and

AdresseerbaarObject:
      title: AdresseerbaarObject
      required:
      - heeftAlsHoofdAdres
      - adresseerbaarObjectType
      type: object
      properties:
        heeftAlsHoofdAdres:
          $ref: '#/components/schemas/NEN3610IDNum'
        heeftAlsNevenAdres:
          type: array
          items:
            $ref: '#/components/schemas/NEN3610IDNum'
      description: Abstract type adresseerbaar object
      discriminator:
        propertyName: adresseerbaarObjectType

These kind of changes also has to be applied to the following schemas:

Antiohne commented 4 years ago

One or more fields contain incorrect values: SOAP Operation URL should contain action as '/?soapAction=...'

I asked Microsoft support if they can explain the origin of this specific error.

The cause of the soapAction error was a mistake in the ARM template. The API was marked as a SOAP service instead of a REST service.

Antiohne commented 4 years ago

Based on the upload of 27 february the discriminator issue exists in the APIs:

Parsing error(s): Schema AdresseerbaarObject must contain property specified in the discriminator adresseerbaarObjectType in the required field list. [#/components/schemas/AdresseerbaarObject/discriminator]