Move Schema Definitions from JSON to swagger.yaml

[GeorgDangl]

We've discussed it in the group, we want to get rid of the embedded JSON schema files for all objects and instead only rely on a single swagger.yaml file. For this, we'll have to do a bit of work:

• Work in the feature/swagger-spec branch
• Publish the API to SwaggerHub: https://app.swaggerhub.com/apis/buildingSMART/BCF/4.0
• Automatically publish the swagger.yaml changes
• Configure automatically publishing only to run for the master branch
• Update the swagger.yaml file with all changes since the 3.0 release (its current state)
• Remove the JSON schemas
• Update the links in the README to point to swagger hub (we can deep link both to actions as well as models there)
• Check the swagger.yaml on SwaggerHub and make sure it has no errors or warnings
• Ensure all date fields are properly marked as dates, not just as strings in Swagger

We need to sync those items:

• 84af26d#diff-ac8d0a54775f67811b0c24e33fd2fa997d59a30af88b696789daf117e3095391
  3885f36
  -> Custom fields ✔

• d92ce0d
  -> Change url parameter names ✔

• 5cbce2f
  -> Topic relations ✔

• 3b6653c
  -> parent / child relations ✔

• c2584b0
  -> Viewpoint audit info ✔

• fa9aa93
  -> translucency ✔

• 5659983
  -> Remove BIM snippet ✔

• f4f5035
  -> Topic files in viewpoints ✔

• 0f3e266
  -> id and name properties ✔

• 6ce1ee5
  -> markers ✔

• edfde64
  -> Main viewpoint guid ✔

[NKnusperer]

Hello, will 4.0 be a new version in terms of breaking changes or is this just some cleanup regarding the swagger.yaml ?

[GeorgDangl]

Hey @NKnusperer, it'll be a new version sometime in the future. There have been a few new features, and also some breaking changes. We don't yet know when this will be released, but the work for moving away from the JSON schemas to the Swagger file won't be made for currently released versions.

[NKnusperer]

Thank you @GeorgDangl.
After looking into the changes in master compared to the current 3.0 specification the most interesting part seems to be the addition of custom_fields which was something I was actually missing in 3.0.
I'm in a very early stage of implementing the BCF API and I'm wondering what would be the best way to already start using this in a "compliant" way until this has been ratified. The first which comes to mind is declaring the version like /bcf/4.0-draft.2024.02.
Any thoughts on this?

[GeorgDangl]

Well you can also just include the fields already in your endpoints, clients should ignore any fields they don't know about. So including extra information right now should just work, and those fields can be consumed by clients that know about it.