URI scheme support in CatalogConfig

Implement equivalent transparent file:// URI parsing support in
CatalogConfig.fromPath and BasicCatalog.getConfig. Unsupported schemes
are correctly rejected, and robust unit tests are included.

Port of Python SDK commit 90a0a19

Author: jgindin

agent_sdks/kotlin/src/main/kotlin/com/google/a2ui/basic_catalog/BasicCatalogProvider.kt

@@ -23,6 +23,7 @@ import com.google.a2ui.core.schema.A2uiConstants
 import com.google.a2ui.core.schema.A2uiVersion
 import com.google.a2ui.core.schema.CatalogConfig
 import com.google.a2ui.core.schema.SchemaResourceLoader
+import com.google.a2ui.core.schema.resolveExamplesPath
 import kotlinx.serialization.json.JsonObject
 import kotlinx.serialization.json.JsonPrimitive
 
@@ -91,6 +92,6 @@ object BasicCatalog {
     CatalogConfig(
       name = BASIC_CATALOG_NAME,
       provider = BundledCatalogProvider(version),
-      examplesPath = examplesPath,
+      examplesPath = resolveExamplesPath(examplesPath),
     )
 }

agent_sdks/kotlin/src/main/kotlin/com/google/a2ui/core/schema/Catalog.kt

@@ -42,9 +42,47 @@ data class CatalogConfig(
     /** Create a [CatalogConfig] using a [FileSystemCatalogProvider]. */
     @JvmStatic
     @JvmOverloads
-    fun fromPath(name: String, catalogPath: String, examplesPath: String? = null): CatalogConfig =
-      CatalogConfig(name, FileSystemCatalogProvider(catalogPath), examplesPath)
+    fun fromPath(name: String, catalogPath: String, examplesPath: String? = null): CatalogConfig {
+      val uri =
+        try {
+          java.net.URI(catalogPath)
+        } catch (e: Exception) {
+          null
+        }
+      val scheme = uri?.scheme?.lowercase()
+
+      val provider =
+        when {
+          scheme == null || scheme == "file" -> {
+            val path =
+              if (scheme == "file") java.nio.file.Paths.get(uri).toString() else catalogPath
+            FileSystemCatalogProvider(path)
+          }
+          scheme == "http" || scheme == "https" ->
+            throw NotImplementedError("HTTP support is coming soon.")
+          else -> throw IllegalArgumentException("Unsupported catalog URL scheme: $catalogPath")
+        }
+
+      return CatalogConfig(name, provider, resolveExamplesPath(examplesPath))
+    }
+  }
+}
+
+internal fun resolveExamplesPath(path: String?): String? {
+  if (path != null) {
+    val uri =
+      try {
+        java.net.URI(path)
+      } catch (e: Exception) {
+        null
+      }
+    val scheme = uri?.scheme?.lowercase()
+    if (scheme == null || scheme == "file") {
+      return if (scheme == "file") java.nio.file.Paths.get(uri).toString() else path
+    }
+    throw IllegalArgumentException("Unsupported examples URL scheme: $path")
   }
+  return null
 }
 
 /** Represents a processed component catalog with its schema. */

agent_sdks/kotlin/src/main/kotlin/com/google/a2ui/core/schema/CatalogProvider.kt

@@ -32,7 +32,7 @@ interface A2uiCatalogProvider {
 }
 
 /** Loads catalog definition from the local filesystem. */
-class FileSystemCatalogProvider(private val path: String) : A2uiCatalogProvider {
+class FileSystemCatalogProvider(val path: String) : A2uiCatalogProvider {
   override fun load(): JsonObject {
     try {
       val file = File(path)

agent_sdks/kotlin/src/test/kotlin/com/google/a2ui/core/schema/CatalogTest.kt

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * 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
+ *
+ *      https://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.google.a2ui.core.schema
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertFailsWith
+import kotlin.test.assertNull
+import kotlin.test.assertTrue
+
+class CatalogTest {
+
+  @Test
+  fun resolvesExamplesPathHandling() {
+    assertNull(resolveExamplesPath(null))
+    assertEquals("/absolute/examples", resolveExamplesPath("/absolute/examples"))
+    assertEquals("/absolute/examples", resolveExamplesPath("file:///absolute/examples"))
+
+    val e =
+      assertFailsWith<IllegalArgumentException> {
+        resolveExamplesPath("https://a2ui.org/examples")
+      }
+    assertTrue(e.message?.contains("Unsupported examples URL scheme") == true)
+  }
+
+  @Test
+  fun stripsPrefixFromCatalogConfigFromPathSchemes() {
+    // Test local path
+    var config =
+      CatalogConfig.fromPath(name = "test_file", catalogPath = "relative_path/to/catalog.json")
+    assertEquals(
+      "relative_path/to/catalog.json",
+      (config.provider as FileSystemCatalogProvider).path,
+    )
+
+    // Test file:// scheme
+    config =
+      CatalogConfig.fromPath(
+        name = "test_file",
+        catalogPath = "file:///absolute_path/to/catalog.json",
+      )
+    assertEquals(
+      "/absolute_path/to/catalog.json",
+      (config.provider as FileSystemCatalogProvider).path,
+    )
+
+    // Test HTTP raises NotImplementedError
+    val eHttp =
+      assertFailsWith<NotImplementedError> {
+        CatalogConfig.fromPath(name = "test_http", catalogPath = "http://a2ui.org/catalog.json")
+      }
+    assertTrue(eHttp.message?.contains("HTTP support is coming soon.") == true)
+
+    // Test unsupported scheme raises IllegalArgumentException
+    val eFtp =
+      assertFailsWith<IllegalArgumentException> {
+        CatalogConfig.fromPath(name = "test_ftp", catalogPath = "ftp://a2ui.org/catalog.json")
+      }
+    assertTrue(eFtp.message?.contains("Unsupported catalog URL scheme") == true)
+  }
+
+  @Test
+  fun resolvesExamplesPathInBasicCatalogGetConfig() {
+    val config =
+      com.google.a2ui.basic_catalog.BasicCatalog.getConfig(
+        version = A2uiVersion.VERSION_0_9,
+        examplesPath = "file:///absolute/examples",
+      )
+    assertEquals("/absolute/examples", config.examplesPath)
+  }
+}