Merge pull request #353 from filip26/issue/347

Add undefined terms processing policy (Fail, Warn, Ignore)

Author: filip26

README.md

@@ -196,6 +196,15 @@ JsonLd.toRdf("https://example/document.jsonld").loader(cachedLoader).get();
 JsonLd.toRdf("https://example/another-document.jsonld").loader(cachedLoader).get();
 ```
 
+#### Undefined Terms Processing Policy
+
+Set processing policy on undefined terms. `Ignore` by default.
+
+```javascript
+// since 1.4.1
+JsonLd.expand(...).undefinedTermsPolicy(Fail|Warn|Ignore).get();
+```
+
 ## Contributing
 
 All PR's welcome!

pom_parent.xml

@@ -129,6 +129,7 @@
 				<version>3.7.0</version>
 				<configuration>
 					<doclint>all,-missing</doclint>
+                    <failOnWarnings>false</failOnWarnings>
 				</configuration>
 				<executions>
 					<execution>

src/main/java/com/apicatalog/jsonld/JsonLdErrorCode.java

@@ -31,8 +31,7 @@
 public enum JsonLdErrorCode {
 
     /**
-     * Two
-     * <a href="https://www.w3.org/TR/rdf11-concepts/#dfn-property">properties</a>
+     * Two <a href="https://www.w3.org/TR/rdf11-concepts/#dfn-property">properties</a>
      * which expand to the same keyword have been detected. This might occur if a
      * keyword and an alias thereof are used at the same time.
      */
@@ -255,20 +254,22 @@ public enum JsonLdErrorCode {
      */
     PROTECTED_TERM_REDEFINITION,
 
-
     // Framing Error Codes https://www.w3.org/TR/json-ld11-framing/#error-handling
 
     /**
      * The frame is invalid.
      *
-     * @see <a href="https://www.w3.org/TR/json-ld11-framing/#dom-jsonldframingerrorcode-invalid-frame">invalid frame</a>
+     * @see <a href=
+     *      "https://www.w3.org/TR/json-ld11-framing/#dom-jsonldframingerrorcode-invalid-frame">invalid
+     *      frame</a>
      */
     INVALID_FRAME,
 
     /**
-     * The value for <code>@embed</code> is not one recognized for the object embed flag.
+     * The value for <code>@embed</code> is not one recognized for the object embed
+     * flag.
      *
-     * @see <a href="https://www.w3.org/TR/json-ld11-framing/#dom-jsonldframingerrorcode-invalid-@embed-value">invalid @embed value</a>
+     * @see <a href="https://www.w3.org/TR/json-ld11-framing/#dom-jsonldframingerrorcode-invalid-@embed-value">invalid @embedvalue</a>
      */
     INVALID_KEYWORD_EMBED_VALUE,
 
@@ -289,9 +290,14 @@ public enum JsonLdErrorCode {
     INVALID_ANNOTATION,
 
     // Custom
-    
+
     PROCESSING_TIMEOUT_EXCEEDED,
-    
+
+    /**
+     * An undefined term has been detected during expansion
+     */
+    UNDEFINED_TERM,
+
     UNSPECIFIED;
 
     private static final Map<JsonLdErrorCode, String> CODE_TO_MESSAGE;
@@ -351,9 +357,10 @@ public enum JsonLdErrorCode {
         messages.put(PROTECTED_TERM_REDEFINITION, "An attempt was made to redefine a protected term");
         messages.put(INVALID_FRAME, "The frame is invalid");
         messages.put(INVALID_KEYWORD_EMBED_VALUE, "The value for @embed is not one recognized for the object embed flag");
-        messages.put(INVALID_EMBEDDED_NODE, "An invalid embedded node has been detected.");
+        messages.put(INVALID_EMBEDDED_NODE, "An invalid embedded node has been detected");
         messages.put(INVALID_ANNOTATION, "An invalid annotation has been detected");
-        messages.put(PROCESSING_TIMEOUT_EXCEEDED, "A processing has exceeded a defined timeount");
+        messages.put(PROCESSING_TIMEOUT_EXCEEDED, "A processing has exceeded a defined timeout");
+        messages.put(UNDEFINED_TERM, "An undefined term has been found. Set policy to ignore to pass");
 
         CODE_TO_MESSAGE = Collections.unmodifiableMap(messages);
     }
@@ -362,4 +369,3 @@ public String toMessage() {
         return CODE_TO_MESSAGE.getOrDefault(this, "Processing error") + " [code=" + this + "].";
     }
 }
-

src/main/java/com/apicatalog/jsonld/JsonLdOptions.java

@@ -45,6 +45,15 @@ public enum RdfDirection {
         COMPOUND_LITERAL
     }
 
+    public enum ProcessingPolicy {
+        /** ignore, the current and default behavior */
+        Ignore,
+        /** stop processing with an error */
+        Fail,
+        /** print warning to log */
+        Warn
+    }
+
     /* default values */
     public static final boolean DEFAULT_RDF_STAR = false;
     public static final boolean DEFAULT_NUMERIC_ID = false;
@@ -124,9 +133,12 @@ public enum RdfDirection {
     private Cache<String, Document> documentCache;
 
     private boolean uriValidation;
-    
+
     private Duration timeout;
 
+    // a policy on how proceed with undefined terms during expansion
+    private ProcessingPolicy undefinedTerms;
+
     public JsonLdOptions() {
         this(SchemeRouter.defaultInstance());
     }
@@ -163,6 +175,7 @@ public JsonLdOptions(DocumentLoader loader) {
         this.documentCache = null;
         this.uriValidation = DEFAULT_URI_VALIDATION;
         this.timeout = null;
+        this.undefinedTerms = ProcessingPolicy.Ignore;
     }
 
     public JsonLdOptions(JsonLdOptions options) {
@@ -195,6 +208,7 @@ public JsonLdOptions(JsonLdOptions options) {
         this.documentCache = options.documentCache;
         this.uriValidation = options.uriValidation;
         this.timeout = options.timeout;
+        this.undefinedTerms = options.undefinedTerms;
     }
 
     /**
@@ -500,7 +514,7 @@ public void setUriValidation(boolean enabled) {
     /**
      * A processing timeout. An exception is thrown when a processing time exceeds
      * the duration, if set. There is no currency that processing gets terminated
-     * immediately, but eventually.  
+     * immediately, but eventually.
      * 
      * Please note, the timeout does not include time consumed by
      * {@link DocumentLoader}.
@@ -510,17 +524,37 @@ public void setUriValidation(boolean enabled) {
     public Duration getTimeout() {
         return timeout;
     }
-    
+
     /**
-     * Set a pressing timeout. A processing is eventually terminated after the 
-     * specified duration. Set <code>null</code> for no timeout. 
+     * Set a pressing timeout. A processing is eventually terminated after the
+     * specified duration. Set <code>null</code> for no timeout.
      * 
      * Please note, the timeout does not include time consumed by
      * {@link DocumentLoader}.
-     *  
+     * 
      * @param timeout to limit processing time
      */
     public void setTimeout(Duration timeout) {
         this.timeout = timeout;
     }
+
+    /**
+     * A processing policy on how proceed with an undefined term during expansion.
+     * 
+     * @return the processing policy, never <code>null</code>
+     */
+    public ProcessingPolicy getUndefinedTermsPolicy() {
+        return undefinedTerms;
+    }
+
+    /**
+     * Set processing policy on how proceed with an undefined term during expansion.
+     * Ignore by default.
+     * 
+     * @param undefinedTerms the processing policy, never <code>null</code>
+     * 
+     */
+    public void setUndefinedTermsPolicy(ProcessingPolicy undefinedTerms) {
+        this.undefinedTerms = undefinedTerms;
+    }
 }

src/main/java/com/apicatalog/jsonld/api/ExpansionApi.java

@@ -20,6 +20,7 @@
 import com.apicatalog.jsonld.JsonLdError;
 import com.apicatalog.jsonld.JsonLdOptions;
 import com.apicatalog.jsonld.JsonLdVersion;
+import com.apicatalog.jsonld.JsonLdOptions.ProcessingPolicy;
 import com.apicatalog.jsonld.document.Document;
 import com.apicatalog.jsonld.document.JsonDocument;
 import com.apicatalog.jsonld.loader.DocumentLoader;
@@ -157,4 +158,16 @@ public ExpansionApi rdfStar() {
         options.setRdfStar(true);
         return this;
     }
+
+    /**
+     * Set a processing policy determining how to proceed when an undefined term is
+     * found during an expansion. An unknown term is ignored by default.
+     * 
+     * @param policy a processing policy
+     * @return builder instance
+     */
+    public ExpansionApi undefinedTermsPolicy(ProcessingPolicy policy) {
+        options.setUndefinedTermsPolicy(policy);
+        return this;
+    }
 }

src/main/java/com/apicatalog/jsonld/expansion/ObjectExpansion1314.java

@@ -137,15 +137,23 @@ public void expand() throws JsonLdError {
             activeContext.runtime().tick();
 
             // 13.2.
-            String expandedProperty = activeContext
+            final String expandedProperty = activeContext
                     .uriExpansion()
                     .documentRelative(false)
                     .vocab(true)
                     .expand(key);
 
-            // 13.3.
+            // if the term is undefined and
             if (expandedProperty == null || (!expandedProperty.contains(":") && !Keywords.contains(expandedProperty))) {
-                continue;
+                switch (activeContext.runtime().getUndefinedTermPolicy()) {
+                case Fail:
+                    throw new JsonLdError(JsonLdErrorCode.UNDEFINED_TERM,
+                            "An undefined term has been found [" + key + "]. Change policy to Ignore or Warn or define the term in a context");
+                case Warn:
+                    LOGGER.log(Level.WARNING, "An undefined term has been found [{0}]", key);
+                case Ignore:
+                    continue;
+                }
             }
 
             JsonValue value = element.get(key);
@@ -163,7 +171,6 @@ public void expand() throws JsonLdError {
                 // 13.4.2
                 if (result.containsKey(expandedProperty)
                         && Keywords.noneMatch(expandedProperty, Keywords.INCLUDED, Keywords.TYPE)) {
-
                     throw new JsonLdError(JsonLdErrorCode.COLLIDING_KEYWORDS,
                             "Two properties which expand to the same keyword have been detected. A property '" + key + "'"
                                     + " expands to '" + expandedProperty + "'"

src/main/java/com/apicatalog/jsonld/processor/ProcessingRuntime.java

@@ -2,6 +2,7 @@
 
 import com.apicatalog.jsonld.JsonLdError;
 import com.apicatalog.jsonld.JsonLdOptions;
+import com.apicatalog.jsonld.JsonLdOptions.ProcessingPolicy;
 import com.apicatalog.jsonld.JsonLdVersion;
 import com.apicatalog.jsonld.context.cache.Cache;
 import com.apicatalog.jsonld.document.Document;
@@ -79,4 +80,8 @@ public boolean isRdfStar() {
     public boolean isNumericId() {
         return options.isNumericId();
     }
+
+    public ProcessingPolicy getUndefinedTermPolicy() {
+        return options.getUndefinedTermsPolicy();
+    }
 }

src/test/java/com/apicatalog/jsonld/loader/LRUDocumentCacheTest.java

@@ -1,19 +1,18 @@
 package com.apicatalog.jsonld.loader;
 
-import com.apicatalog.jsonld.JsonLdError;
-import com.apicatalog.jsonld.document.Document;
-import com.apicatalog.jsonld.document.JsonDocument;
-import jakarta.json.JsonValue;
-import org.junit.jupiter.api.Assertions;
-import org.junit.jupiter.api.Test;
-
 import java.net.URI;
 import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.Collection;
 import java.util.LinkedList;
 import java.util.List;
-import java.util.Set;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+import com.apicatalog.jsonld.JsonLdError;
+import com.apicatalog.jsonld.document.Document;
+import com.apicatalog.jsonld.document.JsonDocument;
+
+import jakarta.json.JsonValue;
 
 public class LRUDocumentCacheTest {