Correct way to return JSON schemas in a REST API

Question

in our company we have some APIs that return some JSON data. Before sending, for instance, data to the backend using PUT, PATCH, or POST, we need to do some kind of validation in the different clients (web, mobile apps, etc). Right now that's a ton of duplicated work, so we would like to start using JSON schemas for our resources. That way the clients can download the schema for a resource and do validations without having to:

1. Call the backend to get the actual error.
2. Implementing the validation logic.

I'm not sure about this idea, so I would like to get your opinion on this and see how this would work in a REST API. I have seen some people suggesting creating an endpoint called /schemas/<name-of-resource>, but not sure.

Answer 1

I have seen some people suggesting creating an endpoint called /schemas/

Most of the validation schemes out there are public, hence, have a route. So yes, you need to make it public. It doesn't mean it should be accessible to everyone. You could secure the document for only clients of yours.

Now, the route doesn't have to be part of the API. For simplicity, the document is usually served as a whole from a single endpoint which can be published from a Web server or CDN as static content. Bear in mind that schemes are versioned too. I find one route per schema and version too complex to manage. A single versioned descriptor, including all models, makes for a more comprehensive document.

Now, bear in mind the following.

The scheme is usually cached, so clients download it from time to time. As you may guess, this increases complexity since we must find a way to invalidate the cache (on the client side) every time we release new schema versions.

A second vector of complexity comes from segmentation.

1. The json schema model version itself
2. Your data model version
3. The client/agent version (browser version, OS-SDKs, etc.)

You have to find libraries compatible with #1 and #3 so that it allows you to implement #2 to meet your multi-platform requirements and expectations.

You have alternatives tho.

In my opinion, the real issue is at implementing the API client several times and maintaining each API client as part of the app. Repeating validation logic is only a symptom of the previous.

The alternative could be a multi-platform API client (say, implemented in Kotlin) so the API client (logic, validations, etc) is programmed only once.

Answer 2

It is not clear for me if you are at the client side or backend side, but what you have mentioned so far is that you are moving to more Contract-First approach, which is common in SOAP, but what you need is Restful and Json support,

I suggest using OpenAPI - Swagger- as it has capabilities for code generation and schema validation.

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

Even without it, you still can use Json Schema support for the language you are using as you mentioned earlier.

Answer 3

First of all, data validation must happen in the backend, you can't trust the client to do it - the client might be buggy, or some bad actor might be using their own client to hack your service.

So what exactly do you want to protect against by letting the client check its own data that it's goin to send to the backend?

• Invalid structure? That should be done first by coding, and verified by testing. A complex validation framework is not a replacement for this, and it's just a burden.
• Invalid data? Are the possible constraints expressible in JSON schemas at all? If yes, it still might be the wrong place to do the checking, as your data validation should be user-centric, not API-centric.

So unless there is a compelling reason that you didn't show yet, don't do it, it's redundant work at the wrong place.