Add JSON schema support

[sdeleuze]

It would be super useful for Spring Hateoas to support additional documentation metadata like being able to describe JSON data with JSON schema.

See also https://github.com/spring-projects/spring-hateoas/issues/16 for related discussion.

[odrotbohm]

What would that support look like? Spring HATEOAS doesn't know anything about the structure of the application level content. All it currently cares about is hypermedia controls and how to create them. Note that there is JSON Schema support in Spring Data REST, where I think it makes a lot of sense, as — through the Spring Data PersistentEntity API — that library has information about the parts of the representation that resemble domain types, which basically means that there's something to actually create a schema for.

[sdeleuze]

My use case is really about allowing JSON schema support in any kind of RESTful Spring Boot + applications using @RestController, not only Spring Data REST based ones.

I think such feature would help to provide an alternative with Spring HATEOAS + Spring REST Docs (cc @wilkinsona) to OpenAPI (very Swagger oriented, and not HATEOAS compliant at all) or RAML that are documenting a wide range of informations (Spring REST docs provides human readable specs but not machine readable ones), and would be complementary to this PR about providing title and type properties.

Such additional metadata could be used for various purpose:

• Automated testing of RESTful APIs
• Developer documentation for free
• Expose more information for libraries like Orbit.js

As mentioned in this blog post or implemented by Spring REST Docs, it could maybe use by default the field names, types and Bean Validation annotations, while providing some extension points to add/customize contraints.

Any thoughts?

[gregturn]

The only avenue I see to implement something would be providing an API to build a JSON Schema compliant document. But it would be to the library user to actually use it.

I don't know how easy or hard it is to build that given Spring HATEOAS isn't setup for building metadata documents.

[sdeleuze]

Using https://github.com/FasterXML/jackson-module-jsonSchema would have been a possible solution I guess.

But Indeed, that's maybe outside of Spring HATEOAS scope. Maybe supporting JSON schema would be better at Spring REST docs level (see this issue) or at RAML level for those who seeks machine readable specs ...

See this discussion about HATEOAS support in RAML forums.

Feel free to close this issue if you think this is outside of Spring HATEOAS scope.

[gregturn]

@odrotbohm can we simply move the JSON Schema builders from Spring Data REST to Spring HATEOAS?

SDR can continue to use them. Spring HATEOAS can now offer them to anyone else that wants to manually assemble such a docu.