diff --git a/docs/reference/api/openapi.yaml b/docs/reference/api/openapi.yaml index 1e8a842..59d941a 100644 --- a/docs/reference/api/openapi.yaml +++ b/docs/reference/api/openapi.yaml @@ -709,7 +709,7 @@ components: type: string format: uri description: JSON Schema URI for this server.json format - example: "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json" + example: "https://static.modelcontextprotocol.io/schemas/draft/server.schema.json" packages: type: array items: diff --git a/docs/reference/server-json/CHANGELOG.md b/docs/reference/server-json/CHANGELOG.md index fb60a48..3fcf0c0 100644 --- a/docs/reference/server-json/CHANGELOG.md +++ b/docs/reference/server-json/CHANGELOG.md @@ -2,6 +2,20 @@ Changes to the server.json schema and format. +## Draft (Unreleased) + +This section tracks changes that are in development and not yet released. The draft schema is available at [`server.schema.json`](./server.schema.json) in this repository. + +### Changed + +- No changes yet. + +### Notes + +When ready for release, changes in this section will be moved to a dated version section (e.g., `## 2025-XX-XX`) and the schema will be published to a versioned URL. + +--- + ## 2025-10-17 ### Changed diff --git a/docs/reference/server-json/CONTRIBUTING.md b/docs/reference/server-json/CONTRIBUTING.md new file mode 100644 index 0000000..d67bc0a --- /dev/null +++ b/docs/reference/server-json/CONTRIBUTING.md @@ -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. diff --git a/docs/reference/server-json/server.schema.json b/docs/reference/server-json/server.schema.json index 59967b5..2d55b58 100644 --- a/docs/reference/server-json/server.schema.json +++ b/docs/reference/server-json/server.schema.json @@ -1,6 +1,6 @@ { "$comment": "This file is auto-generated from docs/reference/api/openapi.yaml. Do not edit manually. Run 'make generate-schema' to update.", - "$id": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$id": "https://static.modelcontextprotocol.io/schemas/draft/server.schema.json", "$ref": "#/definitions/ServerDetail", "$schema": "http://json-schema.org/draft-07/schema#", "definitions": { @@ -373,7 +373,7 @@ "properties": { "$schema": { "description": "JSON Schema URI for this server.json format", - "example": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "example": "https://static.modelcontextprotocol.io/schemas/draft/server.schema.json", "format": "uri", "type": "string" }, diff --git a/tools/extract-server-schema/main.go b/tools/extract-server-schema/main.go index a554e25..723c6a6 100644 --- a/tools/extract-server-schema/main.go +++ b/tools/extract-server-schema/main.go @@ -88,8 +88,12 @@ func main() { } } - // Build the JSON Schema document with dynamic version from OpenAPI spec - schemaID := fmt.Sprintf("https://static.modelcontextprotocol.io/schemas/%s/server.schema.json", version) + // Build the JSON Schema document with draft URL + // The in-repo schema uses "draft" since it may contain unreleased changes. + // When releasing, the schema is published to a versioned URL (e.g., 2025-10-17) + // on https://github.com/modelcontextprotocol/static + _ = version // version from OpenAPI spec available if needed + schemaID := "https://static.modelcontextprotocol.io/schemas/draft/server.schema.json" jsonSchema := map[string]interface{}{ "$comment": "This file is auto-generated from docs/reference/api/openapi.yaml. Do not edit manually. Run 'make generate-schema' to update.", "$schema": "http://json-schema.org/draft-07/schema#",