Skip to content

Commit

Permalink
-01: Reflect comments from initial WG discussion
Browse files Browse the repository at this point in the history
  • Loading branch information
@cabo
cabo committed Mar 9, 2023
1 parent 9973770 commit 519ac6c
Showing 1 changed file with 78 additions and 60 deletions.
138 changes: 78 additions & 60 deletions draft-bormann-cbor-cddl-more-control.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,10 @@ keyword:
- Concise Data Definition Language
- Control Operator
venue:
group: "Concise Binary Object Representation Maintenance and Extensions"
group: "Concise Binary Object Representation (CBOR) Maintenance and Extensions"
mail: "[email protected]"
github: "cbor-wg/cddl-more-control"
latest: "https://cbor-wg.github.io/cddl-more-control/draft-bormann-cbor-cddl-more-control.html"
latest: "https://cbor-wg.github.io/cddl-more-control/"

pi: [toc, sortrefs, symrefs, compact, comments]

Expand Down Expand Up @@ -45,12 +45,8 @@ normative:
IANA.cddl:
RFC9165: control1
RFC4648: base
informative:
INTERSPERSE:
target: https://hoogle.haskell.org/?hoogle=intersperse
title: intersperse
rc: Haskell Documentation
date: false
RFC9285: base45
RFC8742: seq

--- abstract

Expand All @@ -61,7 +57,13 @@ application-specific and a more general way.

The present document defines a number of additional generally
application control operators for text conversion (Bytes, Integers,
JSON) and operations on text.
JSON), operations on text, and deterministic encoding.

[^status]

[^status]: Revision –01 of this draft reflects comments from initial
discussion of the specification in the CBOR working group.
It is intended to be ready for working group adoption.


--- middle
Expand All @@ -78,13 +80,16 @@ application-specific {{?RFC9090}} and a more general {{RFC9165}} way.
The present document defines a number of additional generally
applicable control operators:

| Name | Purpose |
| `.b64u`, `.b64c` | Base64 representation of byte strings |
| `.hex`, `.hexlc`, `.hexuc` | Base16 representation of byte strings |
| `.b32`, `.h32` | Base32 representation of byte strings |
| `.decimal` | Text representation of integer numbers |
| `.json` | Text representation of JSON values |
| `.join` | Building text from array of components |
| Name | Purpose |
| `.b64u`, `.b64c` | Base64 representation of byte strings |
| `.b64u-sloppy`, `.b64c-sloppy` | (sloppy-tolerant variants of the above) |
| `.hex`, `.hexlc`, `.hexuc` | Base16 representation of byte strings |
| `.b32`, `.h32` | Base32 representation of byte strings |
| `.b45` | Base45 representation of byte strings |
| `.decimal` | Text representation of integer numbers |
| `.json` | Text representation of JSON values |
| `.join` | Building text from array of components |
| `.cbordet`, `.cborseqdet` | deterministically encoded CBOR data items, CBOR sequences |
{: #tbl-new title="New control operators in this document"}

Terminology
Expand Down Expand Up @@ -126,14 +131,17 @@ large number of transformations in use. Inspired by {{Section 8 of
-cbor}}, we use representations defined in {{-base}} with the following
names:

| name | meaning | reference |
| `.b64u` | Base64URL, no padding | {{Section 5 of -base}} |
| `.b64c` | Base64 classic, padding | {{Section 4 of -base}} |
| `.b32` | Base32, no padding | {{Section 6 of -base}} |
| `.h32` | Base32/hex alphabet, no padding | {{Section 7 of -base}} |
| `.hex` | Base16 (hex), either case | {{Section 8 of -base}} |
| `.hexlc` | Base16 (hex), lower case | {{Section 8 of -base}} |
| `.hexuc` | Base16 (hex), upper case | {{Section 8 of -base}} |
| name | meaning | reference |
| `.b64u` | Base64URL, no padding | {{Section 5 of -base}} |
| `.b64u-sloppy` | Base64URL, no padding, sloppy | {{Section 5 of -base}} |
| `.b64c` | Base64 classic, padding | {{Section 4 of -base}} |
| `.b64c-sloppy` | Base64 classic, padding, sloppy | {{Section 4 of -base}} |
| `.b32` | Base32, no padding | {{Section 6 of -base}} |
| `.h32` | Base32/hex alphabet, no padding | {{Section 7 of -base}} |
| `.hex` | Base16 (hex), either case | {{Section 8 of -base}} |
| `.hexlc` | Base16 (hex), lower case | {{Section 8 of -base}} |
| `.hexuc` | Base16 (hex), upper case | {{Section 8 of -base}} |
| `.b45` | Base45 | {{-base45}} |
{: title="Control Operators for Text Conversion of byte strings"}

Note that this specification is somewhat opinionated here: It does not
Expand All @@ -143,6 +151,18 @@ combinations only ever occur in error, so the usability of CDDL is
increased by not providing them in the first place. Also, adding "c"
makes sure that any decision for classic base64 is actively taken.

The additional designation "sloppy" indicates that the text string is
not validated for any additional bits being zero, in variance to what
is specified in the paragraph behind table 1 in {{Section 4 of -base}}.
Note that the present specification is opinionated again in not
specifying a sloppy variant of base32 or base32/hex, as no legacy use
of sloppy base32(/hex) was known at the time of writing.
Base45 is known to be suboptimal for use in environments with limited
data transparency (such as URLs), but is included because of its close
relationship to QR codes and its wide use in health informatics (note
that base45 is at least strongly specified not to allow sloppy forms
of encoding).

Numbers
-------

Expand All @@ -169,7 +189,7 @@ JSON Values
-----------

Some applications store complete JSON texts into text strings, the
JSON value for can easily be defined in CDDL.
JSON value for which can easily be defined in CDDL.
This is supported by a control operator similar to `.cbor` in {{Section
3.8.4 of -cddl}}.

Expand Down Expand Up @@ -213,32 +233,25 @@ digits<N> = text .decimal byte<n>
~~~
{: sourcecode-name="example4.cddl"}

Intersperse
-----------

(This section requires some additional design effort before it can be
implemented and registered.)

The previous example is somewhat unwieldy as the dots are just
syntactic noise.
Deterministic Encoding
======================

The `.intersperse` control is modeled after Haskell's function of the
same name {{INTERSPERSE}}. It takes the elements of an array and
intersperses a given additional elements between each to elements of
the additional array.
{{-cddl}} and {{-seq}} specify the control operators `.cbor` and
`.cborseq` to indicate that the value of a byte string should be an
encoded CBOR data item or a CBOR sequence.

~~~ cddl
legacy-ip-address = text .join ("." .intersperse digits)
digits = [4*4 digit]
digit = text .decimal (uint .size 1)
~~~
{: sourcecode-name="example5.cddl"}
This specification provides complementary control operators `.cbordet`
and `.cborseqdet` that indicate that these data items/sequences need
to be encoded in accordance to {{Sections 4.2.1 and 4.2.2 of -cbor}}.

`.intersperse` is actually not limited to text strings; it can be used
for any juggling of arrays.
| name | meaning | reference |
| `.cbordet` | deterministically encoded CBOR data item | {{-cddl}} |
| `.cborseqdet` | CBOR sequence made from deterministically encoded CBOR data items | {{-seq}} |
{: title="Control Operator for Deterministically Encoded Data Items and Sequences"}

We want to stop here, as there is a danger of generating a functional
programming language in an ad-hoc fashion.
Note that considerations of deterministic representation at the
application level can often be expressed in the CDDL definition of the
right-hand side and then do not need additional control operators.


IANA Considerations
Expand All @@ -248,17 +261,22 @@ This document requests IANA to register the contents of
{{tbl-iana-reqs}} into the registry
"{{cddl-control-operators (CDDL Control Operators)<IANA.cddl}}" of {{IANA.cddl}}:

| Name | Reference |
| `.b64u` | [RFCthis] |
| `.b64c` | [RFCthis] |
| `.b32` | [RFCthis] |
| `.h32` | [RFCthis] |
| `.hex` | [RFCthis] |
| `.hexlc` | [RFCthis] |
| `.hexuc` | [RFCthis] |
| `.decimal` | [RFCthis] |
| `.json` | [RFCthis] |
| `.join` | [RFCthis] |
| Name | Reference |
| `.b64u` | [RFCthis] |
| `.b64u-sloppy` | [RFCthis] |
| `.b64c` | [RFCthis] |
| `.b64c-sloppy` | [RFCthis] |
| `.b45` | [RFCthis] |
| `.b32` | [RFCthis] |
| `.h32` | [RFCthis] |
| `.hex` | [RFCthis] |
| `.hexlc` | [RFCthis] |
| `.hexuc` | [RFCthis] |
| `.decimal` | [RFCthis] |
| `.json` | [RFCthis] |
| `.join` | [RFCthis] |
| `.cbordet` | [RFCthis] |
| `.cborseqdet` | [RFCthis] |
{: #tbl-iana-reqs title="New control operators to be registered"}

Implementation Status
Expand All @@ -268,8 +286,8 @@ Implementation Status
<!-- RFC7942 -->

In the CDDL tool described in {{Section F of RFC8610}},
the control operators defined in this specification are
implemented as of version 0.10.2.
the control operators defined in revision -00 of this specification are
implemented as of version 0.10.2; implementation of the rest is ongoing.

Security considerations
=======================
Expand Down

0 comments on commit 519ac6c

Please sign in to comment.