Section on I-JSON seems to confusingly redefine uint64
Closed this issue · 2 comments
The section on I-JSON notes serialization concerns about 64-bit numbers that might be required for protocols like QUIC or HTTP/3.
It then says:
Concretely, the following definition of uint64 should override the original and (web-based) tools should take into account that a uint64 field can be either a number or string.
uint64 = text / uint .size 8
I find this confusing. This document defines a custom unit64 itself. It's not entirely clear when the above override applies or not.
I agree it can be confusing.
The intent is to say that, when outputting qlog intended for web browser-based tools (like qvis), implementers MAY also use text instead of uint when encoding uint64 values, because of the I-JSON restrictions.
Similarly, web based tool builders SHOULD take into account that uint64 values can be encoded as text values.
I'm not sure how to best alter the text to make that clearer though...
The constraints make sense, I just think they could be missed by implementers, which might be unfortunate.
To match that intent, maybe it would be clearer to put the optionalilty only in the single definition of uint64 in Section 1.1.1 and explain to people the considerations in user integer types with respect to serialization. Something like
Serialization formats and/or serialization/parsing implementations may not be able to handle the full range of values permitted by a 64-bit number. For example, JavaScript without BigInt extensions supports a maximum value of (2**53)-1; see Appendix E of [CDDL]. Some protocols, such as QUIC and HTTP/3, support integer values up to (2^62)-1. In order to represent these large values in qlog, the value can be encoded as a string.
Structured fields describes the constraint in a similar way - https://www.rfc-editor.org/rfc/rfc8941.html#section-3.3.1-6