This looks like hell to review but a lot of it is moving text around, so a visual diff is probably the most straightforward.
The high-level (pun-intended) goal of this PR is to realize the main-schema document is not merely a schema. Its the document that defines the core concepts behind its structured logging, methodology, requirements for loggers and tools, AND a few schema.
Moving the document away from referring to its entire self as a schema, makes it easier to isolate the parts we mostly expect people to extend - the event definitions.
I found it incredibly hard to talk about this with the old terminology of generic event class and specific data. Especially when combined with the concept of "event definition documents". That's been reflected into prior attempts at wrangling the extensibility of events. So I've changed that to abstract Event class and concrete event types. I suspect those won't be that popular either but they work for this old OOP survivor.
The PR isn't 100% complete but it does implement the schema > category > event structure that we seemed to align on, and ports over a lot more from https://github.com/quicwg/qlog/pull/415. If we think this is a suitable direction, putting the finishing touches like IANA policy and updating QUIC/H3 docs isn't that much more work.
This looks like hell to review but a lot of it is moving text around, so a visual diff is probably the most straightforward.
The high-level (pun-intended) goal of this PR is to realize the
main-schemadocument is not merely a schema. Its the document that defines the core concepts behind its structured logging, methodology, requirements for loggers and tools, AND a few schema. Moving the document away from referring to its entire self as a schema, makes it easier to isolate the parts we mostly expect people to extend - the event definitions.I found it incredibly hard to talk about this with the old terminology of generic event class and specific data. Especially when combined with the concept of "event definition documents". That's been reflected into prior attempts at wrangling the extensibility of events. So I've changed that to abstract Event class and concrete event types. I suspect those won't be that popular either but they work for this old OOP survivor.
The PR isn't 100% complete but it does implement the schema > category > event structure that we seemed to align on, and ports over a lot more from https://github.com/quicwg/qlog/pull/415. If we think this is a suitable direction, putting the finishing touches like IANA policy and updating QUIC/H3 docs isn't that much more work.