schemanest_files

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

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.
2. Place the binary into a directory of your PATH
3. Execute schema-nest-cli

Registry

Using docker-compose

1. Create a config.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

   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

Native

1. Download the binary schema-nest-registry* for your OS from the latest release.
2. Execute it with ./schema-nest-registry-{os}-{arch}

Usage

schema-nest-cli --help

Registry

# 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.

For the Redocly UI click here. 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.

Development

Requirements

• GNU make
• Go
• Docker
• pre-commit
• Node.js
• yarn
• zig

Test

make test-coverage-report

Build

make build

Alternatives

• Apicurio 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)
  • 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. [...]