John Lancaster
114 lines
3.7 KiB
Markdown
114 lines
3.7 KiB
Markdown
# URI Contract
|
|
|
|
This page defines the canonical resource URI contract, template parameter rules, and compatibility policy.
|
|
|
|
## Canonical URI Surface
|
|
|
|
The public, preferred URIs are:
|
|
|
|
1. `resource://catalog/skills_index`
|
|
2. `resource://catalog/skills/{skill_id}`
|
|
3. `resource://skills/{skill_id}/document`
|
|
4. `resource://skills/{skill_id}/references/{ref_id}`
|
|
5. `resource://docs/{path*}`
|
|
|
|
Contract intent:
|
|
|
|
1. Catalog URIs are discovery surfaces.
|
|
2. Skill URIs are the primary per-skill guidance surfaces.
|
|
3. The docs wildcard URI is a direct authored-markdown access surface under `docs/`.
|
|
|
|
## URI Semantics
|
|
|
|
### `resource://catalog/skills_index`
|
|
|
|
1. Returns a compact list of skill records for discovery.
|
|
2. Contains one entry per `skill_id`.
|
|
3. Includes enough metadata for client-side selection, at minimum `id`, `name`, `description`, `tags`, and `capabilities`.
|
|
|
|
### `resource://catalog/skills/{skill_id}`
|
|
|
|
1. Returns one normalized record for `skill_id`.
|
|
2. Includes the canonical document URI and declared reference ids.
|
|
3. Returns not found when `skill_id` does not exist.
|
|
|
|
### `resource://skills/{skill_id}/document`
|
|
|
|
1. Returns the canonical `SKILL.md` authored content for that skill.
|
|
2. `skill_id` must satisfy the stable skill id rules from the content contract.
|
|
|
|
### `resource://skills/{skill_id}/references/{ref_id}`
|
|
|
|
1. Returns one reference document declared in the skill frontmatter references manifest.
|
|
2. `ref_id` is the stable public handle for that reference document.
|
|
|
|
### `resource://docs/{path*}`
|
|
|
|
1. Returns authored markdown at a normalized relative path under `docs/`.
|
|
2. Supports nested paths via RFC6570 wildcard expansion.
|
|
3. Typical examples include `index.md`, `usage.md`, `skills/<skill-id>/SKILL.md`, and `skills/<skill-id>/references/<file>.md`.
|
|
|
|
## Template Parameter And Validation Rules
|
|
|
|
### `skill_id`
|
|
|
|
1. Lowercase kebab-case.
|
|
2. Must satisfy the stable skill id rules from the content contract.
|
|
|
|
### `ref_id`
|
|
|
|
1. Lowercase kebab-case.
|
|
2. Must be declared in the skill's references manifest.
|
|
|
|
### `path*`
|
|
|
|
1. Relative POSIX path only.
|
|
2. No leading slash.
|
|
3. No `..` traversal segments.
|
|
4. Resolves only inside `docs/`.
|
|
5. Markdown-only in the end state, meaning `.md` files.
|
|
|
|
## URI Versioning Policy
|
|
|
|
Default rule:
|
|
|
|
1. Keep URIs unversioned by default.
|
|
2. Allow URI and payload updates when they improve clarity or implementation simplicity.
|
|
|
|
Breaking-change rule:
|
|
|
|
1. Breaking changes use direct replacement of the canonical URI family.
|
|
2. No compatibility aliases or dual URI families are maintained.
|
|
|
|
FastMCP version metadata usage:
|
|
|
|
1. Resource `version` metadata may be used for implementation and version discovery.
|
|
2. URI readability and maintainability remain the primary contract.
|
|
|
|
## Reference Id Compatibility Policy
|
|
|
|
`ref_id` is the public identifier for a reference document, separate from file path.
|
|
|
|
Rules:
|
|
|
|
1. Prefer keeping `ref_id` stable when practical.
|
|
2. File paths may change without URI churn as long as the mapped `ref_id` still resolves.
|
|
3. If a reference is renamed, introduce a new `ref_id` and treat the old one as retired.
|
|
4. Avoid reusing retired `ref_id` values for unrelated content.
|
|
|
|
## Invariants
|
|
|
|
This contract guarantees:
|
|
|
|
1. One canonical URI pattern per core capability surface.
|
|
2. Fast, low-friction URI evolution through direct replacement of canonical URIs.
|
|
3. A single canonical catalog URI family with no alias maintenance overhead.
|
|
4. Reference mappings can evolve with minimal churn.
|
|
|
|
## Non-Goals
|
|
|
|
This contract does not define:
|
|
|
|
1. Implementation-specific transform wiring details, such as `VersionFilter`, mounts, or provider composition.
|
|
2. Migration script mechanics for auto-generating aliases.
|
|
3. Authorization policy design for URI-level access control. |