Separate protocol specification from SDK implementation into distinct repositories

[mojoatomic]

Separate protocol specification from SDK implementation into distinct repositories

Status and separation of concerns (updated 2025-10-03)

• Protocol work tracked in mojoatomic/rdcp-protocol:
  • Compliance Kit: Compliance kit for cross-language self-certification rdcp-protocol#3
  • Version mapping: Version mapping: SDK ↔ protocol compatibility matrix rdcp-protocol#5
  • Governance (CODEOWNERS + RFC template): Governance: CODEOWNERS and RFC template for protocol changes rdcp-protocol#6
• SDK migration tracked in this repo (rdcp):
  • Tracker: Separate protocol specification from SDK implementation into distinct repositories #111 (this issue)
  • Update SDK links/wiki to point to rdcp-protocol: Update SDK links/wiki to point to rdcp-protocol docs #116
  • Announcement + deprecation notice for the repo split: Announcement + deprecation notice for repo split #117

Checklist (updated)

• Create rdcp-protocol repo (Apache-2.0, CI)
• Move protocol docs
• Generate/publish JSON Schemas
• Add compliance kit (v1.0 Phase 1)
• Add docs site (MkDocs + mike)
• Submodule rdcp-protocol under protocol/
• Update SDK links and add stub wiki pages (see Update SDK links/wiki to point to rdcp-protocol docs #116)
• Version mapping doc (SDK versions → protocol versions) (see Version mapping: SDK ↔ protocol compatibility matrix rdcp-protocol#5)
• CODEOWNERS and RFC template in rdcp-protocol (see Governance: CODEOWNERS and RFC template for protocol changes rdcp-protocol#6)
• Announcement + deprecation notice in rdcp (see Announcement + deprecation notice for repo split #117)

Original problem/proposal/benefits are preserved in the issue history and prior comments. This top section reflects current status and cross-repo tracking.

[mojoatomic]

Status update (Context7-aligned)

Protocol repo delivery (rdcp-protocol)

• Repo created and structured (Apache-2.0)
• Protocol docs moved and expanded (spec + implementation guide + error codes + compliance report placeholder)
• Versioned JSON Schemas (v1) published under schema/v1/* with canonical $id
• OpenAPI 3.1 spec (v1) added at docs/api/v1/openapi.json
• Docs site with MkDocs Material + mike (versioned)
• API Reference (Redoc) and API Playground (Swagger UI) integrated
• CI: Redocly lint for OpenAPI; AJV validation for JSON Schemas; link-check; docs deploy to gh-pages
• Stable URLs: /api (redirect to /latest/api/), /latest/api/reference, /latest/api/playground
• Submodule wired into SDK repo under protocol/ (already present)

Follow‑ups proposed in this issue

• Compliance kit (fixtures + assertions + instructions)
• Version mapping doc (SDK ↔ protocol)
• Governance in protocol repo: CODEOWNERS, CONTRIBUTING, SECURITY, RFC template
• SDK repo: update docs/wiki links; add stub pages that point to protocol site to avoid link rot
• Release/process docs: protocol v1.x additive-only; how we publish new versions (schemas + OpenAPI + docs)
• Announcement in SDK repo (README + CHANGELOG link to protocol site)

References

• Protocol site: https://mojoatomic.github.io/rdcp-protocol/
• API Reference (Redoc): https://mojoatomic.github.io/rdcp-protocol/latest/api/reference/
• Playground (Swagger UI): https://mojoatomic.github.io/rdcp-protocol/latest/api/playground/
• OpenAPI (v1): https://mojoatomic.github.io/rdcp-protocol/latest/api/v1/openapi.json

If you want, I can open separate issues in rdcp-protocol for the remaining checklist (compliance kit, version mapping, governance) and link them here for tracking.

[mojoatomic]

Status update (2025-10-03)

Work completed in mojoatomic/rdcp-protocol that advances this issue:

• Docs site and versioning

  • mkdocs-material + mike versioning live; GitHub Pages publishing confirmed (gh-pages).
  • Homepage API Reference link fixed; version-aware embeds for Redoc/Swagger UI.
  • Redirect /api/ -> /latest/api/ added post-deploy.
  • Custom domain configured (rdcp.dev); note: ensure CNAME on gh-pages if not managed by Settings.

• OpenAPI + API pages

  • API Reference and Playground pages added; Redoc embed fixed ().
  • Download link for OpenAPI JSON enabled; Apache-2.0 license notices added.
  • x-tagGroups and multi-language code samples (curl, Python, Go) added.

• Compliance Kit v1.0 (Phase 1)

  • compliance-kit/v1.0 with fixtures, sequences, assertions, and validation script.
  • CI workflow validates fixtures with Ajv; local script improved to preload schemas and resolve $refs.

• JSON Schemas

  • Published versioned schemas under schema/v1 with canonical $id.
  • Strict mkdocs build passes with schema pages and links.

• CI and workflows

  • Docs deploy workflow supports manual dispatch for on-demand republish.
  • Validation workflows for schemas, OpenAPI, and compliance fixtures are green.

Mapping to the checklist:

• Create rdcp-protocol repo (Apache-2.0, CI)
• Move protocol docs
• Generate/publish JSON Schemas
• Add compliance kit
• Add docs site (MkDocs)
• Submodule rdcp-protocol under protocol/ (confirmed)
• Update SDK links and add stub wiki pages in rdcp
• Version mapping doc (SDK versions → protocol versions)
• CODEOWNERS and RFC template in rdcp-protocol
• Announcement + deprecation notice in rdcp

Proposed next steps:

1. Create/verify stub wiki pages in rdcp pointing to protocol docs (avoid link rot).
2. Add a short "Version mapping" page (SDK ↔︎ protocol) in rdcp-protocol.
3. Add CODEOWNERS and an RFC proposal template to rdcp-protocol.
4. Post an announcement in rdcp: link to new protocol site; outline migration and stable URLs.

If desired, I can open separate issues for the four remaining items and link them here, or I can update the issue body checklist directly to reflect the completed items.