# Schemaport

> Schemaport docs

- Documentation: https://pr-2-390be2854416.thally.app
- GitHub: https://github.com/schemaport/docs
- Full docs for LLMs: https://pr-2-390be2854416.thally.app/llms-full.txt
- Agent discovery (ai.txt): https://pr-2-390be2854416.thally.app/ai.txt
- Structured docs index (JSON): https://pr-2-390be2854416.thally.app/api/docs-index
- OpenAPI spec: https://pr-2-390be2854416.thally.app/openapi.yaml

## For AI agents

Every page supports content negotiation on its human URL:
- JSON API: append `?format=json` or send `Accept: application/json`
- JSON-LD: append `?format=ldjson` or send `Accept: application/ld+json`
- Markdown: append `?format=md` or send `Accept: text/markdown`
- Per-page API: https://pr-2-390be2854416.thally.app/api/docs/{page-id}
- Search API: https://pr-2-390be2854416.thally.app/api/search?q={query}
- Capability manifest (skill): https://pr-2-390be2854416.thally.app/skill.md
- Agent guidance (editing these docs): https://pr-2-390be2854416.thally.app/AGENTS.md
- MCP server (attach docs as native tools): https://pr-2-390be2854416.thally.app/api/mcp
- Agent readiness: https://pr-2-390be2854416.thally.app/api/agent-readiness

### Recommended workflow

1. Use this index, the search API, or `search_docs` before choosing a page.
2. Read the smallest set of relevant pages and follow their prerequisite links.
3. Treat the published docs as the source of truth. Label inferences and say when evidence is missing.
4. Cite the canonical human page URLs, not only API endpoints.
5. Use `/AGENTS.md` before editing a repository. The public MCP server is read-only.

## Get started

### Start here

- [Introduction](https://pr-2-390be2854416.thally.app/): Define an AI tool schema once, then safely use it across OpenAI, Anthropic, Gemini and MCP.
- [The problem](https://pr-2-390be2854416.thally.app/portability-problem): One tool schema, four providers, four different verdicts — and the worst one is the provider that says yes and then ignores half of it.
- [Installation](https://pr-2-390be2854416.thally.app/installation): Build the SchemaPort CLI from the six source repositories. The npm packages are not published yet.
- [Quickstart](https://pr-2-390be2854416.thally.app/quickstart): Check one tool schema against all four providers, then compile it — about five minutes, no API key.

### Core concepts

- [Canonical schemas](https://pr-2-390be2854416.thally.app/concepts/canonical-schemas): The one input format SchemaPort accepts, and why it stays the source of truth for every provider.
- [Compatibility](https://pr-2-390be2854416.thally.app/concepts/compatibility): What "compatible" means in SchemaPort, the three severity levels, and why a silently weakened schema is never reported as a pass.
- [Safe and lossy](https://pr-2-390be2854416.thally.app/concepts/safe-and-lossy-compilation): The rule at the centre of SchemaPort — representation changes compile, constraint-destroying changes are refused until you say otherwise.
- [Breaking changes](https://pr-2-390be2854416.thally.app/concepts/breaking-changes): How diff classifies every difference between two versions of your canonical schemas — and why anything unprovable is reported as breaking.

## Commands

### Commands

- [Check](https://pr-2-390be2854416.thally.app/commands/check): Find out where a tool schema is incompatible with OpenAI, Anthropic, Gemini and MCP, and whether compile can fix it — without an API key.
- [Compile](https://pr-2-390be2854416.thally.app/commands/compile): Turn one canonical tool into OpenAI, Anthropic, Gemini and MCP definitions, plus a manifest recording every transformation — refusing anything that would weaken your schema.
- [Probe](https://pr-2-390be2854416.thally.app/commands/probe): Ask each provider API whether it really accepts your compiled tool definition, and keep "we could not ask" strictly separate from "the provider said no".
- [Diff](https://pr-2-390be2854416.thally.app/commands/diff): Compare two versions of your tools and find out which changes break existing callers, before you ship the release.

## Guides

### Guides

- [Continuous integration](https://pr-2-390be2854416.thally.app/guides/ci): Gate pull requests on provider incompatibilities and breaking schema changes, without an API key.
- [TypeScript](https://pr-2-390be2854416.thally.app/guides/typescript): Import compiled tool definitions, pass them to each provider SDK, and handle the null that OpenAI strict mode introduces.
- [Existing project](https://pr-2-390be2854416.thally.app/guides/existing-project): Turn provider-specific tool schemas you already maintain by hand into one canonical definition, without changing what you send.
- [Migrate providers](https://pr-2-390be2854416.thally.app/guides/migrate-providers): Find out what a provider change costs before you commit to it, then compile, verify and ship.

## Providers

### Providers

- [Compatibility matrix](https://pr-2-390be2854416.thally.app/providers/compatibility-matrix): What survives compilation, keyword by keyword, on OpenAI, Anthropic, Gemini and MCP.
- [OpenAI](https://pr-2-390be2854416.thally.app/providers/openai): How SchemaPort compiles a canonical tool into a Responses API function tool with strict mode, and what strict mode costs.
- [Anthropic](https://pr-2-390be2854416.thally.app/providers/anthropic): Anthropic accepts your whole schema and enforces none of it. SchemaPort drops nothing and reports the non-enforcement instead.
- [Gemini](https://pr-2-390be2854416.thally.app/providers/gemini): Gemini's function declarations take a 22-field OpenAPI subset. See which keywords survive, which are dropped lossily, and why types come out uppercase.
- [MCP](https://pr-2-390be2854416.thally.app/providers/mcp): MCP speaks JSON Schema, so compilation is close to an identity transform. There is no API to probe, so SchemaPort validates protocol shape locally instead.

## Reference

### Reference

- [Tool format](https://pr-2-390be2854416.thally.app/reference/tool-format): The one input format SchemaPort accepts — required fields, the supported JSON Schema subset, source file layouts, directory loading, and what is deliberately unsupported.
- [Configuration](https://pr-2-390be2854416.thally.app/reference/configuration): Every key of schemaport.config.json, how it interacts with command-line flags, and a worked example.
- [Diagnostics](https://pr-2-390be2854416.thally.app/reference/diagnostics): The diagnostic shape, the three severity levels, what compile.supported and compile.lossy promise, and why codes rather than messages are the interface you filter on in CI.
- [Exit codes](https://pr-2-390be2854416.thally.app/reference/exit-codes): What each exit code means, what triggers it per command, and why a missing API key is never reported as a schema rejection.
- [Manifest](https://pr-2-390be2854416.thally.app/reference/manifest): The manifest.json that compile writes — every field, a real example, and why it is deterministic enough to commit and review in a pull request.

### TypeScript library

- [Library overview](https://pr-2-390be2854416.thally.app/api/overview): Load, validate, compile and diff canonical tool schemas from TypeScript, without going through the CLI.
- [Provider contract](https://pr-2-390be2854416.thally.app/api/provider-contract): Implement a new SchemaPort target by satisfying one small interface, and let core apply the compilation policy for you.