Moved API recommendations to their own section.

Author: wolfmcnally

draft-mcnally-deterministic-cbor.md

@@ -70,15 +70,12 @@ This document's goal is to specify such a set of norms and practices for dCBOR c
 
 It is important to stress that dCBOR is *not* a new dialect of CBOR, and that all dCBOR is well-formed CBOR that can be read by existing CBOR codecs.
 
-Nonetheless, many existing implementations give little or no guidance at the API level as to whether the CBOR being read conforms to the dCBOR specification, for example by emitting errors or warnings at deserialization time. Conversely, many existing implementations do not carry any burden of ensuring that CBOR is serialized in conformance with the dCBOR specification, again putting that burden on developers.
-
-The authors of this document believe that for applications where dCBOR correctness is important, the codec itself should carry as much of this burden as possible. This is important both to minimize cognitive load during development, and help ensure interoperability between implementations.
-
-This document is segmented into three categories. They include norms and practices that:
+This document is segmented into four sections. They include norms and practices that:
 
 * MUST be implemented in the codec (Serialization level),
 * MUST be implemented by developers of specifications dependent on dCBOR (Application level).
 * are acknowledged to fall under the purview of this document, but which are not yet specified (Future work).
+* are RECOMMENDED for dCBOR codec implementors (Recommendations).
 
 # Terminology
 
@@ -93,7 +90,7 @@ codec
 : "coder-decoder", a software suite that both encodes (serializes) and decodes (deserializes) a data format.
 
 dCBOR
-: "deterministic CBOR" encoded in conformance with the CBOR specifications §4.2 {{-CBOR}}.
+: "deterministic CBOR" encoded in conformance with the CBOR specification in this document.
 
 insert/extract
 : To convert platform-native or application-centric data structures to/from an in-memory symbolic representation of CBOR.
@@ -105,14 +102,6 @@ serialize/deserialize
 
 This section defines requirements and practices falling in the purview of the dCBOR codec.
 
-## General Practices for dCBOR Codecs
-
-dCBOR codecs SHOULD:
-
-* Make it easy to emit compliant dCBOR.
-* Make it hard to emit non-compliant dCBOR.
-* Make it an error to read non-compliant dCBOR.
-
 ## Base Requirements
 
 dCBOR encoders MUST only emit CBOR conforming to the requirements of {{-CBOR}} §4.2.1. To summarize:
@@ -159,37 +148,6 @@ Because of this incompatibility between the CBOR and standard representations, d
 
 Implementations that support BIGNUM are able to encode and decode this value as BIGNUM.
 
-## API Handling of Maps
-
-dCBOR APIs SHOULD provide a dCBOR `Map` structure or similar that models the dCBOR canonical key encoding and order.
-
-* Supports insertion of unencoded key-value pairs.
-* Supports iteration through entries in dCBOR canonical key order.
-* Supports treating keys as duplicate that have identical dCBOR encodings, e.g., `10` and `10.0`.
-
-The dCBOR decoder MUST return an error if it encounters misordered or duplicate map keys.
-
-## API Handling of Numeric Values
-
-The above requirements of this section deal with how dCBOR encoders MUST serialize numeric values, and how dCBOR decoders MUST validate them. It does not specify requirements for the API, but the authors do make the following recommendations:
-
-* The encoder API SHOULD accept any supported numeric type for insertion into the CBOR stream. The CBOR encoder SHALL decide the dCBOR-conformant form for its encoding.
-* The API SHOULD allow any supported numeric type to be extracted, and return errors when the actual type encountered is not representable in the requested type. For example,
-    * If the encoded value is "1.5" then requesting extraction of the value as floating point will succeed but requesting extraction as an integer will fail.
-    * Similarly, if the value has a large exponent and therefore can be represented as either a floating point value or a BigNum, then attempting to extract it as a machine integer will fail.
-
-## Validation Errors
-
-A dCBOR decoder MUST return errors when it encounters any of these conditions in the input stream. The error symbol names below are informative.
-
-* `underrun`: early end of stream
-* `badHeaderValue`: unsupported CBOR major/minor item header
-* `nonCanonicalNumeric`: An integer, floating-point value, or BigNum was encoded in non-canonical form
-* `invalidString`: An invalid UTF-8 string was encountered
-* `unusedData`: Unused data encountered past the expected end of the input stream
-* `misorderedMapKey`: A map has keys not in canonical order
-* `duplicateMapKey`: A map has a duplicate key
-
 # Application Level
 
 ## Optional/Default Values
@@ -221,6 +179,53 @@ The following issues are currently left for future work:
 
 * How to deal with subnormal floating point values {{SUBNORMAL}}.
 
+# API-Level Recommendations
+
+This section is informative.
+
+Many existing CBOR implementations give little or no guidance at the API level as to whether the CBOR being read conforms to the CBOR specification for deterministic encoding {{-CBOR}} §4.2, for example by emitting errors or warnings at deserialization time. Conversely, many existing implementations do not carry any burden of ensuring that CBOR is serialized in conformance with the CBOR determinstic encoding specification, again putting that burden on developers.
+
+The authors of this document believe that for applications where dCBOR correctness as specified in this document is important, the codec itself should carry as much of this burden as possible. This is important both to minimize cognitive load during development, and help ensure interoperability between implementations.
+
+## General Practices for dCBOR Codecs
+
+It is RECOMMENDED that dCBOR codecs:
+
+* Make it easy to emit compliant dCBOR.
+* Make it hard to emit non-compliant dCBOR.
+* Make it an error to read non-compliant dCBOR.
+
+## API Handling of Maps
+
+It is RECOMMENDED that dCBOR APIs provide a dCBOR `Map` structure or similar that models the dCBOR canonical key encoding and order:
+
+* Supports insertion of unencoded key-value pairs.
+* Supports iteration through entries in dCBOR canonical key order.
+* Supports treating keys as duplicate that have identical dCBOR encodings, e.g., `10` and `10.0`.
+
+The dCBOR decoder SHOULD return an error if it encounters misordered or duplicate map keys.
+
+## API Handling of Numeric Values
+
+The authors do make the following recommendations:
+
+* The encoder API SHOULD accept any supported numeric type for insertion into the CBOR stream and decide the dCBOR-conformant form for its encoding.
+* The API SHOULD allow any supported numeric type to be extracted, and return errors when the actual type encountered is not representable in the requested type. For example,
+    * If the encoded value is "1.5" then requesting extraction of the value as floating point will succeed but requesting extraction as an integer will fail.
+    * Similarly, if the value has a large exponent and therefore can be represented as either a floating point value or a BigNum, then attempting to extract it as a machine integer will fail.
+
+## Validation Errors
+
+It is RECOMMENDED that a dCBOR decoder return errors when it encounters any of these conditions in the input stream:
+
+* `underrun`: early end of stream
+* `badHeaderValue`: unsupported CBOR major/minor item header
+* `nonCanonicalNumeric`: An integer, floating-point value, or BigNum was encoded in non-canonical form
+* `invalidString`: An invalid UTF-8 string was encountered
+* `unusedData`: Unused data encountered past the expected end of the input stream
+* `misorderedMapKey`: A map has keys not in canonical order
+* `duplicateMapKey`: A map has a duplicate key
+
 # Reference Implementations
 
 This section is informative.