[Openid-specs-risc] openid/sharedsignals: Comment created on issue 338

[github at oidf.org]

openid/sharedsignals event

Issue Comment created on issue 338
Issue Title: Event profile versioning
https://github.com/openid/sharedsignals/issues/338

Comment: Notes from the call on 2026-07-07: - (Atul) Created the issue earlier today: [Issue #338](https://github.com/openid/sharedsignals/issues/338) - (Yair) We shouldn't change the base URL for the events that don't change. - (Apoorva) I agree with Yair. We should think harder whether we should check if we should version the spec or the specific event. - (Yair) Let's say we are 5 versions ahead. We now have 40 / 50 URIs, of which only a few will have changed. - (Atul) So will a new spec have only the changed events? - (Yair) Each spec will have all events, just that if an event hasn't changed, we shouldn't change the URIs of events that haven't changed. - (Apoorva) The event URI has a version, and it will reflect the latest change. - (Yair) The spec approval is important. In a future spec, we might even drop an existing event. So it is important for a spec to stand by itself. - (Apoorva) So to clarify: The event version will be different than spec version. The spec will be ratified, but the event URI doesn't change if the event description hasn't changed between versions. - (Yair and Atul) Yes - (Apoorva) Does adding a version number in the event URL break any implementations? - (Thomas) IMO if we had a version number in the URI path, then it would break the existing code. Section 3 of the CAEP spec specifies a base URI, but if we add it after the base path, then we might have more compatibility. If we add a version component after the base URL, all the matching might break. - (Thomas) Therefore, I'd like to specify a URL parameter, e.g. "https://schemas.openid.net/secevent/caep/event-type/session-presented?v=1.0" - (Atul) We won't be changing the base URL for the 1.0 spec. - (Thomas) The query parameter enables backward compatibility in a way that inserting a version number in the path won't. - (Thomas) I've seen code that determines a handler based on the base URI. - (Apoorva) We should check the URI spec to see if there is any recommendation. - (Yair) I'm not sure about using query parameters - (Thomas) It would help for implementers to understand that these are variations of the same event, instead of treating them as new events. - (Atul) The new CAEP spec can clarify Section 3 to have the new base URI - (Atul) It might be better to actually have code not treat a new event as an old event, because it might actually not expect some values that the new event introduces, and hence not be able to handle it. - (Thomas) I can see the merit in that, but implementations will have to replicate the logic between versions. The URI matches might point to the same handlers - (Yair) The way I think about it: Right now we have 8 events, and let's say we add a new version of the device compliance events. You would need to declare all 9 (8 old +1 new version). It is going to be 9 different event types. - (Thomas) I agree partially, because if you add just one new event, then you will have to support the 9 events. Adding a version number at the end like so: "https://schemas.openid.net/secevent/caep/event-type/new-event/1.1" would work better - (Yair) I'm not against using this method. Since everyone who implements the new event would look for the new URI. If you wanted to make just a small change, and it was backward compatible, would you want to change the event type? - (Atul) I prefer the placing of the version number in the base URI rather than after the event type - (Thomas) In a new version of the CAEP spec, we could even allow older events to have a base URI version number (i.e. 1.0) - (George) I think the critical factor is that new versions of an event of the same name (type) must be considered a brand new event. If we agree to that, then the rest doesn't matter as much. If instead we want the v1.1 of the same event to be partially processible by older code, then it would add a lot of complexity of the versioning model. Treating each new version as a completely new event type makes implementation cleaner. If a developer figures out how to optimize code reuse for multiple event versions, then that's an implementation detail. - (Thomas) Under this logic, it would be possible to completely change the logic of an event between versions. - (George) As the spec development body, we should be responsible for making sure that this doesn't happen. - (Matt in chat) many APIs like Stripe use Header based versioning. For example, “Stripe Version: 2024-06-20”. If we are doing it in the URL I agree with George that we shouldn’t be doing minor versions in the URL and everything at a minor or patch level should be backwards compatible and not represented in the URL. - (Yair) I agree with George. If we start calling a "dog" a "cat", then there should be a good reason why the WG decided to do that. - (Thomas) This all falls apart if people need to determine from the event type how to structure the various fields. We don't publish explicit schemas right now. Perhaps that would make it easier. We could make schemas mandatory when inrtoducing new events. - (Atul) We can look into creating schemas for existing events (and new events) - (Thomas) In SSF 1.1, perhaps we can have a way to discover event schemas. - (Atul) I observe that SSF actually doesn't even acknowledge the existence of profiles, and provides no opinion on versioning them. Perhaps it should specify how to version profiles, so that we don't have to do it in each profile spec.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openid.net/pipermail/openid-specs-risc/attachments/20260707/f49a9c3c/attachment-0001.htm>