OpenStack-SDK-PHP/Why-use-JSON-schema

Why use JSON Schemas?

Reason 1: Consistency with OpenStack ecosystem

There are a bunch of OpenStack projects which actively use JSON schemas and many, many more are moving towards it. Here's an overview:

https://wiki.openstack.org/wiki/OpenStack-SDK-PHP/Schema-Adoption

The long-term goal is to build in functionality to consume schemas directly from OpenStack APIs, rather than offline/cached versions. The obvious benefit of doing this is to preserve a dynamic relationship between server and client; instead of tight coupling to a particular client implementation (either in hand-written code or local schema files) which might not match the API functionality.

Reason 2: Quickens development

Schemas are more feature-packed, convenient and provide for greater speed of development. A good way to think about how this issue will affect us is when we introduce a new OpenStack service. When we do so, it's a decision between defining the new API succinctly in schema code, or writing out 5-10 new classes and then an additional 5-10 test classes on top of that. From personal experience, I found adding to a schema quicker and more efficient because you're mapping directly from API documentation.

The second issue is the avoidance of boilerplate code. When you're hand-writing a bunch of new API operations, there's a high likelihood you're doing the same thing over again with little variance: you accept function arguments, perhaps validate them, stock a request and return the response. Then repeat. And repeat. You soon realize that in order to define an API in PHP, you need a whole lot of code. And then you need even more code to unit test the new functionality. On the other hand, schemas do the same thing (from an end-user's perspective), but in a considerably more efficient way. With schemas, there is no boilerplate code and no waste; instead, we'd have a smaller and leaner codebase.

Reason 3: Better end-user experience

One of the great advantages of schema is how it's completely self-documenting. A schema acts as a contract between client and server: it explicitly maps an API, detailing in a precise way what the expectations are with requests, responses, etc. This can become incredibly useful in our documentation. Other OpenStack projects realize this too, and are investigating whether schema can be used to generate API docs. Another great benefit is that it offers automatic user-input validation - there's no need to dedicate dozens of lines of PHP to do something that can be done in 2 lines of schema.