Release Notes for json5 changes

documentation/RELEASE_NOTES.md

@@ -17,6 +17,60 @@ should also be read to understand what has changed since earlier releases.
 
 <!-- Insert new items immediately below here ... -->
 
+### Support for JSON5
+
+The YAJL parser and generator routines in libcom and in the IOC's dbStatic
+parser now support the JSON5 standard. This adds various features to JSON
+without altering the API for the code other than adding a new option to the
+YAJL parser which can be used to disable JSON5 support if desired. The new
+features include:
+
+- The ability to handle numeric values `Infinity`, `-Infinity` and `NaN`.
+- String values and map keys may be enclosed in single quotes `'`, inside which
+  the double-quote character `"` doesn't have to be escaped with a back-slash
+  `\`, although a single-quote character `'` (or apostrophy) must be escaped
+  inside a single-quoted string.
+- Numbers may start with a plus sign, `+`.
+- Integers may be expressed in hexadecimal with a leading `0x` or `0X`.
+- Floating-point numbers may start or end with their decimal point `.`
+  (after the sign or before the exponent respectively if present).
+- Map keys that match the regex `[A-Za-z_][A-Za-z_0-9]*` don't have to be
+  enclosed in quotes at all. The dbStatic parser adds `.+-` to the characters
+  allowed but will add quotes around such keys before passing them to YAJL.
+- Arrays and maps allow a comma before the closing bracket/brace character.
+- The YAJL parser will elide a backslash followed by a newline characters from
+  a string value. The dbStatic parser doesn't allow that however.
+
+Code that must also compile against the older API can use the new C macro
+`HAS_JSON5` to detect the new version. This macro is defined on including
+either the `yajl_parse.h` or `yajl_gen.h` headers, which also provide the
+new configuration options to turn on JSON5 support.
+
+All APIs in the IOC that previously accepted JSON will now accept JSON5.
+This includes JSON field modifiers (channel filters), JSON link addresses,
+constant input link array values and database info-tag values. JSON values
+that get parsed by the dbLoadRecords() routine are still more liberal than
+the other uses as the ability to use unquoted strings that was called
+"relaxed JSON" is still supported, whereas the JSON5 standard and the YAJL
+parser only allow unquoted strings to be used for keys in a JSON map.
+
+This change fixes [lauchpad bug #1714455](https://bugs.launchpad.net/bugs/1714455).
+
+
+### Character escape changes
+
+- The libCom routines `epicsStrnRawFromEscaped()` and `dbTranslateEscape()`
+  declared in epicsString.h no longer accept octal escaped characters such as
+  `\123` or `\41`.
+- The routine `epicsStrnEscapedFromRaw()` now generates hex
+  excaped characters for unprintable characters such as `\x1f`.
+- Hex escape character sequences `\xXX` must now contain exactly 2 hex digits.
+- An escape sequence `\0` now generates a zero byte in the raw string, but the
+  other digits `1-9` should not appear after a back-slash.
+
+These changes are to more closely follow the JSON5 standard, which doesn't
+support octal character escapes or the `\a` (Bel, `\x07`) escape sequence.
+
 ## EPICS Release 7.0.4.1
 
 ### Bug fixes