modelcontextprotocol/registry
Watch
1
0
Fork
You've already forked registry
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix misleading server.json schema URL label (#803)

Browse source 
The schema in this repo may contain unreleased changes, so labeling it
with a dated version URL is misleading. Change to use a `draft` URL
instead, and add documentation for the schema contribution process.

- Update $id in server.schema.json to use draft URL
- Update example $schema URL in openapi.yaml
- Add Draft (Unreleased) section to CHANGELOG.md
- Add CONTRIBUTING.md with process for making/releasing schema changes

Written by Claude Code, reviewed and tweaked by me.

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Tadas Antanavicius 2025-12-03 08:44:30 -08:00 • committed by GitHub
commit 51c70ba034
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 53 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

30
docs/reference/server-json/CONTRIBUTING.md Normal file
View file

@ -0,0 +1,30 @@
# Contributing to server.json Schema
This document describes the process for making and releasing changes to the `server.json` schema.
## Making Changes
1. **Modify the OpenAPI spec**: Edit `docs/reference/api/openapi.yaml` with your schema changes. The `ServerDetail` component defines the server.json structure.
2. **Regenerate the schema**: Run `make generate-schema` to update `server.schema.json` from the OpenAPI spec.
3. **Update the changelog**: Add your changes to the "Draft (Unreleased)" section in `CHANGELOG.md`.
4. **Open a PR**: Submit a pull request to this repository for review.
## Releasing Changes
When the draft changes are ready for release:
1. **Update the changelog**: Move changes from "Draft (Unreleased)" to a new dated section (e.g., `## 2025-XX-XX`).
2. **Update the schema URL**: Change the `$id` in the schema and the example URL in `openapi.yaml` from `draft` to the release date (e.g., `2025-XX-XX`).
3. **Merge the PR**: Get approval and merge the changes to main.
4. **Publish to static hosting**: Open a PR on [modelcontextprotocol/static](https://github.com/modelcontextprotocol/static/tree/main/schemas) to add the new versioned schema file. This "locks in" the released schema at its versioned URL.
## Schema Versioning
- **Draft schema**: `https://static.modelcontextprotocol.io/schemas/draft/server.schema.json` - For in-progress changes, may change without notice.
- **Released schemas**: `https://static.modelcontextprotocol.io/schemas/YYYY-MM-DD/server.schema.json` - Stable, versioned by release date.