Sharing Json Schema files among projects with versioning

Question

Problem

We have a few independent projects (micro-services) that at some point in their life will refer to some JSON schema files, needles to say that each project has its own programming stack (mostly Nodejs and Golang though).

What are the best practices for sharing such data among different projects while keeping versioning.

Bellow I describe my own solution, however I would like to get your feedback as well.

my solution

1. I have set up a github project and put json schema files there
2. For each change to schemas I update the repo and tag it with a new version
3. I use jsdelivr to access it like this: https://cdn.jsdelivr.net/gh/[GITHUB-ID]/[GITHUB-PROJECT]@[TAG]/schema.js
4. When I want to clone the code of a random microservice which requires schema file(s), as part of build process I download the schema file from jsdelivr and save it to my local repo, However the downloaded schema file(s) are git ignored.

What do you think about it, Is there a better and smoother way to handle this case?

Answer 1

Handling multiple dependencies is ( at least in my opinion ), one of the major pain points in working with multiple microservices. A few ways which I can think of or have seen are -

1. Having a Monorepo -

   It becomes a lot easier if you have all your services co-located under just one repository. This means you might use monorepo helpers like lerna ( for JS projects ) or similar. In this case you can have a folder structure like -

-- root
---- shared schema files ( with versioning )
---- service 1
---- service 2

2. Having a service which provides schema files -

   The idea here is to have a separate repo for the schema files and serve them when any of your app loads. This can be done in several ways -

   a). By maintaining different packages for different languages - like gems for ruby and node_modules for Node projects. Then these modules are responsible for fetching relevant schemas from a central repo.

   b). By having a docker image running locally - you can also keep these schemas as docker image ( with versioning of course ) and server them by mounting as logical volumes. The image can have all kinds of helper libraries you might need to maintain the schema ( maybe validators , tests, and UI views for schemas ).

PS: you might also wanna have a look at tools like prototool.

Answer 2

From my perspective, the best way is to put JSON schema into a separated file (in your project or in a common repo in Github, etc.) and then refer to it from the documentation that you use to describe you APIs. For example, if you use Swagger, you can include a reference to external URL (or file path). Example 1, example 2.

Versioning is anyway up to you, just name your JSON-files like some-entity-response-v2.json, and your APIs will probably have the same version. Keep each version backward-compatible and you will be fine.