-
Notifications
You must be signed in to change notification settings - Fork 12
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Versioning for additional schema #283
Comments
This adds the additional_schema field to QlogFile defined in the main schema. The purpose being to explicitly identify the schema used for additional events (possibly) included in qlog traces. The field is free-forma and could be anything. We could go XML style and require a URL. I've started by just proposing that we reference the document name: for I-Ds, this makes it easy to manage iterative versions for RFCs, these have a canonical source already. If an RFC update is published and an implementation switches to it, we can change easily. Closes #283
This adds the additional_schema field to QlogFile defined in the main schema. The purpose being to explicitly identify the schema used for additional events (possibly) included in qlog traces. The field is free-forma and could be anything. We could go XML style and require a URL. I've started by just proposing that we reference the document name: for I-Ds, this makes it easy to manage iterative versions for RFCs, these have a canonical source already. If an RFC update is published and an implementation switches to it, we can change easily. Closes #283
As discussed on the call yesterday, everyone generally likes this concept on how to tackle versioning. Additionally, it can help replace One thing I personally did not really love in current PR #284 is that we use a separate approach for the main schema version (indicated via Put differently, this is what the PR currently proposes:
While a more consistent option would be:
Downsides I could find:
I think those downsides are sufficient to go with the original proposal, but in that case, I'd rename |
So the issue with a list of name and value tuples is, you'd need to go to the effort of defining naming strategy and a registry to hold those names to avoid conflicts. That's overhead I'd like to avoid.
I'd stuck with something like |
Thinking about this more and comparing with other similar projects, I think keeping the original proposal is fine, but that we should probably use the term "namespace" instead of "schema" (seems to be used quite consistently across XML, YAML, even CDDL 2.0). Thus:
|
qlog doesn't define the term namespace anywhere, so it would have to do that. Realistically, I think that pushes us towards making this all much more explicit. I.e. providing guidelines defining namespaces and registering them in a new IANA registry. That's not far off what we talked about earlier with the tuple suggestion but I don't see a good reason to have a separate version field. |
Discussed on the call: namespaces has some implicit connotations that imply things like versioning and uniqueness, which we don't want because they need IANA support. Keep |
I don't love naming protocol elements after drafts or RFCs ... it gets very confusing if you ever publish a compatible update of a spec. (E.g.: what RFC defines the content of the media format It's maybe moderately annoying, but I'd suggest a |
That's a fair point Lennox. Have you got any links to resources for registering and maintaining such a namespace? |
The model I'm thinking of is the URIs identifying RTP Header Extensions, RFC 8285 - that's probably a good starting point to base yourself on. (Section 5 and Section 10.1.) |
thanks! |
This adds the additional_schema field to QlogFile defined in the main schema. The purpose being to explicitly identify the schema used for additional events (possibly) included in qlog traces. The field is free-forma and could be anything. We could go XML style and require a URL. I've started by just proposing that we reference the document name: for I-Ds, this makes it easy to manage iterative versions for RFCs, these have a canonical source already. If an RFC update is published and an implementation switches to it, we can change easily. Closes #283
This adds the additional_schema field to QlogFile defined in the main schema. The purpose being to explicitly identify the schema used for additional events (possibly) included in qlog traces. The field is free-forma and could be anything. We could go XML style and require a URL. I've started by just proposing that we reference the document name: for I-Ds, this makes it easy to manage iterative versions for RFCs, these have a canonical source already. If an RFC update is published and an implementation switches to it, we can change easily. Closes #283
Alternative to #284. This follows Lennox's suggestion to take influence from RFC 8285 and reference extension schema according to a URI. IETF documents can use URNs under a formal namespace, and as such we register a new `qlog` URN Sub-namespace for Registered Protocol Parameter Identifiers. Fixes #283
We presently have 3 documents: main schema, quic schema, HTTP/3 and QPACK schema.
We presently have 1 version field
qlog_version
to express changes in any of these documents.We make efforts to keep these things in lock step, but the relationship is quite implicit and not explicitly stated. That's not brilliant and adds some friction.
One proposal I have is to articulate the schema(s) used in the log. I don't think we need to go as far as XML does (e.g. https://www.oreilly.com/library/view/xml-in-a/0596007647/re168.html) but we could just include the I-D or RFC name as a string. Then each additional schema document can express what version of qlog main schema it depends on. I'll write this up as a PR.
The text was updated successfully, but these errors were encountered: