fix: resolve cross-file discriminator mapping references (#115)

`discriminator.mapping` and `defaultMapping` values are URI references
that live outside the JSON Schema vocabulary, so the schema compiler
never saw them. Planning resolved them lazily after the compiled graph
had been rebased onto portable identifiers, so any relative or
cross-file value failed with `invalid_discriminator_mapping` even though
the same URI worked in `$ref`. Mapping values were also resolved
relative to the union schema rather than the schema that owns the
discriminator.

The schema engine gains a generic `extra_references` compilation hook:
callers name additional reference strings inside schema objects, keyed
by a JSON Pointer relative to the schema. They are resolved like `$ref`
before rebasing, retrieving target resources when needed, and recorded
in the reference table. Failures to retrieve or resolve them are
recorded for `reference_failure` instead of aborting compilation;
retrieved documents that fail to compile stay fatal. Rebasing carries
the bindings and failures across and rewrites the resolved strings.

Normalization declares URI-shaped mapping values through the hook (bare
schema names are left alone per OAS 3.1.1), and planning reads the
recorded binding for the discriminator owner's node, reporting recorded
failures as located diagnostics.

Fixes #114

Author: tanmaykm

docs/src/models.md

@@ -8,7 +8,9 @@ Implemented model behavior includes:
 
 - objects, arrays, tuples, dictionaries, primitives, enums, and nullable types;
 - required, optional, and explicit-null values;
-- `allOf`, `oneOf`, `anyOf`, and discriminators;
+- `allOf`, `oneOf`, `anyOf`, and discriminators, whose `mapping` and
+  `defaultMapping` values may be same-document, relative, or cross-file URI
+  references resolved like `$ref`;
 - recursive models and recursive aliases;
 - `additionalProperties`, `patternProperties`, `propertyNames`, and closed
   objects;

docs/src/pipeline.md

@@ -123,6 +123,10 @@ The default retriever has conservative access rules:
 - HTTP redirects are not followed.
 - Unsupported URI schemes are rejected.
 
+Discriminator `mapping` and `defaultMapping` URI references are retrieved under
+the same rules as `$ref`, relative to the document that holds the
+`discriminator`.
+
 Pass an `OpenAPI.SchemaEngine.Resources.AbstractRetriever` with `retriever=...`
 when an application needs another retrieval policy or an in-memory resource
 store. Resource size and count limits still apply.

src/normalize.jl

@@ -655,6 +655,46 @@ function _portable_schema_ids(context::NormalizationContext, schemas)
     return output
 end
 
+# JSON Pointer, relative to a schema object, of a discriminator mapping value.
+# Planning derives the same key to look up the binding the compiler recorded.
+function _discriminator_mapping_pointer(tag::AbstractString)
+    return string(Resources.JSONPointer(("discriminator", "mapping", String(tag))))
+end
+
+const _DISCRIMINATOR_DEFAULT_POINTER = "/discriminator/defaultMapping"
+
+# OAS 3.1.1 §4.8.25: a mapping value is either a schema name or a URI
+# reference, and an ambiguous bare value such as "Cat" is a schema name; authors
+# write "./Cat" to force a URI reference. Only URI-shaped values are references.
+function _uri_reference_mapping_value(value::AbstractString)
+    return occursin('/', value) || occursin('#', value) || occursin(':', value)
+end
+
+# `discriminator.mapping` values are URI references that live outside the JSON
+# Schema vocabulary, so the schema engine does not see them as references.
+# Declare them as optional references so the compiler resolves them against the
+# schema's real base URI, retrieving cross-file targets like `\$ref`, before the
+# graph is rebased onto portable identifiers. Planning reads the bindings.
+function _discriminator_references(schema::AbstractDict)
+    discriminator = get(schema, "discriminator", nothing)
+    discriminator isa AbstractDict || return ()
+    references = Tuple{String,String}[]
+    mapping = get(discriminator, "mapping", nothing)
+    if mapping isa AbstractDict
+        for tag in sort!(String[String(tag) for tag in keys(mapping)])
+            value = mapping[tag]
+            value isa AbstractString && _uri_reference_mapping_value(value) ||
+                continue
+            push!(references, (_discriminator_mapping_pointer(tag), String(value)))
+        end
+    end
+    default = get(discriminator, "defaultMapping", nothing)
+    if default isa AbstractString && _uri_reference_mapping_value(default)
+        push!(references, (_DISCRIMINATOR_DEFAULT_POINTER, String(default)))
+    end
+    return references
+end
+
 function _compile_schemas!(context::NormalizationContext)
     isempty(context.schema_cache) && return
     handles = sort(
@@ -678,6 +718,7 @@ function _compile_schemas!(context::NormalizationContext)
             max_resources = context.resolver.max_resources,
             max_nodes = context.resolver.max_nodes,
             max_depth = context.resolver.max_depth,
+            extra_references = _discriminator_references,
         )
     catch error
         location = error isa SchemaEngine.CompilationError ? error.location : first(roots)

src/planning.jl

@@ -989,6 +989,52 @@ function _reference_view(view::SchemaView, reference::AbstractString)
     )
 end
 
+# Resolve a discriminator `mapping` or `defaultMapping` value. The schema
+# compiler already resolved URI-shaped values (see `_discriminator_references`)
+# against the pre-rebase base URI of the schema that owns the discriminator,
+# retrieving cross-file targets, and recorded either the binding or a failure.
+# Values the compiler was not asked about fall back to same-document lookup.
+# Emit a diagnostic with `code` and return `nothing` when the value does not
+# name a schema.
+function _discriminator_target(
+    context,
+    owner::SchemaView,
+    pointer::String,
+    reference::AbstractString,
+    code::Symbol,
+    label::String,
+)
+    compiled = owner.compiled
+    location = SourceLocation(owner.node.resource, owner.node.pointer)
+    if compiled !== nothing
+        target = SchemaEngine.reference_target(compiled, owner.node, pointer)
+        if target !== nothing
+            resource = Resources.resource(compiled.registry, target.resource)
+            value = Resources.resolve(resource.contents, target.pointer)
+            return SchemaView(value, target, owner.version, compiled)
+        end
+        failure = SchemaEngine.reference_failure(compiled, owner.node, pointer)
+        if failure !== nothing
+            _error!(context.bag, code, "cannot resolve $label: $failure", location)
+            return nothing
+        end
+    end
+    target = try
+        _reference_view(owner, reference)
+    catch error
+        _error!(
+            context.bag,
+            code,
+            "cannot resolve $label: $(sprint(showerror, error))",
+            location,
+        )
+        return nothing
+    end
+    target === nothing &&
+        _error!(context.bag, code, "$label does not resolve to a schema", location)
+    return target
+end
+
 function _plan_union!(context, view, suggested, mode, keyword)
     resolved = _resolved_view(view)
     union_owner = something(_keyword_owner(resolved, keyword), resolved)
@@ -1035,27 +1081,15 @@ function _plan_union!(context, view, suggested, mode, keyword)
        get(discriminator, "mapping", nothing) isa AbstractDict
         for (tag, reference) in discriminator["mapping"]
             reference isa AbstractString || continue
-            target = try
-                _reference_view(resolved, reference)
-            catch error
-                _error!(
-                    context.bag,
-                    :invalid_discriminator_mapping,
-                    "cannot resolve discriminator mapping $(repr(tag)): $(sprint(showerror, error))",
-                    SourceLocation(resolved.node.resource, resolved.node.pointer),
-                )
-                missing
-            end
-            target === missing && continue
-            if target === nothing
-                _error!(
-                    context.bag,
-                    :invalid_discriminator_mapping,
-                    "discriminator mapping $(repr(tag)) does not resolve to a schema",
-                    SourceLocation(resolved.node.resource, resolved.node.pointer),
-                )
-                continue
-            end
+            target = _discriminator_target(
+                context,
+                discriminator_owner,
+                _discriminator_mapping_pointer(tag),
+                reference,
+                :invalid_discriminator_mapping,
+                "discriminator mapping $(repr(tag))",
+            )
+            target === nothing && continue
             target_type = _type_for!(
                 context,
                 target,
@@ -1071,27 +1105,15 @@ function _plan_union!(context, view, suggested, mode, keyword)
     default_mapping = nothing
     if discriminator isa AbstractDict &&
        get(discriminator, "defaultMapping", nothing) isa AbstractString
-        target = try
-            _reference_view(resolved, discriminator["defaultMapping"])
-        catch error
-            _error!(
-                context.bag,
-                :invalid_discriminator_default,
-                "cannot resolve discriminator defaultMapping: $(sprint(showerror, error))",
-                SourceLocation(resolved.node.resource, resolved.node.pointer),
-            )
-            missing
-        end
-        if target === missing
-            nothing
-        elseif target === nothing
-            _error!(
-                context.bag,
-                :invalid_discriminator_default,
-                "discriminator defaultMapping does not resolve to a schema",
-                SourceLocation(resolved.node.resource, resolved.node.pointer),
-            )
-        else
+        target = _discriminator_target(
+            context,
+            discriminator_owner,
+            _DISCRIMINATOR_DEFAULT_POINTER,
+            discriminator["defaultMapping"],
+            :invalid_discriminator_default,
+            "discriminator defaultMapping",
+        )
+        if target !== nothing
             target_type = _type_for!(context, target, suggested * "Default", mode)
             push!(types, target_type)
             default_mapping = target.node => target_type