From e4288d336643d9fa93348ccf17d45914bc989ecb Mon Sep 17 00:00:00 2001 From: Samuel M Smith Date: Tue, 30 Jan 2024 11:15:33 -0700 Subject: [PATCH] changed version string description to refere to defintion in CESR specifiction --- spec/spec.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/spec/spec.md b/spec/spec.md index e8c6bf0..9d27998 100644 --- a/spec/spec.md +++ b/spec/spec.md @@ -608,17 +608,14 @@ https://github.com/trustoverip/tswg-keri-specification/issues/20 ##### Version string field -The version string, `v`, field MUST be the first field in any top-level KERI field map. It provides a regular expression target for determining a serialized field map's serialization format and size (character count) that constitutes a KERI message body. A stream parser may use the version string to extract and deserialize (deterministically) any serialized stream of KERI message bodies in a set of KERI field maps. Each KERI message body in a stream may use a different serialization type. +The version string, `v`, field shall be the first field in any top-level KERI field map encoded in JSON, CBOR, or MGPK as a message body [[spec: RFC4627]] [[spec: RFC4627]] [[ref: CBOR]] [[ref: RFC8949]] [[ref: MGPK]]. It provides a regular expression target for determining a serialized field map's serialization format and size (character count) constituting an KERI message body. A stream parser may use the version string to extract and deserialize (deterministically) any serialized stream of KERI message bodies. Each KERI message body in a stream may use a different serialization type. The format for the version string field value is defined in the CESR specification [[ref: CESR]]. -The format of the version string is `KERIVVVKKKKBBBB_`. It is 16 characters in length and is divided into five parts: protocol, version, serialization kind, serialization length, and terminator. The first four characters, `KERI` indicate the protocol. The CESR encoding standard supports multiple protocols, `KERI` being one of them. The next three characters, `VVV` provide in Base64 notation the major and minor version numbers of the version of the KERI protocol specification. The first `V` character provides the major version number and the final two `VV` characters provide the minor version number. For example, `CAA` indicates major version 2 and minor version 00 or in dotted-decimal notation, i.e., `2.00`. Likewise, `CAQ` indicates major version 2 and minor version decimal 16 or in dotted-decimal notation `1.16`. The version part supports up to 64 major versions with 4096 minor versions per major version. The next four characters, `KKKK` indicate the serialization kind in uppercase. The four supported serialization kinds are `JSON`, `CBOR`, `MGPK`, and `CESR` for the JSON, CBOR, MessagePack, and CESR serialization standards, respectively [[spec: RFC4627]] [[spec: RFC4627]] [[ref: CBOR]] [[ref: RFC8949]] [[ref: MGPK]] [[ref: CESR]]. The next six characters provide in Base64 notation the total length of the serialization, inclusive of the version string and any prefixed characters or bytes. This length is the total number of characters in the serialization of the KERI message body. The maximum length of a given KERI message body is thereby constrained to be *224 = 16,777,216* characters in length. The final character `_` is the version string terminator. This enables later versions of KERI to change the total version string size and thereby enable versioned changes to the composition of the fields in the version string while preserving deterministic regular expression extractability of the version string. - -Although a given KERI message body serialization kind may have characters or bytes such as field map delimiters or framing codes that appear before, i.e., prefix the version string field in a serialization, the set of possible prefixes for each of the supported serialization kinds is sufficiently constrained by the allowed serialization protocols to guarantee that a regular expression can determine unambiguously the start of any ordered field map serialization that includes the version string as the first field value. Given the length from the version string, a parser may then determine the end of the serialization so that it can extract the full KERI message body from the stream without first deserializing it. This enables performant stream parsing and off-loading of KERI streams that include any or all of the supported serialization types. +The protocol field, `PPPP` value in the version string shall be `KERI` for the KERI protocol. The version field, `VVV`, shall encode the current version of the KERI protocol [[ref: CESR]]. ##### Legacy version string field format -Compliant KERI version 2.XX implementations shall support the old KERI version 1.XX version string format to properly verify KELs created with 1.XX format events. +Compliant KERI version 2.XX implementations shall support the old KERI version 1.x version string format to properly verify message bodies created with 1.x format events. The old version 1.x version string format is defined in the CESR specification [[ref: CESR]]. The protocol field, `PPPP` value in the version string shall be `KERI` for the KERI protocol. The version field, `vv`, shall encode the old version of the KERI protocol [[ref: CESR]]. -The format of the version string for KERI 1.XX is `KERIvvKKKKllllll_`. It is 16 characters in length and is divided into five parts: protocol, version, serialization kind, serialization length, and terminator. The first four characters, `KERI,` indicate the protocol. The CESR encoding standard supports multiple protocols, `KERI` being one of them. The next two characters, `vv` provide the major and minor version numbers of the version of the KERI protocol specification in lowercase hexadecimal notation. The first `v` provides the major version number, and the second `v` provides the minor version number. For example, `01` indicates major version 0 and minor version 1 or in dotted-decimal notation `0.1`. Likewise, `1c` indicates major version 1 and minor version decimal 12 or in dotted-decimal notation `1.12`. The next four characters, `KKKK` indicate the serialization kind in uppercase. The four supported serialization kinds are `JSON`, `CBOR`, `MGPK`, and `CESR` for the JSON, CBOR, MessagePack, and CESR serialization standards, respectively [[spec: RFC4627]] [[spec: RFC4627]] [[ref: CBOR]] [[ref: RFC8949]] [[ref: MGPK]] [[ref: CESR]]. The next six characters provide in lowercase hexadecimal notation the total length of the serialization, inclusive of the version string and any prefixed characters or bytes. This length is the total number of characters in the serialization of the KERI message body. The maximum length of a given KERI message body is thereby constrained to be *224 = 16,777,216* characters in length. For example, when the length of serialization is 384 decimal characters/bytes, the length part of the version string has the value `000180`. The final character `_` is the version string terminator. This enables later versions of KERI to change the total version string size and thereby enable versioned changes to the composition of the fields in the version string while preserving deterministic regular expression extractability of the version string. ##### SAID (Self-Addressing identifier) fields