Add "safe mode" documentation.

Author: davidlehn

CHANGELOG.md

@@ -9,6 +9,10 @@
 - Support test environment in EARL output.
 - Support benchmark output in EARL output.
 - Benchmark comparison tool.
+- Add "safe mode" to all APIs. Enable by adding `{safe: true}` to API options.
+  This mode causes processing to fail when data constructs are encountered that
+  result in lossy behavior or other data warnings. This is intended to be the
+  common way that digital signing and similar applications use this libraray.
 
 ## 6.0.0 - 2022-06-06
 
@@ -34,6 +38,8 @@
 
 ### Removed
 - Experimental non-standard `protectedMode` option.
+- **BREAKING**: Various console warnings were removed. The newly added "safe
+  mode" can stop processing where these warnings were.
 
 ## 5.2.0 - 2021-04-07
 

README.md

@@ -346,6 +346,24 @@ It is recommended to set a default `user-agent` header for Node.js
 applications. The default for the default Node.js document loader is
 `jsonld.js`.
 
+### Safe Mode
+
+A common use case is to avoid JSON-LD constructs that will result in lossy
+behavior. The JSON-LD specifications have notes about when data is dropped.
+This can be especially important when calling [`canonize`][] in order to
+digitally sign data. A special "safe mode" is available that will detect these
+situations and cause processing to fail.
+
+**Note**: This mode is designed to be the common way that digital signing and
+similar applications use this library.
+
+The `safe` options flag set to `true` enables this behavior:
+
+```js
+// expand a document in safe mode
+const expanded = await jsonld.expand(data, {safe: true});
+```
+
 Related Modules
 ---------------