Unexpected namespaceUri property on ClassificationPropertyContract.v4

[rubendel]

Describe the bug When calling /api/Classification/v4 on production (https://api.bsdd.buildingsmart.org) the returned ClassificationContract.v4 seems to reference ClassificationPropertyContract.v4 objects that have the namespaceUri property, which (according to https://app.swaggerhub.com/apis/buildingSMART/Dictionaries/v1#/Classification/get_api_Classification_v4) is not a valid property.

To Reproduce Steps to reproduce the behavior:

1. Call /api/Classification/v4 (on production)
2. Deserialize the object according to deserializers generated from the https://app.swaggerhub.com/apis/buildingSMART/Dictionaries/v1 OpenAPI spec

Expected behavior No namespaceUri property on ClassificationPropertyContract.v4, or an updated spec.

Additional context From https://forums.buildingsmart.org/t/bsdd-tech-updates/4889 I understand some changes have been implemented, also on production, but the OpenAPI spec that is being referred to from the bSDD github page (https://github.com/buildingSMART/bSDD) still seems to be referring to a V1 of the OpenAPI spec. I suspect perhaps that's where something is going wrong because until now I have not updated my code that was working a few months ago, maybe I am missing the updated spec.

[rubendel]

A little bit more info, I managed to get this working by adding the namespaceUri property to the following two types:

• ClassificationRelationContract.v4
• ClassificationPropertyContract.v4

This might not be conclusive, but these are currently being used in our software and triggered errors when reading the results coming back from the bSDD production environment.

So there could be two situations, I think:

• A bug in the server-side implementation where it erroneously sends these namespaceUri properties on the mentioned types
• Changes to the OpenAPI spec are not reflected on the spec hosted here: https://app.swaggerhub.com/apis/buildingSMART/Dictionaries/v1

Two additional suggestions:

• The version number can be updated when changes to the schema are being done, especially for changes that are deployed to the bSI production environment.
• Perhaps the OpenAPI definition could be part of this GitHub repository, so that changes can be tracked

[atomczak]

Hi @rubendel, thank you for reporting this. No changes were made to that API recently, so it was probably like this for some time already. On the forum, we announced changes that we are rolling out in September, which will result in v5. We will update the spec as well. cc: @Baars-IT

[Baars-IT]

Hi @rubendel, thanks again for reporting the issue! Updating the OpenAPI definition on SwaggerHub is a manual process and sometimes we forget to update it. It is updated now.

About your additional suggestions:

• The yaml will become available soon on GitHub: documentation/bSDD OpenAPI.yaml
• We do not consider new fields in the output as breaking changes. We only update the version number in case of a breaking change (e.g. field removed, field renamed, behaviour changed).

[rubendel]

Thanks for the responses @atomczak and @Baars-IT and for the updated spec.

1. Great to hear the OpenAPI spec will be published on github as well.
2. Ok fair enough. Keep in mind though that a lot of tooling (especially in the typed/compiled languages) are actually that strict. In my case I have been using Java.