Allow overriding the default logic for resolving imports.

gouttegd · gouttegd · commit b44606a0d07e · 2026-03-24T13:47:49.000Z
So far, the logic to resolve import declarations within a LinkML schema
has been embedded within the SchemaDocument class, and was not
modifiable.

This commit introduces a ISchemaResolver interface for an object that
can resolve an import name into a usable schema location
(ISchemaSource).

The pre-existing logic is moved to a default implementation of that
interface, and SchemaDocument is given an additional constructor that
can accept a ISchemaResolver provided by the client code -- thereby
giving client code the ability to customise the logic for resolving
imports as needed.

In addition, the default resolver now checks whether a schema name that
is supposed to point to a local file, actually points to an _existing_
file, and errors out if it does not.
diff --git a/core/src/main/java/org/incenp/linkml/schema/DefaultSchemaResolver.java b/core/src/main/java/org/incenp/linkml/schema/DefaultSchemaResolver.java
@@ -0,0 +1,81 @@
+/*
+ * LinkML-Java - LinkML library for Java
+ * Copyright © 2026 Damien Goutte-Gattat
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ *   (1) Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ *
+ *   (2) Redistributions in binary form must reproduce the above
+ *   copyright notice, this list of conditions and the following
+ *   disclaimer in the documentation and/or other materials provided
+ *   with the distribution.
+ *
+ *   (3) Neither the name of the copyright holder nor the names its
+ *   contributors may be used to endorse or promote products derived
+ *   from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+ * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+ * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+ * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+ * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
+ * WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package org.incenp.linkml.schema;
+
+import java.io.File;
+import java.net.MalformedURLException;
+
+/**
+ * The schema resolver that implements the default behaviour for resolving
+ * <code>imports</code> declarations within a LinkML schema.
+ * <p>
+ * If the name to resolve contains a colon, this resolver assumes it is a
+ * relative file name, and attempts to find it on the local file system.
+ * Otherwise, it assumes the name is a URI pointing to a remote resource.
+ * <p>
+ * Of note, this resolver automatically and silently redirects the
+ * <code>https://w3id.org/linkml/types.yaml</code> schema name to a version that
+ * is embedded with the LinkML-Java runtime. That schema is expected to be
+ * imported in virtually all LinkML schemas, so we don’t want to have to always
+ * fetch it from a remote server.
+ */
+public class DefaultSchemaResolver implements ISchemaResolver {
+
+    private final static String TYPES_SCHEMA = "https://w3id.org/linkml/types.yaml";
+    private final static String UNRESOLVABLE_SCHEMA = "Cannot resolve schema name '%s'";
+
+    @Override
+    public ISchemaSource resolve(String name, String base) throws InvalidSchemaException {
+        if (!name.contains(":")) {
+            // Local file, relative to the base directory
+            File file = new File(base, name);
+            if ( !file.exists() ) {
+                throw new InvalidSchemaException(String.format(UNRESOLVABLE_SCHEMA, name));
+            }
+            return new FileSchemaSource(file);
+        }
+
+        if ( name.equals(TYPES_SCHEMA) ) {
+            // Redirect the standard linkml:types schema to the embedded version.
+            return new EmbeddedSchemaSource("types.yaml");
+        }
+        try {
+            return new URLSchemaSource(name);
+        } catch ( MalformedURLException e ) {
+            throw new InvalidSchemaException(String.format(UNRESOLVABLE_SCHEMA, name), e);
+        }
+    }
+
+}
diff --git a/core/src/main/java/org/incenp/linkml/schema/ISchemaResolver.java b/core/src/main/java/org/incenp/linkml/schema/ISchemaResolver.java
@@ -0,0 +1,58 @@
+/*
+ * LinkML-Java - LinkML library for Java
+ * Copyright © 2026 Damien Goutte-Gattat
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ *   (1) Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ *
+ *   (2) Redistributions in binary form must reproduce the above
+ *   copyright notice, this list of conditions and the following
+ *   disclaimer in the documentation and/or other materials provided
+ *   with the distribution.
+ *
+ *   (3) Neither the name of the copyright holder nor the names its
+ *   contributors may be used to endorse or promote products derived
+ *   from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+ * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+ * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+ * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+ * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
+ * WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package org.incenp.linkml.schema;
+
+/**
+ * An interface to resolve the name of a schema into a {@link ISchemaSource}.
+ * <p>
+ * That interface is primarily intended to allow client code to customise the
+ * way that import declarations within a LinkML schema are resolved.
+ */
+public interface ISchemaResolver {
+
+    /**
+     * Resolves the given schema name into a schema source object.
+     * 
+     * @param name The name of the schema to resolve. Of note, if the name was
+     *             originally provided as a Curie, this method will receive the
+     *             <em>expanded</em> form of the original name.
+     * @param base The base location from which to resolve relative names.
+     * @return A {@link ISchemaSource} object that can be used to access the content
+     *         of the schema.
+     * @throws InvalidSchemaException If the name cannot be resolved into a schema
+     *                                source.
+     */
+    public ISchemaSource resolve(String name, String base) throws InvalidSchemaException;
+}
diff --git a/core/src/main/java/org/incenp/linkml/schema/SchemaDocument.java b/core/src/main/java/org/incenp/linkml/schema/SchemaDocument.java
@@ -36,7 +36,6 @@
 
 import java.io.File;
 import java.io.IOException;
-import java.net.MalformedURLException;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.HashMap;
@@ -63,10 +62,8 @@
  */
 public class SchemaDocument {
 
-    private final static String TYPES_SCHEMA = "https://w3id.org/linkml/types.yaml";
     private final static String INVALID_YAML = "Cannot read YAML document";
     private final static String INVALID_LINKML = "Cannot parse schema from YAML document";
-    private final static String UNRESOLVABLE_IMPORT = "Cannot resolve import name '%s'";
 
     private SchemaDefinition rootSchema;
     private List<SchemaDefinition> importedSchemas = new ArrayList<>();
@@ -78,6 +75,8 @@ public class SchemaDocument {
     private Map<String, Map<String, SlotDefinition>> allAttributes = new HashMap<>();
     private Map<String, Map<String, SlotDefinition>> allSlotUsages = new HashMap<>();
 
+    private ISchemaResolver importResolver;
+
     /**
      * Creates a new instance from the specified file.
      * 
@@ -86,6 +85,39 @@ public class SchemaDocument {
      * @throws InvalidSchemaException If the file is not a valid schema.
      */
     public SchemaDocument(File source) throws IOException, InvalidSchemaException {
+        importResolver = new DefaultSchemaResolver();
+        rootSchema = parseSchema(new FileSchemaSource(source));
+    }
+
+    /**
+     * Creates a new instance from the specified file, using a custom import
+     * resolver.
+     * 
+     * @param source         The source file from which to parse the LinkML schema.
+     * @param importResolver The resolver to use to resolve import names into schema
+     *                       source objects.
+     * @throws IOException            If we cannot read the specified file.
+     * @throws InvalidSchemaException If the file is not a valid schema.
+     */
+    public SchemaDocument(File source, ISchemaResolver importResolver) throws IOException, InvalidSchemaException {
+        this.importResolver = importResolver;
+        rootSchema = parseSchema(new FileSchemaSource(source));
+    }
+
+    /**
+     * Creates a new instance from the specified source, using a custom import
+     * resolver.
+     * 
+     * @param source         The source location from which to obtain the LinkML
+     *                       schema.
+     * @param importResolver The resolver to use to resolve import names into schema
+     *                       source objects.
+     * @throws IOException            If we cannot read the specified file.
+     * @throws InvalidSchemaException If the file is not a valid schema.
+     */
+    public SchemaDocument(ISchemaSource source, ISchemaResolver importResolver)
+            throws IOException, InvalidSchemaException {
+        this.importResolver = importResolver;
         rootSchema = parseSchema(source);
     }
 
@@ -225,13 +257,13 @@ public SlotDefinition getSlotUsage(String className, String slotName) {
     }
 
     // The entry point for the actual parsing code
-    private SchemaDefinition parseSchema(File file)
+    private SchemaDefinition parseSchema(ISchemaSource source)
             throws IOException, InvalidSchemaException {
         ObjectMapper mapper = new ObjectMapper(new YAMLFactory());
         ConverterContext ctx = new ConverterContext();
 
         // Parse the top-level schema and all its imports recursively
-        SchemaDefinition schema = parseSchema(new FileSchemaSource(file), mapper, ctx);
+        SchemaDefinition schema = parseSchema(source, mapper, ctx);
 
         try {
             // All schemas have been read, so we can resolve all references
@@ -264,7 +296,7 @@ private SchemaDefinition parseSchema(ISchemaSource source, ObjectMapper mapper,
         importedSources.add(source);
         if ( schema.getImports() != null ) {
             for ( String importName : schema.getImports() ) {
-                ISchemaSource importSource = resolveImport(importName, schema, source.getBase());
+                ISchemaSource importSource = importResolver.resolve(importName + ".yaml", source.getBase());
                 if ( !importedSources.contains(importSource) ) {
                     SchemaDefinition importedSchema = parseSchema(importSource, mapper, ctx);
                     importedSchemas.add(importedSchema);
@@ -311,30 +343,4 @@ private SchemaDefinition parseSchema(ISchemaSource source, ObjectMapper mapper,
 
         return schema;
     }
-
-    private ISchemaSource resolveImport(String name, SchemaDefinition schema, String base)
-            throws InvalidSchemaException {
-        name += ".yaml";
-        if ( !name.contains(":") ) {
-            // Local file, relative to the directory containing the importing schema
-            if ( base != null ) {
-                return new FileSchemaSource(base + File.separator + name);
-            } else {
-                return new FileSchemaSource(name);
-            }
-        }
-
-        if ( name.equals(TYPES_SCHEMA) ) {
-            // Redirect the standard linkml:types schema to the embedded version. That
-            // schema is expected to be imported in virtually all LinkML schemas, so we
-            // don't want to have to always fetch it from a remote server.
-            // FIXME: We should probably provide a way to override this behaviour.
-            return new EmbeddedSchemaSource("types.yaml");
-        }
-        try {
-            return new URLSchemaSource(name);
-        } catch ( MalformedURLException e ) {
-            throw new InvalidSchemaException(String.format(UNRESOLVABLE_IMPORT, name), e);
-        }
-    }
 }
