@@ -32,20 +32,22 @@ the following form, called the "JSON envelope":
3232
3333See [ Protocol] ( protocol.md ) for a definition of parameters and functions.
3434
35- Arbitrary binary data can be encode in [ Base64] ( https://tools.ietf.org/html/rfc4648 ) ,
36- as a unicode string and enclosed in the envelope using the ` payload ` key.
37- Either standard or URL-safe encoding is allowed.
38-
39- However, if the serialized payload body is a text string, it can * instead* be
40- encoded in [ UTF-8] ( https://tools.ietf.org/html/rfc3629 ) and enclosed in the
41- envelope using the ` payloadUtf8 ` key. The UTF-8 encoding has a lower overhead
42- than Base64 for texts, and is more friendly for compression algorithms.
43-
44- Note:
45-
46- 1 . Use either the ` payload ` or ` payloadUtf8 ` key in an envelope, not both;
47- 2 . The choice of payload encoding does not impact
48- [ the signing or the signatures] ( protocol.md#signature-definition ) .
35+ Exactly one of ` payload ` or ` payloadUtf8 ` MUST be set:
36+
37+ - ` payload ` supports arbitrary SERIALIZED_BODY.
38+ [ Base64Encode()] ( https://tools.ietf.org/html/rfc4648 ) transforms a byte
39+ sequence to a Unicode string. Base64 has a fixed 33% space overhead but
40+ supports payloads that are not necessarily valid UTF-8. Either standard or
41+ URL-safe encoding is allowed.
42+
43+ - ` payloadUtf8 ` only supports valid
44+ [ UTF-8] ( https://tools.ietf.org/html/rfc3629 ) SERIALIZED_BODY. ` Utf8Decode() `
45+ converts that UTF-8 byte sequence to a Unicode string. Regular JSON string
46+ escaping applies, but this is usually more compact and amenable to
47+ compression than Base64.
48+
49+ Note: The choice of ` payload ` vs ` payloadUtf8 ` does not impact the
50+ [ the signing or the signatures] ( protocol.md#signature-definition ) .
4951
5052### Multiple signatures
5153
0 commit comments