51c70ba034The 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>
30 lines
1.5 KiB
Markdown
30 lines
1.5 KiB
Markdown
# 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.
|