[Docs request] lenient decoding explained

[avanov]

Hi!

The current docs section for https://hackage.haskell.org/package/cborg-json-0.2.2.0/docs/Codec-CBOR-JSON.html#v:decodeValue omits mentioning of the effect lenient argument has on data decoding. I'd appreciate it if the docs mentioned it in a quick example of how the argument affects decoding of the same input structure. Thanks!

[thoughtpolice]

Yes, this is worth pointing out. For people who end up looking here, the essential impact is this: CBOR has a notion of types for the keys in a Map, while JSON has no such equivalent for an object, a key is always a string. This makes CBOR maps a strict superset of JSON objects, so you cannot always convert from one to the other.

More specifically: when you decode a CBOR Map into JSON, the question then becomes, what should the JSON equivalent for following two-entry CBOR map be?

True:Bool -> 1
"True":String -> 2

That is, the first entry is a value of type CBOR Bool, while the second is of type String. This CBOR can't trivially be converted to JSON; the only apparent trivial mapping would be:

{
  "True": 1,
  "True": 2
}

Which is clearly an invalid JSON object due to collision of the key names.

So the rules are this:

• By default, with lenient = False, the only kind of Map that can be decoded is one that only has Strings as the key values. If any non-String key value is found, emitting JSON fails.
• If lenient = True, then if a Map is encountered with a non-String key, that key is show'd and converted to a String, and then returned. This means the above CBOR (valid) map would be accepted, but the resulting JSON would still be invalid as above: duplicate keys can now occur.

[avanov]

It's a great write-up, thank you! If it doesn't take too much effort on your side, I wouldn't hesitate to put it into the docstring, as it really explains the intent of the bool flag in the function signature.