Feat/schema driven conformance - #119
Merged
Merged
Conversation
`docs/standards/draft-eep-protocol-core-00.md` and
`schemas/v0.1/eep-manifest.json` had drifted until not one field name
matched except `eep_version`:
draft requires publisher_did, endpoints.discovery,
endpoints.subscribe, endpoints.stream,
supported_layers, delivery_methods,
conformance_level
schema requires did, eep_version, layers,
supported_content_types, pqc_ready, x402_enabled
A publisher conformant to the shipped schema fails every MUST in the
Internet-Draft, and vice versa. Nothing in CI noticed, because nothing
compared them. ROADMAP.md targets IETF/W3C submission at v0.2, so this
is the document reviewers would read first.
Direction: the draft is rewritten to match the schema, not the reverse.
The schema is implemented by both middleware packages, both reference
implementations and the compliance CLI; the draft has no
implementations at all. Changing the schema instead would be a breaking
change to a published v0.1 artifact for no protocol benefit.
Changes:
- Layer 1 field table restated against `eep-manifest.json`, with the
`layers` object documented and the rule that at least one Layer 2
endpoint must be populated.
- `endpoints.stream` / `endpoints.subscribe` references replaced with
`layers.layer2_sse` / `layers.layer2_webhook`.
- Envelope section documents `eep_version` (what implementations emit)
instead of `eepversion` / `eepdelivery` (which nothing emits).
- Editor's note recording that the shipped `eep_`-prefixed names violate
the CloudEvents v1.0.2 attribute-naming rule, which excludes the
underscore. This is a real problem that becomes load-bearing in binary
content mode, where attributes become `ce-`-prefixed headers. Recorded
as an open question rather than silently renamed: no implementation
emits the compliant spelling today.
- `scripts/check-draft-schema-parity.mjs` plus a CI job, so this class of
drift is a build failure. The gate parses the draft's delimited field
table and diffs names and required-ness against the schema; verified
by injecting drift and confirming a non-zero exit.
No schema changed, so the types drift gate is a no-op here.
Refs: EEP audit 2026-08 finding A1
Signed-off-by: Ugur Cekmez <ucekmez@gmail.com>
fix(standards): make the IETF draft describe the protocol that ships
There was a problem hiding this comment.
🟡 Changes recommended
The updated draft text still describes POST/SSE endpoints as the literal manifest field names (e.g., layers.layer2_webhook) rather than the URL values stored in those fields, which is ambiguous for implementers.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR introduces a schema-driven conformance check to prevent the Internet-Draft from drifting away from the shipped JSON Schemas, and updates the draft to align its manifest field table with schemas/v0.1/eep-manifest.json.
Changes:
- Add a Node script that parses a delimited manifest table in the draft and verifies it matches
eep-manifest.json(fields + requiredness). - Update the Internet-Draft’s Layer 1 manifest documentation and related Layer 2 / event-envelope wording to match the current schema surface.
- Add a CI job that runs the parity check as a drift gate.
File summaries
| File | Description |
|---|---|
| scripts/check-draft-schema-parity.mjs | New script to compare the draft’s manifest field table against the JSON Schema and fail on drift. |
| docs/standards/draft-eep-protocol-core-00.md | Updates Core-tier manifest fields and related text to match the shipped schema, with markers for automated parity checks. |
| .github/workflows/test.yml | Adds a new “draft ↔ schema parity” CI job to enforce the drift gate. |
Review details
Suppressed comments (1)
docs/standards/draft-eep-protocol-core-00.md:189
- This sentence currently says to POST to
layers.layer2_webhook(the manifest field name) rather than to the URL value in that field. That’s ambiguous for implementers and should explicitly refer to the URL stored in the manifest.
A subscriber MAY register for events by POSTing to
`layers.layer2_webhook` a JSON body conforming to the
`subscription.request.json` schema in {{EEP-SPEC}}. Required fields are
- Files reviewed: 3/3 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| publisher MUST implement at least one of: | ||
|
|
||
| - Server-Sent Events ({{W3C.SSE}}) at `endpoints.stream`, OR | ||
| - Server-Sent Events ({{W3C.SSE}}) at `layers.layer2_sse`, OR |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Scope
Checklist
npm test/pytestin affected packages).Notes for reviewers