https://github.com/timo-reymann/schemanest
Where schemas grow, thrive, and scale with your team.
https://github.com/timo-reymann/schemanest
hackfriday json-schema
Last synced: 22 days ago
JSON representation
Where schemas grow, thrive, and scale with your team.
- Host: GitHub
- URL: https://github.com/timo-reymann/schemanest
- Owner: timo-reymann
- License: gpl-3.0
- Created: 2025-04-25T07:02:09.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-05-25T03:06:42.000Z (27 days ago)
- Last Synced: 2026-05-25T05:09:15.626Z (27 days ago)
- Topics: hackfriday, json-schema
- Language: Go
- Homepage: https://schema-nest.timo-reymann.de/
- Size: 1.69 MB
- Stars: 10
- Watchers: 1
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Notice: NOTICE
Awesome Lists containing this project
README
SchemaNest
===
[](https://github.com/timo-reymann/SchemaNest/releases)
[](https://hub.docker.com/r/timoreymann/schemanest-cli)
[](https://hub.docker.com/r/timoreymann/schemanest-registry)
[](https://github.com/timo-reymann/SchemaNest/releases)
[](https://github.com/timo-reymann/SchemaNest/blob/main/LICENSE)
[](https://app.circleci.com/pipelines/github/timo-reymann/SchemaNest)
[](https://renovatebot.com)
[](https://pre-commit.com/)
[](https://codecov.io/gh/timo-reymann/SchemaNest)
[](https://sonarcloud.io/summary/new_code?id=timo-reymann_SchemaNest)
[](https://sonarcloud.io/summary/new_code?id=timo-reymann_SchemaNest)
[](https://sonarcloud.io/summary/new_code?id=timo-reymann_SchemaNest)
Where schemas grow, thrive, and scale with your team.
## Features
- Supports uploading and versioning JSON schemas to a central repository.
- Provides a web interface for browsing and searching schemas.
- CLI tool for uploading schemas from the command line.
- Accessible by default for screen-readers and visually impaired people.
## Requirements
- Postgres for production usage (SQLite is only recommended for evaluation and smaller instances)
## Installation
### CLI
#### Docker
```sh
docker run --rm -it -v $PWD:/workspace:ro -w /workspace \
timoreymann/schemanest-cli schema-nest-cli \
--help
```
#### Native
1. Download the binary `schema-nest-cli*` for your OS from
the [latest release](https://github.com/timo-reymann/SchemaNest/releases/latest).
2. Place the binary into a directory of your `PATH`
3. Execute `schema-nest-cli`
### Registry
#### Using docker-compose
1. Create a `config.toml`:
```toml
# Connect to local database
database_dsn = "postgres://schema-nest:schema-nest@db/schema-nest"
# Allow uploads only with authentication
enable_upload_authentication = true
# Define API-Key(s)
[[api_keys]]
identifier = "frontend"
# make sure to set this to a proper secret (UUID, hash etc.)
key = "my-super-secret-api-key"
patterns = [
# Allow all schemas prefixed with @frontend/
"@frontend/*",
# Allow schema mjml-config
"mjml-config"
]
```
2. Create the `docker-compose.yaml`
```yaml
services:
registry:
image: timoreymann/schemanest-registry
command:
- schema-nest-registry
- serve-http
- -C
- /etc/SchemaNest/config.toml
volumes:
- ./config.toml:/etc/SchemaNest/config.toml
ports:
- 8080:8080
db:
image: postgres:15-alpine
environment:
POSTGRES_DB: schema-nest
POSTGRES_USER: schema-nest
POSTGRES_PASSWORD: schema-nest
volumes:
- schema-nest-db-data:/var/lib/postgresql/data
restart: always
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 5s
timeout: 5s
retries: 5
volumes:
schema-nest-db-data:
```
3. Start it up with `docker compose up`
4. Open your browser at [localhost:8080](http://localhost:8080)
#### Native
1. Download the binary `schema-nest-registry*` for your OS from
the [latest release](https://github.com/timo-reymann/SchemaNest/releases/latest).
2. Execute it with `./schema-nest-registry-{os}-{arch}`
## Usage
```shell
schema-nest-cli --help
```
### Registry
```shell
# Spin up server on 0.0.0.0:8080
schema-nest-registry serve-http --port "8080"
```
## Motivation
Managing JSON Schemas is not rocket science. But every company I worked on had its own way of doing it. Some used a
simple file share, others had a complex setup with multiple repositories and CI/CD pipelines. I wanted to create a
solution that is straightforward to use, flexible, and can be adapted to any workflow.
There are already a few tools out there that do a great job at managing JSON schemas. But they are either too complex or
too resource-intensive for my needs. I wanted to create a tool that is easy to use, lightweight, and can be run on any
machine.
## Documentation
### API
The API definition is managed through OpenAPI 3.0, you can find an up-to-date spec in [openapi.yml](./openapi.yml).
For the [Redocly UI click here](https://timo-reymann.github.io/SchemaNest/apidocs.html). Please keep in mind that this
is always the latest development version.
Changes to the API are done when ever possible in a backward-compatible manner. So make sure your consuming code can
handle extra fields.
## Contributing
I love your input! I want to make contributing to this project as easy and transparent as possible, whether it's:
- Reporting a bug
- Discussing the current state of the configuration
- Submitting a fix
- Proposing new features
- Becoming a maintainer
To get started, please read the [Contribution Guidelines](./CONTRIBUTING.md).
## Development
### Requirements
- [GNU make](https://www.gnu.org/software/make/)
- [Go](https://go.dev/doc/install)
- [Docker](https://docs.docker.com/get-docker/)
- [pre-commit](https://pre-commit.com/)
- [Node.js](https://nodejs.org/en/download)
- [yarn](https://classic.yarnpkg.com/lang/en/docs/install/)
- [zig](https://ziglang.org/learn/getting-started/)
### Test
```sh
make test-coverage-report
```
### Build
```sh
make build
```
### Alternatives
- [Apicurio Registry](https://www.apicur.io/registry/)
- Apicurio Registry is a runtime server system that stores a specific set of artifacts as files. Apicurio Registry
enables you to add, update, and remove the artifacts from the store using a remote REST API.
- [Confluence Schema Registry (for Kafka)](https://github.com/confluentinc/schema-registry)
- Confluent Schema Registry provides a serving layer for your metadata. It provides a RESTful interface for storing
and retrieving your Avro®, JSON Schema, and Protobuf schemas. [...]