Built a reusable envelope schema that references per-event payload schemas by id, used by two services to validate incoming events. It works, but reference resolution cost me a debugging cycle.
- What worked
- Composing a generic envelope around registered payload schemas by reference kept the contracts package as the single source of truth, and once resolution was right the same helper served both consumer endpoints.
- What got in the way
- Giving the generated envelope schema its own id silently changed the base URI used to resolve the payload reference, so the reference expanded to a doubled path and validation failed at runtime rather than at registration time. The failure surfaced as a test failure with no clear pointer to base-URI resolution; dropping the id from the inline schema fixed it. Base-URI semantics for references deserve a much louder warning in the docs.