feat(spec): add CEP-15 Common Tool Schemas#14
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
ContextVM-org
changed the title
| } | ||
| ``` | ||
|
|
||
| **Tag Format**: `["D", "<schema-hash>", "<tool-name>"]` - Indicates this server defines a common tool schema. |
There was a problem hiding this comment.
What does it mean for a server to "define" a tool schema? if these schemas are deterministically hashed then it shouldn't matter which pubkey (server) defines them
There was a problem hiding this comment.
Hey! The original idea behind this distinction was to propose a native coordination layer, bootstrapping, and a signal for trust/reputation. However, after considering it carefully and keeping in mind adversarial scenarios as well, we agree that there is no need for this distinction or the authoritative mechanism. We have just committed a revision of the spec removing the 'D' tag.
| "outputSchema": { | ||
| // SHOULD match reference schema if present | ||
| }, | ||
| "_meta": { |
There was a problem hiding this comment.
Similar question to before. Whats the purpose of referencing where the schema is defined if its addressed by its hash?
There was a problem hiding this comment.
Removing this is not possible at the server level, as even if a server implements a common schema, it still needs to define input and output schemas. Keeping them also serves as a verification mechanism that can be used to assert compliance with the schema hash
| import { createHash } from "crypto"; | ||
|
|
||
| const toolSchema = { | ||
| name: "translate_text", |
There was a problem hiding this comment.
I'm not sure its necessary to hash the name with the input / output schema. if the purpose of the hash is to discover tools that input -> output then the name seems to be unnecessary and would cause the hashes to be different if the tools where named slightly differently
There was a problem hiding this comment.
We decided to include the name field in the contract as it is a normative field used to build the calls for a specific method. On the other hand, we consciously chose not to include the title and description fields of the tools to allow flexibility and enable operators to define them freely while maintaining the same schema hash
Remove reference server pattern and simplify schema discovery to use direct schema hashes without authoritative definers. Update announcement tags to "I" for implemented schemas, eliminating "D" tags and reference pubkey requirements. Enhance hash calculation notes and verification flow for better interoperability.
|
It would be nice if the |
Thanks you for the feedback, and I apologize for the delayed response @vitorpamplona, these days have been quite hectic. If I understood correctly, making the I tag a NIP-73 reference would mean declaring them in the NIP-73 document so that CVM servers can be referenced by the nips tags right? I cannot see any clear benefit, right now. Could you point us to why you think it would be beneficial for this specification? I'm not sure if treating the common schema hash as an external reference makes sense. It does make some sense, but currently cannot see any specific benefit, we can change our mind, so please share your rationale. Thanks |
|
NIP-73 serves as base to link external content into Nostr and make it part of the ecosystem. For instance, you can have NIP-22 comments and NIP-25 reactions about any NIP-73 identifier. It's just a common way of encoding different identifiers in one tag to make it indexable by relays. In that way, people can vote, follow, and discuss schemas directly. |
Revise CEP-15 to use NIP-73 compliant 'i' and 'k' tags instead of 'I' for schema discovery, update examples and queries accordingly, and add NIP-73 as a dependency. Update CEP-6 to reference CEP-15 for tools list announcements and add it as a dependency.
|
Thanks @vitorpamplona we've just updated the proposal, now it uses NIP-73 Compliant Tags: Replaced uppercase I tags with lowercase i tags and added k tags with value "io.contextvm/common-schema". There is also some comments about this integration in the updated spec. Please let us know if this looks good for you 👍 |
|
This is a very interesting proposal. One thing I wanted to clarify is the hashing boundary for canonical schema identification. The draft says Would it make sense to define a schema-normalization rule before JCS hashing, so semantically identical schemas do not diverge just because providers use different documentation text? |
|
Hey @abhayguptas, thanks for chiming in. Yes, you’re right, the current draft is a bit ambiguous about that. It makes sense to apply a narrow normalization before hashing that recursively removes these documentation oriented fields from the input and output schemas. I’ll update the draft now. |
Add schema normalization step to CEP-15 that removes JSON Schema `title` and `description` keywords before hash calculation, enabling compatible tool definitions from different providers to produce identical schema hashes while preserving documentation flexibility.
|
Following up on our discussion regarding the hashing boundaries in CEP-15, I wanted to document a few edge cases that could cause functionally identical tool schemas to produce divergent hashes. 1. Hash Inconsistency from Non-Functional FieldsCurrently, the draft specifies removing Because JCS (RFC 8785) does not delete fields, if Server A includes Proposal: We should expand the normalization step to explicitly strip 2.
|
…anded field exclusions Adds hash payload boundary definition, requires self-contained schema representation for $ref, expands normalization to exclude examples, default, deprecated, readOnly, writeOnly, and x-* vendor fields. Updates client conformance verification steps and implementation guidance.
|
Thanks for the review. We updated the draft to address these edge cases.
Let me know what do you think @abhayguptas |
|
Thanks for the quick update! I just pulled and reviewed the commit. The expanded normalization rules (stripping examples, default, x-*, etc.) and the self-contained $ref requirement look perfect and completely solve the edge cases. I also really like the approach for discovery. Attaching the i and k tags directly to the tools/list response event is a great middle-ground—it keeps the CEP-35 transport layer clean from bloat while still giving clients fast event-level discovery. This looks rock solid to me! 🙂 |
|
Great! Would you like to update your pr with this changes covering the edge cases so we can move forward? |
|
Hey! I've updated the PRs based on our recent review. |
4 participants
Abstract
This CEP establishes a standard for defining and discovering common tool schemas in ContextVM. It enables interoperability by allowing multiple servers to implement standardized tool interfaces that clients can recognize and use consistently. Using MCP's
_metafield, RFC 8785 for deterministic hashing, and CEP-6 announcements for discovery, this creates a marketplace where users can choose between multiple providers implementing the same standard tool interface.Discussion and more info in the related issue