Add support for reference schemas in JSON/YAML schema validation (7.X)

annot/src/main/java/com/predic8/membrane/annot/generator/Scope.java

@@ -1,3 +1,17 @@
+/* Copyright 2025 predic8 GmbH, www.predic8.com
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License. */
+
 package com.predic8.membrane.annot.generator;
 
 public enum Scope {

annot/src/main/java/com/predic8/membrane/annot/util/ReflectionUtil.java

@@ -1,3 +1,17 @@
+/* Copyright 2025 predic8 GmbH, www.predic8.com
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License. */
+
 package com.predic8.membrane.annot.util;
 
 public class ReflectionUtil {

annot/src/test/java/com/predic8/membrane/annot/util/ReflectionUtilTest.java

@@ -1,3 +1,17 @@
+/* Copyright 2025 predic8 GmbH, www.predic8.com
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License. */
+
 package com.predic8.membrane.annot.util;
 
 import org.junit.jupiter.api.*;

core/src/main/java/com/predic8/membrane/core/interceptor/schemavalidation/ValidatorInterceptor.java

@@ -66,6 +66,8 @@ public class ValidatorInterceptor extends AbstractInterceptor implements Applica
     private ResolverMap resourceResolver;
     private ApplicationContext applicationContext;
 
+    private SchemaMappings schemaMappings;
+
     private SOAPProxy soapProxy;
 
     public ValidatorInterceptor() {
@@ -94,15 +96,23 @@ public void init() {
 
     private MessageValidator getMessageValidator() throws Exception {
         if (wsdl != null) {
+            if (schemaMappings != null)
+                logIgnoringRefSchemas();
             return new WSDLValidator(resourceResolver, combine(getBaseLocation(), wsdl), serviceName, createFailureHandler(), skipFaults);
         }
         if (schema != null) {
+            if (schemaMappings != null)
+                logIgnoringRefSchemas();
             return new XMLSchemaValidator(resourceResolver, combine(getBaseLocation(), schema), createFailureHandler());
         }
         if (jsonSchema != null) {
-            return new JSONYAMLSchemaValidator(resourceResolver, combine(getBaseLocation(), jsonSchema), createFailureHandler(), schemaVersion);
+            return new JSONYAMLSchemaValidator(resourceResolver, combine(getBaseLocation(), jsonSchema), createFailureHandler(), schemaVersion) {{
+                if(schemaMappings != null) setSchemaMappings(schemaMappings.getSchemaMap());
+            }};
         }
         if (schematron != null) {
+            if (schemaMappings != null)
+                logIgnoringRefSchemas();
             return new SchematronValidator(combine(getBaseLocation(), schematron), createFailureHandler(), router, applicationContext);
         }
 
@@ -112,6 +122,10 @@ private MessageValidator getMessageValidator() throws Exception {
         throw new RuntimeException("Validator is not configured properly. <validator> must have an attribute specifying the validator.");
     }
 
+    private static void logIgnoringRefSchemas() {
+        log.warn("Ignoring 'referenceSchemas': schema references are only supported for JSON/YAML validators");
+    }
+
     private @Nullable WSDLValidator getWsdlValidatorFromSOAPProxy() {
         if(soapProxy == null) return null;
         wsdl = soapProxy.getWsdl();
@@ -319,6 +333,16 @@ private FailureHandler createFailureHandler() {
         throw new IllegalArgumentException("Unknown failureHandler type: " + failureHandler);
     }
 
+    @MCChildElement
+    public void setReferenceSchemas(SchemaMappings schemaMappings) {
+        this.schemaMappings = schemaMappings;
+    }
+
+    public SchemaMappings getReferenceSchemas() {
+        return schemaMappings;
+    }
+
+
     public void setSoapProxy(SOAPProxy soapProxy) {
         this.soapProxy = soapProxy;
     }

core/src/main/java/com/predic8/membrane/core/interceptor/schemavalidation/json/JSONYAMLSchemaValidator.java

@@ -20,6 +20,7 @@
 import com.networknt.schema.*;
 import com.networknt.schema.Error;
 import com.networknt.schema.path.NodePath;
+import com.networknt.schema.resource.SchemaLoader;
 import com.predic8.membrane.core.exchange.*;
 import com.predic8.membrane.core.interceptor.Interceptor.*;
 import com.predic8.membrane.core.interceptor.*;
@@ -48,7 +49,6 @@ public class JSONYAMLSchemaValidator extends AbstractMessageValidator {
 
     private final YAMLFactory factory = YAMLFactory.builder().enable(STRICT_DUPLICATE_DETECTION).build();
     private final ObjectMapper yamlObjectMapper = new ObjectMapper(factory);
-    private final ObjectMapper jsonObjectMapper = new ObjectMapper();
 
     public static final String SCHEMA_VERSION_2020_12 = "2020-12";
 
@@ -60,10 +60,7 @@ public class JSONYAMLSchemaValidator extends AbstractMessageValidator {
     private final AtomicLong invalid = new AtomicLong();
     private final SpecificationVersion schemaId;
 
-    /**
-     * JsonSchemaFactory instances are thread-safe provided its configuration is not modified.
-     */
-    SchemaRegistry jsonSchemaFactory;
+    private Map<String, String> schemaMappings = new HashMap<>();
 
     /**
      * JsonSchema instances are thread-safe provided its configuration is not modified.
@@ -76,7 +73,7 @@ public JSONYAMLSchemaValidator(Resolver resolver, String jsonSchema, FailureHand
         this.resolver = resolver;
         this.jsonSchema = jsonSchema;
         this.failureHandler = failureHandler;
-        this.schemaId = JSONSchemaVersionParser.parse( schemaVersion);
+        this.schemaId = JSONSchemaVersionParser.parse(schemaVersion);
         this.inputFormat = inputFormat;
     }
 
@@ -97,26 +94,34 @@ public String getName() {
     public void init() {
         super.init();
 
-        jsonSchemaFactory = SchemaRegistry.withDefaultDialect(schemaId, builder ->
-                builder.schemaLoader(loaders -> new MembraneSchemaLoader(resolver)));
-
         try (InputStream in = resolver.resolve(jsonSchema)) {
-            schema = jsonSchemaFactory.getSchema((jsonSchema.endsWith(".yaml") || jsonSchema.endsWith(".yml") ? yamlObjectMapper: jsonObjectMapper).readTree(in));
+            schema = createSchemaRegistry().getSchema(SchemaLocation.of(jsonSchema), in, getSchemaFormat());
             schema.initializeValidators();
         } catch (IOException e) {
             throw new RuntimeException("Cannot read JSON Schema from: " + jsonSchema, e);
         }
     }
 
+    private @NotNull InputFormat getSchemaFormat() {
+        return (jsonSchema.toLowerCase().endsWith(".yaml") || jsonSchema.toLowerCase().endsWith(".yml")) ? YAML : JSON;
+    }
+
+    private SchemaRegistry createSchemaRegistry() {
+        return SchemaRegistry.withDefaultDialect(schemaId, b -> b.schemaLoader(SchemaLoader.builder()
+                .schemaIdResolvers(r -> r.mappings(schemaMappings))
+                .resourceLoaders(rl -> rl.values(list -> list.addFirst(new MembraneSchemaLoader(resolver))))
+                .build()));
+    }
+
     public Outcome validateMessage(Exchange exc, Flow flow) throws Exception {
         return validateMessage(exc, flow, UTF_8);
     }
 
     public Outcome validateMessage(Exchange exc, Flow flow, Charset ignored) throws Exception {
 
         List<Error> assertions = inputFormat == YAML ?
-            handleMultipleYAMLDocuments(exc, flow) :
-            schema.validate(exc.getMessage(flow).getBodyAsStringDecoded(), inputFormat);
+                handleMultipleYAMLDocuments(exc, flow) :
+                schema.validate(exc.getMessage(flow).getBodyAsStringDecoded(), inputFormat);
 
         if (assertions.isEmpty()) {
             valid.incrementAndGet();
@@ -204,4 +209,8 @@ public long getInvalid() {
     public String getErrorTitle() {
         return "JSON validation failed";
     }
+
+    public void setSchemaMappings(Map<String, String> schemaMappings) {
+        this.schemaMappings = schemaMappings;
+    }
 }

core/src/main/java/com/predic8/membrane/core/interceptor/schemavalidation/json/SchemaMappings.java

@@ -0,0 +1,72 @@
+/* Copyright 2025 predic8 GmbH, www.predic8.com
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License. */
+
+package com.predic8.membrane.core.interceptor.schemavalidation.json;
+
+import com.predic8.membrane.annot.MCAttribute;
+import com.predic8.membrane.annot.MCChildElement;
+import com.predic8.membrane.annot.MCElement;
+import com.predic8.membrane.annot.Required;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+@MCElement(name = "schemaMappings")
+public class SchemaMappings {
+
+    private List<Schema> schemas = new ArrayList<>();
+
+    public Map<String, String> getSchemaMap() {
+        Map<String, String > referenceSchemas = new HashMap<>();
+        schemas.forEach(schema ->  referenceSchemas.put(schema.getId(), schema.getLocation()));
+        return referenceSchemas;
+    }
+
+    @Required
+    @MCChildElement
+    public void setSchemas(List<Schema> schemas) {
+        this.schemas = schemas;
+    }
+
+    public List<Schema> getSchemas() {
+        return schemas;
+    }
+
+    @MCElement(name = "schema")
+    public static class Schema {
+        private String id;
+
+        private String location;
+
+        @MCAttribute
+        public void setId(String id) {
+            this.id = id;
+        }
+
+        public String getId() {
+            return id;
+        }
+
+        @MCAttribute
+        public void setLocation(String location) {
+            this.location = location;
+        }
+
+        public String getLocation() {
+            return location;
+        }
+    }
+}

distribution/examples/validation/json-schema/schema-mappings/README.md

@@ -0,0 +1,51 @@
+# Validation - JSON Schema with Schema Mappings
+
+This sample explains how to set up and use the `validator` plugin with JSON Schemas that reference external schemas 
+by `$ref` URN/ID, and how to map those references to local files via `schemaMappings`.
+
+## Running the Example
+
+1. Go to the directory:
+   `<membrane-root>/examples/validation/json-schema/schema-mappings`
+
+2. Start `membrane.cmd` or `membrane.sh`.
+
+3. Look at `schemas/schema2000.json` and note the `$ref` to `urn:app:base_parameter_def`. Then open `schemas/base-param.json` and compare the schema to `good2000.json` and `bad2000.json`.
+
+4. Run `curl -H "Content-Type: application/json" -d @good2000.json http://localhost:2000/` on the console. Observe that you get a successful response.
+
+5. Run `curl -H "Content-Type: application/json" -d @bad2000.json http://localhost:2000/`. Observe that you get a validation error response.
+
+Keeping the router running, you can try a more complex setup with multiple referenced schemas.
+
+1. Have a look at `schemas/schema2001.json` and note the `$ref`s to `urn:app:base_parameter_def` and `urn:app:meta_def`. Then open `schemas/base-param.json` and `schemas/meta.json` and compare the schemas to `good2001.json` and `bad2001.json`.
+
+2. Run `curl -H "Content-Type: application/json" -d @good2001.json http://localhost:2001/`. Observe that you get a successful response.
+
+3. Run `curl -H "Content-Type: application/json" -d @bad2001.json http://localhost:2001/`. Observe that you get a validation error response.
+
+## How it is done
+
+In `proxies.xml`, each API configures a `<validator jsonSchema="...">`.
+The root schemas contain `$ref` references to URN/IDs, for example:
+
+- `urn:app:base_parameter_def#/$defs/BaseParameter`
+- `urn:app:meta_def#/$defs/Meta`
+
+To let Membrane resolve these URNs, you map them in the validator using:
+
+```xml
+<schemaMappings>
+  <schema id="urn:app:base_parameter_def" location="schemas/base-parameter.json"/>
+  <schema id="urn:app:meta_def" location="schemas/meta.json"/>
+</schemaMappings>
+````
+
+Only if validation succeeds, the request is forwarded to the backend (port 2002).
+
+---
+
+See:
+
+* [JSON Schema](https://json-schema.org/) documentation
+* [validator](https://www.membrane-api.io/docs/current/validator.html) reference

distribution/examples/validation/json-schema/schema-mappings/bad2000.json

@@ -0,0 +1,7 @@
+{
+  "param": {
+    "name": "limit"
+  },
+  "timestamp": "not-a-date",
+  "extra": true
+}

distribution/examples/validation/json-schema/schema-mappings/bad2001.json

@@ -0,0 +1,12 @@
+{
+  "params": [
+    {
+      "name": "mode",
+      "value": "fast",
+      "unexpected": "foo"
+    }
+  ],
+  "meta": {
+    "source": ""
+  }
+}

distribution/examples/validation/json-schema/schema-mappings/good2000.json

@@ -0,0 +1,7 @@
+{
+  "param": {
+    "name": "limit",
+    "value": 100
+  },
+  "timestamp": "2025-12-19T10:15:30Z"
+}

distribution/examples/validation/json-schema/schema-mappings/good2001.json

@@ -0,0 +1,16 @@
+{
+  "params": [
+    {
+      "name": "mode",
+      "value": "fast"
+    },
+    {
+      "name": "retries",
+      "value": 3
+    }
+  ],
+  "meta": {
+    "source": "curl",
+    "requestId": "REQ-12345678"
+  }
+}