Wot-thing-description: Are there any OpenAPI <-> TD converters?

[FilipBrinkmann]

(I don't know if this is the right wot repository to ask my question. Sorry if I picked the wrong one).

We would like to support thing descriptions in our applications. However, there is a large stack of applications that provide OpenAPI specifications. In order to have a migration path, we would like to support both ways - TDs and OpenAPI files. However, to keep things consistent and reduce headache, we asked ourselves if there are any libraries or tools that can convert TDs into OpenAPI specs and back. Googling returned nothing, therefore I am asking here. Is anyone working on this?

[relu91]

As far as I know, there's no such a converter. TD to Open API conversion should be pretty easy, however, the opposite might be a lossy transformation, since OpenAPI is more expressive in some points (i.e. you can express different responses for one resource, but in TD you can't right now).

I guess if your company aims to be "Thing Description complaint", they have to use a subset of features of OpenAPI to be able to migrate easily in the future.

[egekorkan]

There is one since a couple of weeks, to be introduced in the W3C TPAC. It is a submodule of the TD playground for now and will be deployed on the hosted instance as well

https://github.com/thingweb/thingweb-playground/tree/master/playground-td_to_openAPI

[egekorkan]

By the way, this is only TD -> Open API and soon there will be TD -> Async API but the other way around has serious limitations, one you have already pointed out. One big difference is that TD abstracts resources into affordances where an affordance can have multiple resource representations or if the affordance is using an REST protocol like most industrial protocols and MQTT to some extend, the affordance will not have a resource but a URI-like string that represents one way to interaction with the affordance.
For doing the OpenAPI -> TD we need to figure out some things:

• How does a resource map to an affordance: Firstly, is it a property, action (or event but that is not possible with OpenAPI as far as I know). Then what is the name of that affordance? If we are lucky and the resource is /myapi/properties/weather then we can wing it and say that this is a property called weather but what about other cases? We can simply name the property the URI of the resource and it would work.
• (As @relu91 said) OpenAPI can specify that a resource can have different responses based on the method or based on the content type wanted. TD can do that but in a rather unusual way. If you are interested in this, I can provide examples :)
• OpenAPI can define components which are reusable schemas. This is something that the TD task force was looking into but it is a bit in sleep mode.

Since the above converter implementation was done by @adriankast, do you have something to add?

[adriankast]

I think you mentioned all major points, but I can share some additional thoughts:

• even for TD -> Open API there will be some limitations since:
  
  
  
  1. They have different scopes, so e.g. adding all semantic stuff (from a TD) to an openAPI instance as custom fields could be possible, but doesn't really make sense.
  
  
  2. They use different solutions for the same problems sometimes, e.g., if you look at the Security there is no psk equivalent in openAPI, the http authentication has to happen in the Header, ...
  
  
  3. The effort for possible conversions that add not much value is at some points high, e.g., it could be possible to map the TD-event-data to an openAPI callback, but Events are only seldom representable in openAPI (http longpoll) anyway and the conversion would be rather difficult.
  
  

• for OpenAPI -> TD as all of you already describe even more problems arise since openAPI at some points allows to describe implementations more into detail. (e.g. from the Security: you can define securityDefinitions that have to be ALL or SOME fullfilled, I don't think this is possible in a TD). I would take the guess that the most promising approach here would be to go for a semi-automated conversion, where the user makes certain choices based on the found openAPI instance. Since I think a fully automated conversion openAPI -> TD won't be able to produce quality TDs.

[adriankast]

And you can always check the current state of TD -> OpenAPI conversion here:
https://github.com/adriankast/thingweb-playground/tree/openAPI

[egekorkan]

You can now easily test it out on the deployed version: http://plugfest.thingweb.io/playground/ :)

[egekorkan]

Now available as a standalone npm package: https://www.npmjs.com/package/@thing-description-playground/td_to_openapi :)

[relu91]

I propose closing this issue, @FilipBrinkmann are you ok?

[FilipBrinkmann]

I am sorry for answering late. Thanks to everyone for your quick and insightful answers. It definitely helped me a lot!
We will definitely have a look at the converter you pointed out. On a side note, I guess that it will be sufficient for our use cases - namely providing a fallback strategy for developers which are new to WoT, as well as for legacy applications using OpenAPI.

So this issue can be closed from my point of view. And thank you again - great community here!