Update events and validation modes.

davidlehn · davidlehn · commit e050ad8d534e · 2022-08-10T11:17:26.000-04:00
- Rename handlers.
- Add strict handler docs.
- Add `JsonLdEvent` type to events.
- Update `safeEventHandler` to handle new event codes.
- Add more event emitting points.
- Update event testing and tests.
- Add safe/strict testing flags.
- Fix bugs and cleanup.
diff --git a/README.md b/README.md
@@ -363,14 +363,11 @@ quality is known events are unnecessary.
 
 #### Event Structure
 
-Events are basic JSON objects with the following properties:
+Events are JSON objects with the following properties:
 
+- **`type`**: ['JsonLdEvent'] and optionally an array with others.
 - **`code`**: A basic string code, similar to existing JSON-LD error codes.
 - **`level`**: The severity level. Currently only `warning` is emitted.
-- **`tags`**: Optional hints for the type of event. Currently defined:
-  - **`unsafe`**: Event is considered unsafe.
-  - **`lossy`**: Event is related to potential data loss.
-  - **`empty`**: Event is related to empty data structures.
 - **`message`**: A human readable message describing the event.
 - **`details`**: A JSON object with event specific details.
 
@@ -445,7 +442,7 @@ const handler = {
 const expanded = await jsonld.expand(data, {eventHandler});
 ```
 
-#### Safe Mode
+#### Safe Validation
 
 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.
@@ -473,15 +470,29 @@ const expanded = await jsonld.expand(data, {
 });
 ```
 
+#### Strict Validation
+
+Some data may be valid and "safe" but still have issues that could indicate
+data problems. A "strict" validation mode is available that handles more issues
+that the "safe" validation mode. This mode may cause false positives so may be
+best suited for JSON-LD authoring tools.
+
+```js
+// expand a document in strict mode
+const expanded = await jsonld.expand(data, {
+  eventHandler: jsonld.strictEventHandler
+});
+```
+
 #### Available Handlers
 
 Some predefined event handlers are available to use alone or as part of a more
 complex handler:
 
-- **safeModeEventHandler**: The handler used when `safe` is `true`.
-- **strictModeEventHandler**: A handler that is more strict than the `safe`
-  handler and also fails on other detectable events related to poor input
-  structure.
+- **safeEventHandler**: The handler used when `safe` is `true`.
+- **strictEventHandler**: A handler that is more strict than the `safe`
+  handler and also fails on other detectable events related to possible input
+  issues.
 - **logEventHandler**: A debugging handler that outputs to the console.
 - **logWarningHandler**: A debugging handler that outputs `warning` level
   events to the console.
@@ -495,13 +506,13 @@ safe mode, and the second handler when in safe mode.
 ```js
 // fail on unknown events
 jsonld.setDefaultEventHandler(jsonld.unhandledEventHandler);
-// will use safe mode handler, like `{safe: true}`
+// will use unhandled event handler by default
 const expanded = await jsonld.expand(data);
 ```
 
 ```js
 // always use safe mode event handler, ignore other events
-jsonld.setDefaultEventHandler(jsonld.safeModeEventHandler);
+jsonld.setDefaultEventHandler(jsonld.safeEventHandler);
 // will use safe mode handler, like `{safe: true}`
 const expanded = await jsonld.expand(data);
 ```
diff --git a/lib/context.js b/lib/context.js
@@ -479,6 +479,7 @@ api.createTermDefinition = ({
     if(options.eventHandler) {
       _handleEvent({
         event: {
+          type: ['JsonLdEvent'],
           code: 'invalid reserved term',
           level: 'warning',
           message:
@@ -573,6 +574,7 @@ api.createTermDefinition = ({
       if(options.eventHandler) {
         _handleEvent({
           event: {
+            type: ['JsonLdEvent'],
             code: 'invalid reserved value',
             level: 'warning',
             message:
@@ -621,6 +623,7 @@ api.createTermDefinition = ({
       if(options.eventHandler) {
         _handleEvent({
           event: {
+            type: ['JsonLdEvent'],
             code: 'invalid reserved value',
             level: 'warning',
             message:
@@ -1155,6 +1158,7 @@ function _expandIri(activeCtx, value, relativeTo, localCtx, defined, options) {
       if(options.eventHandler) {
         _handleEvent({
           event: {
+            type: ['JsonLdEvent'],
             code: 'relative IRI after expansion',
             level: 'warning',
             message: 'Expansion resulted in a relative IRI.',
diff --git a/lib/events.js b/lib/events.js
@@ -34,7 +34,7 @@ api.defaultEventHandler = null;
 api.setupEventHandler = ({options = {}}) => {
   // build in priority order
   const eventHandler = [].concat(
-    options.safe ? api.safeModeEventHandler : [],
+    options.safe ? api.safeEventHandler : [],
     options.eventHandler ? _asArray(options.eventHandler) : [],
     api.defaultEventHandler ? api.defaultEventHandler : []
   );
@@ -100,27 +100,43 @@ function _handle({event, handlers}) {
   return doNext;
 }
 
+const _notSafeEventCodes = new Set([
+  'dropping object with only @id',
+  'dropping object with only @list',
+  'dropping object with only @value',
+  'dropping empty object',
+  'dropping free-floating scalar',
+  'invalid @language value',
+  'invalid property expansion',
+  'no value after expansion',
+  'relative IRI after expansion'
+]);
+
 // safe handler that rejects unsafe warning conditions
-api.safeModeEventHandler = function safeModeEventHandler({event, next}) {
+api.safeEventHandler = function safeEventHandler({event, next}) {
   // fail on all unsafe warnings
-  if(event.level === 'warning' &&
-    event.tags && event.tags.includes('unsafe')) {
+  if(event.level === 'warning' && _notSafeEventCodes.has(event.code)) {
     throw new JsonLdError(
-      'Safe mode violation.',
-      'jsonld.SafeModeViolationEvent',
+      'Safe mode validation error.',
+      'jsonld.ValidationError',
       {event}
     );
   }
   next();
 };
 
+const _notStrictEventCodes = new Set([
+  ..._notSafeEventCodes,
+  'invalid reserved term'
+]);
+
 // strict handler that rejects all warning conditions
-api.strictModeEventHandler = function strictModeEventHandler({event, next}) {
+api.strictEventHandler = function strictEventHandler({event, next}) {
   // fail on all warnings
-  if(event.level === 'warning') {
+  if(event.level === 'warning' && _notStrictEventCodes.has(event.code)) {
     throw new JsonLdError(
-      'Strict mode violation.',
-      'jsonld.StrictModeViolationEvent',
+      'Strict mode validation error.',
+      'jsonld.ValidationError',
       {event}
     );
   }
diff --git a/lib/expand.js b/lib/expand.js
@@ -106,6 +106,21 @@ api.expand = async ({
         insideList
       });
       if(mapped === undefined) {
+        // FIXME
+        if(options.eventHandler) {
+          _handleEvent({
+            event: {
+              type: ['JsonLdEvent'],
+              code: 'dropping free-floating scalar',
+              level: 'warning',
+              message: 'Dropping a free-floating scalar not in a list.',
+              details: {
+                value: element
+              }
+            },
+            options
+          });
+        }
         return null;
       }
       return mapped;
@@ -148,6 +163,21 @@ api.expand = async ({
           insideList
         });
         if(e === undefined) {
+          // FIXME name, desc
+          if(options.eventHandler) {
+            _handleEvent({
+              event: {
+                type: ['JsonLdEvent'],
+                code: 'no value after expansion',
+                level: 'warning',
+                message: 'Expansion did not result in any value.',
+                details: {
+                  value: element[i]
+                }
+              },
+              options
+            });
+          }
           continue;
         }
       }
@@ -317,6 +347,21 @@ api.expand = async ({
       if(mapped !== undefined) {
         rval = mapped;
       } else {
+        // FIXME
+        if(options.eventHandler) {
+          _handleEvent({
+            event: {
+              type: ['JsonLdEvent'],
+              code: 'no value after expansion',
+              level: 'warning',
+              message: 'Dropping null value from expansion.',
+              details: {
+                value: rval
+              }
+            },
+            options
+          });
+        }
         rval = null;
       }
     } else if(!values.every(v => (_isString(v) || _isEmptyObject(v))) &&
@@ -365,6 +410,21 @@ api.expand = async ({
     if(mapped !== undefined) {
       rval = mapped;
     } else {
+      // FIXME
+      if(options.eventHandler) {
+        _handleEvent({
+          event: {
+            type: ['JsonLdEvent'],
+            code: 'dropping object with only @language',
+            level: 'warning',
+            message: 'Dropping object with only @language.',
+            details: {
+              value: rval
+            }
+          },
+          options
+        });
+      }
       rval = null;
     }
   }
@@ -388,6 +448,37 @@ api.expand = async ({
       if(mapped !== undefined) {
         rval = mapped;
       } else {
+        // FIXME
+        if(options.eventHandler) {
+          // FIXME: one event or diff event for empty, @v/@l, {@id}?
+          let code;
+          let message;
+          if(count === 0) {
+            code = 'dropping empty object';
+            message = 'Dropping empty object.';
+          } else if('@value' in rval) {
+            code = 'dropping object with only @value';
+            message = 'Dropping object with only @value.';
+          } else if('@list' in rval) {
+            code = 'dropping object with only @list';
+            message = 'Dropping object with only @list.';
+          } else if(count === 1 && '@id' in rval) {
+            code = 'dropping object with only @id';
+            message = 'Dropping object with only @id.';
+          }
+          _handleEvent({
+            event: {
+              type: ['JsonLdEvent'],
+              code,
+              level: 'warning',
+              message,
+              details: {
+                value: rval
+              }
+            },
+            options
+          });
+        }
         rval = null;
       }
     }
@@ -454,6 +545,7 @@ async function _expandObject({
     if(expandedProperty === null ||
       !(_isAbsoluteIri(expandedProperty) || _isKeyword(expandedProperty))) {
       // TODO: use `await` to support async
+      const _expandedProperty = expandedProperty;
       expandedProperty = expansionMap({
         unmappedProperty: key,
         activeCtx,
@@ -468,12 +560,13 @@ async function _expandObject({
         if(options.eventHandler) {
           _handleEvent({
             event: {
+              type: ['JsonLdEvent'],
               code: 'invalid property expansion',
               level: 'warning',
               message: 'Invalid expansion for property.',
               details: {
-                // FIXME: include expandedProperty before mapping
-                property: key
+                property: key,
+                expandedProperty: _expandedProperty
               }
             },
             options
@@ -633,6 +726,7 @@ async function _expandObject({
           if(options.eventHandler) {
             _handleEvent({
               event: {
+                type: ['JsonLdEvent'],
                 code: 'invalid @language value',
                 level: 'warning',
                 message: '@language value must be valid BCP47.',
diff --git a/lib/fromRdf.js b/lib/fromRdf.js
@@ -344,6 +344,7 @@ function _RDFToObject(o, useNativeTypes, rdfDirection, options) {
           if(options.eventHandler) {
             _handleEvent({
               event: {
+                type: ['JsonLdEvent'],
                 code: 'invalid @language value',
                 level: 'warning',
                 message: '@language value must be valid BCP47.',
diff --git a/lib/jsonld.js b/lib/jsonld.js
@@ -83,9 +83,10 @@ const {
 const {
   logEventHandler: _logEventHandler,
   logWarningEventHandler: _logWarningEventHandler,
+  safeEventHandler: _safeEventHandler,
   setDefaultEventHandler: _setDefaultEventHandler,
   setupEventHandler: _setupEventHandler,
-  strictModeEventHandler: _strictModeEventHandler,
+  strictEventHandler: _strictEventHandler,
   unhandledEventHandler: _unhandledEventHandler
 } = require('./events');
 
@@ -1018,8 +1019,9 @@ jsonld.url = require('./url');
 /* Events API and handlers */
 jsonld.logEventHandler = _logEventHandler;
 jsonld.logWarningEventHandler = _logWarningEventHandler;
+jsonld.safeEventHandler = _safeEventHandler;
 jsonld.setDefaultEventHandler = _setDefaultEventHandler;
-jsonld.strictModeEventHandler = _strictModeEventHandler;
+jsonld.strictEventHandler = _strictEventHandler;
 jsonld.unhandledEventHandler = _unhandledEventHandler;
 
 /* Utility API */
diff --git a/tests/misc.js b/tests/misc.js
