documentation/guides/registry/schemas.md
This guide will help you start using Scalar Schemas to manage and share JSON Schema objects across your registry APIs in our dashboard on scalar.com, which can be done alongside our CLI.
Make sure you have created a Scalar Account & are logged in (see create account guide)
Scalar Schemas allow you to publish and manage standalone JSON Schema objects outside of OpenAPI documents. These reusable JSON Schema components can be referenced across multiple APIs in your registry, providing a centralized way to manage shared data models and validation rules.
Unlike schemas defined within OpenAPI documents, Scalar Schemas are:
Schemas allow you to reference shared components across your registry APIs.
From the dashboard left-most sidebar under Registry > Schemas, then click "+ New" to create your first schema.
You'll be taken to the schema creation page where you can configure your new JSON Schema.
Schema Name: Give your schema a descriptive name that identifies its purpose (e.g., "User Profile", "Payment Method", "Address Schema").
Description: Add a description explaining what this JSON Schema defines and how it should be used.
Version: Set the initial version for your schema (e.g., 0.1.0, 1.0.0). You can update versions as you publish new iterations.
Namespace: Select the team namespace where this schema will be published. This determines the registry path for referencing the schema.
Schema Access: Choose whether your schema should be:
Once you've configured the metadata, you can define your JSON Schema. Click on the "Edit" tab to access the schema editor.
Here's an example JSON Schema you might create:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"title": "User Profile",
"description": "A user profile schema with contact information",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the user"
},
"email": {
"type": "string",
"format": "email",
"description": "User's email address"
},
"name": {
"type": "object",
"properties": {
"first": {
"type": "string",
"minLength": 1
},
"last": {
"type": "string",
"minLength": 1
}
},
"required": ["first", "last"]
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": ["id", "email", "name"]
}
After defining your JSON Schema, click "Publish" to make it available in the registry. Once published, you'll receive a registry path that you can use to reference this schema.
The registry path follows this format:
registry.scalar.com/@your-team/schemas/your-schema-name@version
Once you've published a schema, you can reference it in your OpenAPI documents using $ref. This allows you to reuse the same JSON Schema definition across multiple APIs.
If the schema is in the same namespace, you can reference it using a relative path:
components:
schemas:
User:
$ref: '@your-team/schemas/[email protected]'
For schemas in other namespaces or public schemas, use the full registry URL:
components:
schemas:
User:
$ref: 'https://registry.scalar.com/@other-namespace/schemas/[email protected]'
openapi: 3.1.0
info:
title: User API
version: 1.0.0
paths:
/users:
get:
responses:
'200':
description: List of users
content:
application/json:
schema:
type: array
items:
$ref: '@your-team/schemas/[email protected]'
You can also use our CLI to interface with Scalar Schemas programmatically. This is especially useful for CI/CD pipelines and automated workflows.
First, make sure you're authenticated with the CLI:
scalar auth login
Or using a token directly:
scalar auth login --token your-api-token
To publish a JSON Schema file to the registry:
scalar schema publish ./schema.json --namespace your-team --name user --version 1.0.0
Required Parameters:
file: Path to your JSON Schema file--namespace: Your Scalar team namespace--name: Name identifier for the schemaOptional Parameters:
--version: Schema version (e.g., 1.0.0, defaults to 0.0.1 if not specified)--private: Make schema private (default: false)--force: Force override an existing version (default: false)Examples:
# Basic publish
scalar schema publish ./schemas/user.json --namespace your-team --name user
# Publish with version and make private
scalar schema publish ./schemas/payment-method.json --namespace your-team --name payment-method --version 2.0.0 --private
# Force update existing version
scalar schema publish ./schemas/user.json --namespace your-team --name user --version 1.0.0 --force
View all schemas for your team namespace:
scalar schema list --namespace your-team
This will display all schemas in your namespace with their versions and access levels.
Update schema metadata (name, description) without re-uploading the file:
scalar schema update --namespace your-team --name user --description "Updated user profile schema"
Remove a schema from the registry:
scalar schema delete --namespace your-team --name user --version 1.0.0
Note: Deleting a schema version will break any references to it in your OpenAPI documents. Make sure to update all references before deleting.
1.0.0, 1.1.0, 2.0.0)description fields for better documentationformat, pattern, minLength, maxLength, etc.$defs for complex nested structures that might be reuseduser-*, payment-*, address-*)You can integrate schema publishing into your CI/CD pipelines to automatically publish schemas when they're updated in your repository.
Example GitHub Actions workflow:
# .github/workflows/publish-user-schema.yml
name: Publish User Schema
on:
push:
branches:
- main
paths:
- 'schemas/**'
jobs:
publish:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v6
- name: Setup Node.js
uses: actions/setup-node@v6
with:
node-version: 24
- name: Log in to Registry
run: npx @scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }}
- name: Publish Schema
run: |
npx @scalar/cli schema publish ./schemas/user.json \
--namespace your-team \
--name user \
--version 1.0.0
This workflow will automatically publish your schemas whenever they're updated in your repository, ensuring your registry stays in sync with your source code.