timoreymann/schemanest-cli repository overview

⁠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"
   ]
   

   Copy
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:
   

   Copy
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. [...]