Merge pull request #1 from marenamat/mm-ip

Updates on IP address and prefix representation
Discussion of intermediates

draft-bormann-cbor-yang-standin.md

@@ -40,6 +40,7 @@ author:
 
 normative:
   RFC9254: yang-cbor
+  RFC9164: cbor-ip
   I-D.schoenw-netmod-rfc6991-bis: legacy-bis
   RFC5952:
   RFC8943: date
@@ -87,14 +88,36 @@ Stand-in tag:
   legacy representation in a more efficient format (e.g., using binary
   data).
 
+Encoder:
+: The party which generates (sends) CBOR data described by YANG.
+
+Intermediate Encoder:
+: An encoder which isn't the original author of the data, converting it
+  from legacy representation.
+
+Decoder:
+: The party which receives and parses CBOR data described by YANG.
+
+Intermediate Decoder:
+: A decoder which isn't the final recipient of the data, converting it
+  to legacy representation.
+
+Data Transfer:
+: A series of actions, generally beginning by data origination, encoding,
+  continuing by optional intermediate transcoding, sending and receiving,
+  and finally decoding and consuming.
+
 Round Trip:
-: A pair of conversions from a legacy representation to a stand-in tag
-  and back to a legacy representation.
-  By definition of these conversions, a round trip needs to retain the
-  semantic information of the original legacy representation.
+: Part of a data transfer between an encoder generating CBOR data with
+  stand-in tags and a decoder parsing the data.
+
+Legacy Round Trip:
+: A Round Trip where the encoder is an intermediate encoder or the decoder is
+  an intermediate decoder and any of these converts from or to the
+  legacy representation.
 
 Unambiguous Round Trip:
-: A Round Trip that provides exactly the same legacy representation
+: A Legacy Round Trip that provides exactly the same legacy representation
   (not just semantically equivalent).
   The stand-in tag is also said to "unambiguously stand in" for the
   legacy representation.
@@ -140,52 +163,141 @@ Tag 100 {{-date}} can unambiguously stand in for all `date-no-zone` values.
 
 YANG type | base type | specification | stand-in
 ip-address | union | {{-yang-types}} | (see union)
-ipv4-address | string | {{-yang-types}} | tag 52
 ipv6-address | string | {{-yang-types}} | tag 54
+ipv4-address | string | {{-yang-types}} | tag 52
 ip-address-no-zone | union | RFC 6991 | (see union)
-ipv4-address-no-zone | ipv4-address | RFC 6991 | tag 52
 ipv6-address-no-zone | ipv6-address | RFC 6991 | tag 54
+ipv4-address-no-zone | ipv4-address | RFC 6991 | tag 52
 ip-address-link-local | union | {{-legacy-bis}} | (see union)
-ipv4-address-link-local | ipv4-address | {{-legacy-bis}} | tag 52
 ipv6-address-link-local | ipv6-address | {{-legacy-bis}} | tag 54
+ipv4-address-link-local | ipv4-address | {{-legacy-bis}} | tag 52
 ip-prefix | union | {{-yang-types}} | (see union)
-ipv4-prefix | string | {{-yang-types}} | tag 52
 ipv6-prefix | string | {{-yang-types}} | tag 54
+ipv4-prefix | string | {{-yang-types}} | tag 52
 ip-address-and-prefix | union | {{-legacy-bis}} | (see union)
-ipv4-address-and-prefix | string | {{-legacy-bis}} | tag 52
 ipv6-address-and-prefix | string | {{-legacy-bis}} | tag 54
+ipv4-address-and-prefix | string | {{-legacy-bis}} | tag 52
 {: title="Legacy representations in ietf-yang-types"}
 
-TO DO: Define usage of tags 54 and 52 for the cases we actually
-support.
-Addresses that have zones given cannot use tag 54/52.
-Addresses with leading zeros cannot use tag 54/52.
-Addresses that do not comply with {{RFC5952}} cannot use tag 54.
+An intermediate encoder MAY normalize IPv6 addresses and prefixes that do not comply with {{RFC5952}}
+but can be converted into the stand-in representation.
+For example, IPv6 address written as 2001:db8:: is the same as 2001:0db8::0:0 and both would
+be converted to `54(h'20010db8000000000000000000000000')`, anyway only the
+first one complies with {{RFC5952}}. The encoder MAY refuse to convert the
+latter one.
+
+If the schema specifies
+`ip-prefix`, an intermediate encoder MAY normalize prefixes with non-zero bits after the prefix end.
+For example, if the legacy representation of `ipv6-prefix` is 2001:db8:1::/40, the encoder
+may either refuse it as malformed or convert it to 2001:db8::/40 and represent
+as `54([40, h'20010db8'])`.
+
+The encoder implementation should be clear about which normalizations are employed and how.
+
+Adapted examples from {{-cbor-ip}}:
+
+Stand-in representation of IPv6 address 2001:db8:1234:deed:beef:cafe:face:feed
+is `54(h'20010db81234deedbeefcafefacefeed')`.
+
+CBOR encoding of stand-in (19 bytes):
+
+``` cbor-pretty
+D8 36                                  # tag(54)
+   50                                  # bytes(16)
+      20010DB81234DEEDBEEFCAFEFACEFEED
+```
+
+CBOR encoding of legacy representation (40 bytes):
+
+``` cbor-pretty
+78 26                                   # text(38)
+   323030313A6462383A313233343A646565643A626565663A636166653A666163653A66656564
+```
+
+Stand-in representation of IPv6 prefix 2001:db8:1234::/48 is
+`54([48, h'20010db81234'])`.
+
+CBOR encoding of stand-in (12 bytes):
+
+``` cbor-pretty
+D8 36                 # tag(54)
+   82                 # array(2)
+      18 30           # unsigned(48)
+      46              # bytes(6)
+         20010DB81234 # " \u0001\r\xB8\u00124"
+```
+
+CBOR encoding of legacy representation (19 bytes):
+
+``` cbor-pretty
+72                                      # text(18)
+   323030313A6462383A313233343A3A2F3438 # "2001:db8:1234::/48"
+```
+
+Stand-in representation of IPv6 link-local address fe80::0202:02ff:ffff:fe03:0303/64%eth0 is
+`54([h'fe8000000000020202fffffffe030303', 64, 'eth0'])`.
+
+CBOR encoding of stand-in (27 bytes):
+
+``` cbor-pretty
+D8 36                                   # tag(54)
+   83                                   # array(3)
+      50                                # bytes(16)
+         FE8000000000020202FFFFFFFE030303
+      18 40                             # unsigned(64)
+      44                                # bytes(4)
+         65746830                       # "eth0"
+```
+
+CBOR encoding of legacy representation (40 bytes):
+
+``` cbor-pretty
+78 26                                   # text(38)
+   666538303A3A303230323A303266663A666666663A666530333A303330332F36342565746830
+```
+
+TO DO: adapt more examples from {{-cbor-ip}}
 
 TO DO: Check how the unions in {{-yang-types}} and {{-legacy-bis}} interact
 with this.  E.g., the union ip-address needs to be parsed to decide
 between tag 54 and tag 52.
 
+## Union handling
+
+When the schema specifies a union data type for a node, there are
+additional requirements on the encoder and decoder.
+
+An encoder which is fully aware of data semantics MUST use the appropriate
+data type, even though it isn't formally specified by the schema.
+
+If an intermediate encoder doesn't fully understand the data semantics,
+it needs to find out which type the data actually is to choose the right stand-in.
+If more types are possible, it MAY choose any of these which allow for an Unambiguous Round Trip,
+otherwise it SHOULD keep the legacy representation.
+
+If a decoder receives data for a union-typed node, it MUST accept any data type
+of the union, even though it may violate additional constraints outside the schema.
+
 # Using Stand-In Tags
 
-## The Role of the Schema
+## Defining Stand-In Usage in Schema
+
+TO DO: formally define the YANG extension
+
+## Original stand-ins
+
+The simplest situation is when no intermediate encoders and decoders are
+involved in the data transfer, therefore the round trip is not legacy.
+In this case, no conversions are involved and data is validated using the
+schema extension from the previous section.
 
-One approach of introducing stand-in tags in a produced would be to
-match any text string it produces against the format of the legacy
-representations and put in a stand-in tag instead.
-We call this the schema-agnostic approach.
+## Legacy Round Trip
 
-It is probably more efficient to trigger producing a stand-in tag from
-schema information available while producing the YANG-CBOR.
-However, that entangles the use of stand-in tags with the need schema
-information; the algorithm for deciding about the use of the stand-in
-tag needs to have enough schema information available to make this
-decision.
+Producing a stand-in MUST be triggered by schema usage. Intermediate encoders
+MUST NOT encode stand-ins when no schema is available.
 
-Not all values of a schema type can be represented by a tag such that
-an unambiguous round trip is achieved.  This document aims at an
-unambiguous round trip.
-ISSUE: Can we maybe live with round trips that aren't unambiguous?
+It's generally not recommended to do a legacy round trip where both the encoder
+and decoder are converting from and to the legacy representation.
 
 # Negotiation