Add support for Avro Schemas

[ghost]

At Pearson Education, we have a preference for expressing data models using Avro Schemas. Avro schemas have some benefits over JSON schema. See, for example, Jon Zuanich's blog.

Ideally, we would like the Swagger specification to offer a choice in the way that the data model is expressed. As a starting point, one could choose either JSON Schema or Avro Schema.

[dolmen]

I had a quick look at Avro Schemas. It looks like it should be straightforward to convert most Avro schemas into a schema to use in a Swagger 2.0 spec. Only null and Union seem to be completely incompatible. The other way seems possible too as Swagger schemas are stricter than full JSON schemas.

Adding generation of Avro Schemas could be interesting for swagger-codegen, but I don't see what "support" for Avro you are requesting in the core Swagger spec.

PS: I'm not a core contributor of Swagger

[ghost]

By "support" I mean (1) the ability to embed an Avro Schema in the Swagger specification instead of embedding a JSON-Schema definition, and (2) support for null and Union, as these are important constructs for schema evolution.

[dolmen]

(1) does not seem in the spirit of Swagger. You can still do it using vendor extensions in a schema definition, but most generation tools will not support your extension. (2) Swagger 2.0 is inspired from JSON Schema, but the Swagger 2.0 designers deliberately choose to exclude null and multiple types for a value (the Union of Avro) that are in JSON Schema, and to disallow them. This is to force API designers to build APIs that do not rely on unions that some programming language do not support natively. So, don't expect them to come back.

[webron]

(1) We're actually considering the option to use alternative data modeling schemes in the future. (2) We did not deliberately choose to exclude null. Being human, we make mistakes and that was one of them. Unfortunately, when it was discovered, it was too late to change. The other aspects that were excluded from JSON Schema were indeed intentional - however, I can't really say that won't change in the future. It will be challenging, but that's not saying it won't happen.

Since I don't know Avro except by name, I cannot address the concerns about the Union without diving in and getting more information about it.

[dolmen]

@webron null as a type doesn't have much value if another type is also allowed for non-null value: type: [ "null", "string" ]. This implies that at least a some kind of unions are required to define such types.

[webron]

That's why null may not be an actual value but isNullable may be the right approach.

[webron]

Parent: #586.

[rage-shadowman]

@dolmen can you please expand on what you mean by "using vendor extensions" to support Avro schemas in swagger?

It is the unions that make the difference here. Otherwise, everything from a swagger generated schema is likely identical to the Avro schema.

We need to support polymorphism and it would be nice if swagger would generate an accurate representation of our actual schema. It sounds like I will have to write such a generator myself, so any pointers would be appreciated.

[LasneF]

@handrews @lornajane this ticket should be closed

as mentionned the topic of union / polymorphism is already been solved by leveraging Json Schema capability

[handrews]

This may also fall under Moonwalk's separation of concerns and decoupling from specific schema systems. So folks can join the discussions there if interested.