feat: Add --external-ref-mapping to import from external packages instead of generating (#3006)

* feat: Add --external-ref-mapping CLI option and config plumbing

Add a new --external-ref-mapping option that maps external $ref file
paths to Python import packages. When a $ref points to a mapped file,
an import statement is generated instead of a duplicate class definition.

This commit adds the option to the CLI argument parser, Config class,
GenerateConfig, ParserConfig, and their TypedDict counterparts. No
behavior change yet — the core logic follows in the next commit.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: Implement external ref mapping in JSON Schema parser

When --external-ref-mapping is provided, external $ref targets that
match a mapped file produce import-based DataTypes (via Import.from_full_path
and DataType.from_import) instead of loading and parsing the external file.

This follows the exact same pattern as the existing x-python-import
vendor extension, but configured externally via CLI rather than requiring
modifications to the schema YAML.

Three changes in jsonschema.py:
- __init__: normalize mapping file paths to absolute for reliable matching
- get_ref_data_type: check mapping before _load_ref_schema_object
- resolve_ref: skip loading/parsing for mapped external files

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* test: Add tests for --external-ref-mapping feature

Five test cases covering:
- Basic CLI usage: external refs produce imports, not class definitions
- No duplicate classes: mapped types are imported, not generated
- Regression: without the flag, behavior is unchanged
- Invalid format: missing '=' in mapping produces a clear error
- Programmatic API: GenerateConfig with external_ref_mapping dict

Test fixtures: api.yaml referencing common.yaml via $ref, with
expected output showing imports from the mapped package.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: Correct help text for --external-ref-mapping

With nargs="+", multiple mappings are passed after a single flag
invocation, not by repeating the flag. Updated help text to reflect this.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: resolve PR3006 CI and nested external ref mapping

* fix: address external-ref-mapping review feedback

* fix: validate non-empty external-ref-mapping pairs

* test: use assert helper for external ref mapping errors

* test: move external ref mapping cases into main openapi e2e

* test: fix absolute ref template for Windows yaml parsing

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Koudai Aono <koxudaxi@gmail.com>

Author: 3 people

src/datamodel_code_generator/__main__.py

@@ -317,6 +317,32 @@ def validate_class_decorators(cls, values: dict[str, Any]) -> dict[str, Any]:  #
             values["class_decorators"] = decorators
         return values
 
+    @model_validator(mode="before")  # ty: ignore
+    def validate_external_ref_mapping(cls, values: dict[str, Any]) -> dict[str, Any]:  # noqa: N805
+        """Parse external_ref_mapping from list of KEY=VALUE strings to dict."""
+        raw = values.get("external_ref_mapping")
+        if raw is not None and isinstance(raw, list):
+            mapping: dict[str, str] = {}
+            for item in raw:
+                if not isinstance(item, str) or "=" not in item:
+                    msg = (
+                        f"Invalid --external-ref-mapping format: {item!r}. "
+                        "Expected FILE_PATH=PYTHON_PACKAGE (e.g., '../common/schema.yaml=mypackage.models')"
+                    )
+                    raise Error(msg)
+                file_path, python_package = item.split("=", maxsplit=1)
+                file_path = file_path.strip()
+                python_package = python_package.strip()
+                if not file_path or not python_package:
+                    msg = (
+                        f"Invalid --external-ref-mapping format: {item!r}. "
+                        "Both FILE_PATH and PYTHON_PACKAGE must be non-empty."
+                    )
+                    raise Error(msg)
+                mapping[file_path] = python_package
+            values["external_ref_mapping"] = mapping
+        return values
+
     __validate_output_datetime_class_err: ClassVar[str] = (
         '`--output-datetime-class` only allows "datetime" for '
         f"`--output-model-type` {DataModelType.DataclassesDataclass.value}"
@@ -624,6 +650,7 @@ def validate_class_name_affix_scope(cls, v: str | ClassNameAffixScope | None) ->
     watch_delay: float = 0.5
     schema_version: Optional[str] = None  # noqa: UP045
     schema_version_mode: Optional[VersionMode] = None  # noqa: UP045
+    external_ref_mapping: Optional[dict[str, str]] = None  # noqa: UP045
 
     def merge_args(self, args: Namespace) -> None:
         """Merge command-line arguments into config."""
@@ -1070,6 +1097,7 @@ def run_generate_from_config(  # noqa: PLR0913, PLR0917
         default_value_overrides=default_value_overrides,
         schema_version=config.schema_version,
         schema_version_mode=config.schema_version_mode,
+        external_ref_mapping=config.external_ref_mapping,
     )
 
     if output is None and result is not None:  # pragma: no cover

src/datamodel_code_generator/_types/generate_config_dict.py

@@ -172,6 +172,7 @@ class GenerateConfigDict(TypedDict, closed=True):
     default_value_overrides: NotRequired[Mapping[str, Any] | None]
     schema_version: NotRequired[str | None]
     schema_version_mode: NotRequired[VersionMode | None]
+    external_ref_mapping: NotRequired[dict[str, str] | None]
 
 
 class ValidatorDefinition(TypedDict):

src/datamodel_code_generator/_types/parser_config_dicts.py

@@ -162,6 +162,7 @@ class ParserConfigDict(TypedDict):
     field_type_collision_strategy: NotRequired[FieldTypeCollisionStrategy | None]
     target_pydantic_version: NotRequired[TargetPydanticVersion | None]
     default_value_overrides: NotRequired[Mapping[str, Any] | None]
+    external_ref_mapping: NotRequired[dict[str, str] | None]
 
 
 class GraphQLParserConfigDict(ParserConfigDict, closed=True):

src/datamodel_code_generator/arguments.py

@@ -70,6 +70,21 @@ def _dataclass_arguments(value: str) -> DataclassArguments:
     return cast("DataclassArguments", result)
 
 
+def _external_ref_mapping(value: str) -> str:
+    """Validate FILE_PATH=PYTHON_PACKAGE mapping format."""
+    if "=" not in value:
+        msg = (
+            f"Invalid --external-ref-mapping format: {value!r}. "
+            "Expected FILE_PATH=PYTHON_PACKAGE (e.g., '../common/schema.yaml=mypackage.models')"
+        )
+        raise ArgumentTypeError(msg)
+    file_path, python_package = value.split("=", maxsplit=1)
+    if not file_path.strip() or not python_package.strip():
+        msg = f"Invalid --external-ref-mapping format: {value!r}. Both FILE_PATH and PYTHON_PACKAGE must be non-empty."
+        raise ArgumentTypeError(msg)
+    return value
+
+
 class SortingHelpFormatter(RawDescriptionHelpFormatter):
     """Help formatter that sorts arguments, adds color to section headers, and preserves epilog formatting."""
 
@@ -147,6 +162,15 @@ def start_section(self, heading: str | None) -> None:
     ),
     choices=[i.value for i in InputFileType],
 )
+base_options.add_argument(
+    "--external-ref-mapping",
+    nargs="+",
+    metavar="FILE_PATH=PYTHON_PACKAGE",
+    type=_external_ref_mapping,
+    help="Map external $ref file paths to Python import packages instead of generating duplicate classes. "
+    'Accepts one or more mappings after a single flag. Format: "path/to/schema.yaml=mypackage.models". '
+    "When a $ref points to a mapped file, an import statement is generated instead of a class definition.",
+)
 base_options.add_argument(
     "--output",
     help="Output file (default: stdout)",

src/datamodel_code_generator/cli_options.py

@@ -72,6 +72,7 @@ class CLIOptionMeta:
     "--encoding": CLIOptionMeta(name="--encoding", category=OptionCategory.BASE),
     "--schema-version": CLIOptionMeta(name="--schema-version", category=OptionCategory.BASE),
     "--schema-version-mode": CLIOptionMeta(name="--schema-version-mode", category=OptionCategory.BASE),
+    "--external-ref-mapping": CLIOptionMeta(name="--external-ref-mapping", category=OptionCategory.BASE),
     # ==========================================================================
     # Model Customization
     # ==========================================================================

src/datamodel_code_generator/config.py

@@ -208,6 +208,7 @@ class Config:
     default_value_overrides: Mapping[str, Any] | None = None
     schema_version: str | None = None
     schema_version_mode: VersionMode | None = None
+    external_ref_mapping: dict[str, str] | None = None
 
 
 class ParserConfig(BaseModel):
@@ -341,6 +342,7 @@ class Config:
     field_type_collision_strategy: FieldTypeCollisionStrategy | None = None
     target_pydantic_version: TargetPydanticVersion | None = None
     default_value_overrides: Mapping[str, Any] | None = None
+    external_ref_mapping: dict[str, str] | None = None
 
 
 class GraphQLParserConfig(ParserConfig):

src/datamodel_code_generator/parser/jsonschema.py

@@ -702,6 +702,17 @@ def __init__(
         self.raw_obj: dict[str, YamlValue] = {}
         self._root_id: Optional[str] = None  # noqa: UP045
         self._root_id_base_path: Optional[str] = None  # noqa: UP045
+
+        # Normalize external ref mapping paths to absolute for reliable matching
+        raw_mapping = self.config.external_ref_mapping
+        self._external_ref_mapping: dict[str, str] = {}
+        if raw_mapping:
+            for file_path, python_package in raw_mapping.items():
+                if is_url(file_path):
+                    self._external_ref_mapping[file_path] = python_package
+                else:
+                    abs_path = str((self.base_path / file_path).resolve())
+                    self._external_ref_mapping[abs_path] = python_package
         self.reserved_refs: defaultdict[tuple[str, ...], set[str]] = defaultdict(set)
         self._dynamic_anchor_index: dict[tuple[str, ...], dict[str, str]] = {}
         self._recursive_anchor_index: dict[tuple[str, ...], list[str]] = {}
@@ -1324,8 +1335,71 @@ def _get_data_type(type_: str, format__: str) -> DataType:
             return self.data_type(data_types=[data_type], is_optional=True)
         return data_type
 
+    def _resolve_external_ref_mapping(self, ref: str) -> tuple[str, str] | None:
+        """Resolve a ref and return mapped package + fragment if configured."""
+        if not self._external_ref_mapping:
+            return None
+
+        def _resolve_lookup_key(file_part: str) -> str:
+            if is_url(file_part):
+                return file_part
+            path = Path(file_part)
+            if path.is_absolute():
+                return str(path.resolve())
+            base_path = self.model_resolver.current_base_path or self.base_path
+            return str((base_path / path).resolve())
+
+        candidate_refs = [ref]
+        resolved_ref = self.model_resolver.resolve_ref(ref)
+        if resolved_ref not in candidate_refs:
+            candidate_refs.append(resolved_ref)
+
+        for candidate_ref in candidate_refs:
+            if "#" not in candidate_ref:
+                continue
+            file_part, fragment = candidate_ref.split("#", maxsplit=1)
+            if not file_part:
+                continue
+            lookup_key = _resolve_lookup_key(file_part)
+            if python_package := self._external_ref_mapping.get(lookup_key):
+                return python_package, fragment
+
+        return None
+
+    def _check_external_ref_mapping(self, ref: str) -> DataType | None:
+        """Check if a $ref matches an external ref mapping and return an import-based DataType.
+
+        Splits the ref into file path + JSON pointer fragment, resolves the file path
+        to absolute, and checks against the normalized mapping. If matched, constructs
+        an import from the mapped package and the class name extracted from the fragment.
+
+        Returns None if no mapping matches, allowing the caller to fall through
+        to normal ref resolution.
+        """
+        mapped = self._resolve_external_ref_mapping(ref)
+        if mapped is None:
+            return None
+        python_package, fragment = mapped
+
+        # Extract and normalize class name from fragment to match generated model naming.
+        raw_name = unescape_json_pointer_segment(fragment.rstrip("/").rsplit("/", maxsplit=1)[-1])
+        if not raw_name:
+            return None
+        class_name = self.model_resolver.get_class_name(raw_name, unique=False).name
+
+        # Construct import — same pattern as x-python-import
+        full_path = f"{python_package}.{class_name}"
+        import_ = Import.from_full_path(full_path)
+        self.imports.append(import_)
+        return self.data_type.from_import(import_)
+
     def get_ref_data_type(self, ref: str) -> DataType:
         """Get a data type from a reference string."""
+        # Check external ref mapping before loading the schema
+        mapped = self._check_external_ref_mapping(ref)
+        if mapped is not None:
+            return mapped
+
         ref_schema = self._load_ref_schema_object(ref)
         x_python_import = ref_schema.extras.get("x-python-import")
         if isinstance(x_python_import, dict):
@@ -3803,6 +3877,12 @@ def _get_ref_body_from_remote(self, resolved_ref: str) -> dict[str, YamlValue]:
 
     def resolve_ref(self, object_ref: str) -> Reference:
         """Resolve a reference by loading and parsing the referenced schema."""
+        # If the ref is mapped to an external package, mark as loaded and skip parsing
+        if self._resolve_external_ref_mapping(object_ref) is not None:
+            reference = self.model_resolver.add_ref(object_ref)
+            reference.loaded = True
+            return reference
+
         reference = self.model_resolver.add_ref(object_ref)
         if reference.loaded:
             return reference

tests/data/expected/main/input_model/config_class.py

@@ -252,6 +252,7 @@ class GenerateConfig(TypedDict, closed=True):
     default_value_overrides: NotRequired[Mapping[str, Any] | None]
     schema_version: NotRequired[str | None]
     schema_version_mode: NotRequired[VersionMode | None]
+    external_ref_mapping: NotRequired[dict[str, str] | None]
 
 
 class ValidatorDefinition(TypedDict):

tests/data/expected/main/openapi/external_ref_mapping.py

@@ -0,0 +1,20 @@
+# generated by datamodel-codegen:
+#   filename:  api.yaml
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from mypackage.shared.models import Error, User
+from pydantic import BaseModel
+
+
+class UserResponse(BaseModel):
+    user: User
+    request_id: str
+
+
+class ErrorResponse(BaseModel):
+    error: Error
+    timestamp: datetime

tests/data/expected/main/openapi/external_ref_mapping_nested.py

@@ -0,0 +1,16 @@
+# generated by datamodel-codegen:
+#   filename:  api_nested.yaml
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from mypackage.shared.models import User
+from pydantic import BaseModel
+
+
+class UserAlias(BaseModel):
+    __root__: User
+
+
+class UserResponse(BaseModel):
+    user: UserAlias