netbox-super-cli 1.6.1__tar.gz → 1.6.2__tar.gz

{netbox_super_cli-1.6.1 → netbox_super_cli-1.6.2}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to netbox-super-cli are tracked here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) loosely. From v1.0.0 onward, releases follow [Semantic Versioning](https://semver.org/) and the version in `pyproject.toml` matches the git tag. Pre-1.0 milestones (Phase 1-5) were pinned by tag while `pyproject.toml` stayed at `0.0.1`.
 
+## v1.6.2 — 2026-06-30
+
+Patch release. Fixes TUI foreign-key pickers resolving to the wrong resource.
+
+### Fixed
+
+- **Filtering/editing by `role` (and other FKs) opened the wrong picker**
+  ([#139]). Choosing a `role` value when filtering devices listed IPAM roles
+  instead of device roles, because the picker matched the bare field name across
+  apps. Foreign-key pickers now resolve to the field's true target read from the
+  OpenAPI schema (a device/VM `role` → dcim device-roles, a prefix `role` → ipam
+  roles, a contact-assignment `role` → tenancy contact-roles), and fall back to a
+  context-qualified name match. This also corrects `group`, `type`, and similar
+  cross-app FK fields. Cached schemas rebuild once to pick up the new metadata.
+
+[#139]: https://github.com/thomaschristory/netbox-super-cli/issues/139
+
 ## v1.6.1 — 2026-06-29
 
 Patch release. Fixes the TUI bulk-edit form so custom-field edits are visible and

{netbox_super_cli-1.6.1 → netbox_super_cli-1.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: netbox-super-cli
-Version: 1.6.1
+Version: 1.6.2
 Summary: Dynamic NetBox CLI generated from the live OpenAPI schema.
 Project-URL: Homepage, https://github.com/thomaschristory/netbox-super-cli
 Project-URL: Documentation, https://thomaschristory.github.io/netbox-super-cli/

{netbox_super_cli-1.6.1 → netbox_super_cli-1.6.2}/nsc/_version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the package version."""
 
-__version__ = "1.6.1"
+__version__ = "1.6.2"

{netbox_super_cli-1.6.1 → netbox_super_cli-1.6.2}/nsc/builder/build.py

@@ -10,8 +10,10 @@ import re
 from typing import Literal
 
 from nsc.model.command_model import (
+    MODEL_FORMAT_VERSION,
     CommandModel,
     FieldShape,
+    FkResourceRef,
     HttpMethod,
     Operation,
     Parameter,
@@ -77,6 +79,8 @@ def build_command_model(loaded: LoadedSchema) -> CommandModel:
         info_version=doc.info.version,
         schema_hash=loaded.hash,
         tags=final_tags,
+        fk_resources=_build_fk_resources(doc),
+        format_version=MODEL_FORMAT_VERSION,
     )
 
 
@@ -346,10 +350,107 @@ def _flat_fields(schema: SchemaObject, doc: OpenAPIDocument) -> dict[str, FieldS
         resolved = _resolve_ref(prop, doc) or prop
         primitive = _primitive(resolved)
         enum = [str(v) for v in resolved.enum] if resolved.enum else None
-        out[name] = FieldShape(primitive=primitive, enum=enum, nullable=resolved.nullable)
+        out[name] = FieldShape(
+            primitive=primitive,
+            enum=enum,
+            nullable=resolved.nullable,
+            fk_target=_fk_target_component(prop),
+        )
     return out
 
 
+def _ref_component_name(ref: str | None) -> str | None:
+    prefix = "#/components/schemas/"
+    if isinstance(ref, str) and ref.startswith(prefix):
+        return ref[len(prefix) :]
+    return None
+
+
+def _normalize_serializer(name: str) -> str:
+    """Reduce a serializer name to a key shared by a field's FK brief and the
+    target resource's list serializer: ``BriefDeviceRoleRequest`` → ``DeviceRole``
+    and ``DeviceWithConfigContext`` → ``Device`` both land on the same base."""
+    return name.removeprefix("Brief").removesuffix("Request").removesuffix("WithConfigContext")
+
+
+def _branch_ref(raw: dict[str, object]) -> str | None:
+    """The `$ref` of a oneOf/anyOf branch, unwrapping a nullable `allOf` wrapper."""
+    ref = raw.get("$ref")
+    if isinstance(ref, str):
+        return ref
+    inner = raw.get("allOf")
+    if isinstance(inner, list):
+        for sub in inner:
+            if isinstance(sub, dict) and isinstance(sub.get("$ref"), str):
+                return str(sub["$ref"])
+    return None
+
+
+def _fk_target_component(prop: SchemaObject) -> str | None:
+    """Target serializer name for a writable FK (`oneOf[integer, Brief<X>Request]`).
+
+    A `oneOf`/`anyOf` mixing an integer branch with a brief-ref branch is NetBox's
+    way of saying "an id or an object" — i.e. a foreign key. Returns `<X>`.
+    """
+    extras = prop.model_extra or {}
+    branches = extras.get("oneOf") or extras.get("anyOf") or []
+    if not isinstance(branches, list):
+        return None
+    has_integer = False
+    ref_name: str | None = None
+    for raw in branches:
+        if not isinstance(raw, dict):
+            continue
+        if raw.get("type") == "integer":
+            has_integer = True
+        name = _ref_component_name(_branch_ref(raw))
+        if name is not None:
+            ref_name = name
+    if has_integer and ref_name is not None:
+        return _normalize_serializer(ref_name)
+    return None
+
+
+def _list_serializer_name(get_op: SchemaOperation, doc: OpenAPIDocument) -> str | None:
+    """The item serializer name a collection GET returns (Paginated<X>List → <X>)."""
+    response = get_op.responses.get("200")
+    if response is None:
+        return None
+    media = response.content.get("application/json")
+    if media is None or media.schema_ is None:
+        return None
+    paginated_name = _ref_component_name(media.schema_.ref)
+    if paginated_name is None:
+        return None
+    paginated = doc.components.schemas.get(paginated_name)
+    if paginated is None or not paginated.properties:
+        return None
+    results = paginated.properties.get("results")
+    if results is None or results.items is None:
+        return None
+    return _ref_component_name(results.items.ref)
+
+
+def _build_fk_resources(doc: OpenAPIDocument) -> dict[str, FkResourceRef]:
+    """Index each list endpoint's item serializer to its owning resource."""
+    index: dict[str, FkResourceRef] = {}
+    for path in sorted(doc.paths):
+        get_op = doc.paths[path].get
+        if get_op is None or not get_op.tags:
+            continue
+        tag_name = get_op.tags[0]
+        resource_name, is_collection = _resource_from_path(path, tag_name)
+        if resource_name is None or not is_collection:
+            continue
+        serializer = _list_serializer_name(get_op, doc)
+        if serializer is None:
+            continue
+        index.setdefault(
+            _normalize_serializer(serializer), FkResourceRef(tag=tag_name, resource=resource_name)
+        )
+    return index
+
+
 def _primitive(schema: SchemaObject) -> PrimitiveType:
     if schema.type is None:
         return PrimitiveType.UNKNOWN

{netbox_super_cli-1.6.1 → netbox_super_cli-1.6.2}/nsc/cache/store.py

@@ -14,7 +14,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from nsc.config.models import Config, Profile
-from nsc.model.command_model import CommandModel
+from nsc.model.command_model import MODEL_FORMAT_VERSION, CommandModel
 
 _LOG = logging.getLogger(__name__)
 _PROFILE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$")
@@ -76,6 +76,10 @@ class CacheStore:
         if model.schema_hash != schema_hash:
             _LOG.warning("cache: hash mismatch for %s (file says %s)", target, model.schema_hash)
             return None
+        if model.format_version != MODEL_FORMAT_VERSION:
+            # Built by an older nsc whose model lacks current metadata; rebuild.
+            _LOG.info("cache: stale model format for %s; rebuilding", target)
+            return None
         return model
 
     def save(self, profile: str, model: CommandModel) -> Path:

{netbox_super_cli-1.6.1 → netbox_super_cli-1.6.2}/nsc/model/command_model.py

@@ -43,6 +43,12 @@ class PrimitiveType(StrEnum):
     UNKNOWN = "unknown"
 
 
+# Bumped whenever the builder changes the shape of a CommandModel in a way that
+# makes older cached models incomplete (not just a schema-body change). The cache
+# rebuilds entries stamped with an older version. See nsc/cache/store.py.
+MODEL_FORMAT_VERSION = 1
+
+
 class _Frozen(BaseModel):
     model_config = ConfigDict(frozen=True, extra="forbid")
 
@@ -60,6 +66,10 @@ class FieldShape(_Frozen):
     primitive: PrimitiveType = PrimitiveType.UNKNOWN
     enum: list[str] | None = None
     nullable: bool = False
+    # For a writable foreign key (`oneOf[integer, Brief<X>Request]`), the target
+    # serializer name `<X>` (e.g. "DeviceRole"); None for non-FK fields. Pairs
+    # with CommandModel.fk_resources to find the target resource.
+    fk_target: str | None = None
 
 
 class RequestBodyShape(_Frozen):
@@ -97,6 +107,13 @@ class Tag(_Frozen):
     resources: dict[str, Resource] = Field(default_factory=dict)
 
 
+class FkResourceRef(_Frozen):
+    """Where a foreign-key serializer lives: which `tag` and `resource` serve it."""
+
+    tag: str
+    resource: str
+
+
 class CommandModel(_Frozen):
     """The full normalized tree: tags → resources → operations."""
 
@@ -104,6 +121,11 @@ class CommandModel(_Frozen):
     info_version: str
     schema_hash: str
     tags: dict[str, Tag] = Field(default_factory=dict)
+    # serializer name (e.g. "DeviceRole") → the resource whose list endpoint
+    # serves it. Lets the TUI resolve an FK picker to its true target.
+    fk_resources: dict[str, FkResourceRef] = Field(default_factory=dict)
+    # Defaults to 0 so models written before versioning read as stale and rebuild.
+    format_version: int = 0
 
     def iter_operations(self) -> Iterator[tuple[str, str, Operation]]:
         """Yield `(tag, resource, operation)` triples in deterministic order."""

{netbox_super_cli-1.6.1 → netbox_super_cli-1.6.2}/nsc/tui/fk.py

@@ -20,7 +20,7 @@ from urllib.parse import urlsplit
 
 from pydantic import BaseModel, ConfigDict
 
-from nsc.model.command_model import CommandModel, Operation
+from nsc.model.command_model import CommandModel, Operation, Resource
 from nsc.tui.relations import singularize
 
 FkKind = Literal["picker", "raw_id"]
@@ -51,12 +51,27 @@ class FkTarget(BaseModel):
     hint: str | None = None
 
 
-def resolve_fk_target(field_name: str, current_value: Any, model: CommandModel) -> FkTarget:
+def resolve_fk_target(
+    field_name: str,
+    current_value: Any,
+    model: CommandModel,
+    *,
+    context_tag: str | None = None,
+    context_resource: str | None = None,
+) -> FkTarget:
     from_url = _resolve_from_url(field_name, current_value, model)
     if from_url is not None:
         return from_url
 
-    by_name = _resolve_by_field_name(field_name, model)
+    from_schema = _resolve_from_schema_fk(
+        field_name, model, context_tag=context_tag, context_resource=context_resource
+    )
+    if from_schema is not None:
+        return from_schema
+
+    by_name = _resolve_by_field_name(
+        field_name, model, context_tag=context_tag, context_resource=context_resource
+    )
     if by_name is not None:
         return by_name
 
@@ -67,6 +82,67 @@ def resolve_fk_target(field_name: str, current_value: Any, model: CommandModel)
     )
 
 
+def _resolve_from_schema_fk(
+    field_name: str,
+    model: CommandModel,
+    *,
+    context_tag: str | None,
+    context_resource: str | None,
+) -> FkTarget | None:
+    """Resolve via the schema-declared FK target of the owning resource's field.
+
+    The owning resource's create/update body types the field as a FK to a named
+    serializer (`fk_target`); `model.fk_resources` maps that serializer to the
+    resource that serves it. This resolves even when the field and resource names
+    diverge (a virtual-machine's `role` targets dcim `device-roles`).
+    """
+    if context_resource is None:
+        return None
+    resource = _find_resource(model, context_resource, prefer_tag=context_tag)
+    if resource is None:
+        return None
+    base = field_name[:-3] if field_name.endswith("_id") else field_name
+    component = _field_fk_target(resource, base)
+    if component is None:
+        return None
+    ref = model.fk_resources.get(component)
+    if ref is None:
+        return None
+    tag = model.tags.get(ref.tag)
+    target = tag.resources.get(ref.resource) if tag is not None else None
+    if target is None or target.list_op is None:
+        return None
+    return FkTarget(
+        kind="picker",
+        field_name=field_name,
+        tag=ref.tag,
+        resource_name=ref.resource,
+        list_op=target.list_op,
+    )
+
+
+def _field_fk_target(resource: Resource, base: str) -> str | None:
+    for op in (resource.create_op, resource.update_op, resource.replace_op):
+        if op is None or op.request_body is None:
+            continue
+        shape = op.request_body.fields.get(base)
+        if shape is not None and shape.fk_target is not None:
+            return shape.fk_target
+    return None
+
+
+def _find_resource(model: CommandModel, name: str, *, prefer_tag: str | None) -> Resource | None:
+    if prefer_tag is not None and prefer_tag in model.tags:
+        found = model.tags[prefer_tag].resources.get(name)
+        if found is not None:
+            return found
+    for tag_name in sorted(model.tags):
+        found = model.tags[tag_name].resources.get(name)
+        if found is not None:
+            return found
+    return None
+
+
 def _resolve_from_url(field_name: str, current_value: Any, model: CommandModel) -> FkTarget | None:
     if not isinstance(current_value, dict):
         return None
@@ -110,27 +186,61 @@ def _resolve_from_url(field_name: str, current_value: Any, model: CommandModel)
     )
 
 
-def _resolve_by_field_name(field_name: str, model: CommandModel) -> FkTarget | None:
+def _resolve_by_field_name(
+    field_name: str,
+    model: CommandModel,
+    *,
+    context_tag: str | None = None,
+    context_resource: str | None = None,
+) -> FkTarget | None:
     base = field_name[:-3] if field_name.endswith("_id") else field_name
     wanted = singularize(base)
-    for tag_name in sorted(model.tags):
-        tag = model.tags[tag_name]
-        for resource_name in sorted(tag.resources):
-            if singularize(resource_name) != wanted:
-                continue
-            resource = tag.resources[resource_name]
-            if resource.list_op is None:
-                continue
+
+    # NetBox reuses bare FK names across apps: a device's `role` targets dcim
+    # `device-roles`, an ipam prefix's `role` targets ipam `roles`. The bare name
+    # can't disambiguate (`device-roles` does not singularize to `role`), so when
+    # the owning resource is known we first try the qualified target name
+    # `<owner>-<field>` (e.g. `device-role`), preferring the owner's own tag,
+    # before falling back to the bare name's global scan.
+    candidates: list[str] = []
+    if context_resource is not None:
+        candidates.append(f"{singularize(context_resource)}-{wanted}")
+    candidates.append(wanted)
+
+    for candidate in candidates:
+        located = _match_resource_by_singular(model, candidate, prefer_tag=context_tag)
+        if located is not None:
+            tag_name, resource_name, list_op = located
             return FkTarget(
                 kind="picker",
                 field_name=field_name,
                 tag=tag_name,
                 resource_name=resource_name,
-                list_op=resource.list_op,
+                list_op=list_op,
             )
     return None
 
 
+def _match_resource_by_singular(
+    model: CommandModel, wanted: str, *, prefer_tag: str | None
+) -> tuple[str, str, Operation] | None:
+    for tag_name in _tag_search_order(model, prefer_tag):
+        tag = model.tags[tag_name]
+        for resource_name in sorted(tag.resources):
+            resource = tag.resources[resource_name]
+            if singularize(resource_name) != wanted or resource.list_op is None:
+                continue
+            return (tag_name, resource_name, resource.list_op)
+    return None
+
+
+def _tag_search_order(model: CommandModel, prefer_tag: str | None) -> list[str]:
+    rest = sorted(model.tags)
+    if prefer_tag is not None and prefer_tag in model.tags:
+        return [prefer_tag, *(t for t in rest if t != prefer_tag)]
+    return rest
+
+
 def _locate_resource(
     resource_name: str, model: CommandModel
 ) -> tuple[str, Operation | None] | None:

{netbox_super_cli-1.6.1 → netbox_super_cli-1.6.2}/nsc/tui/screens/bulk_edit_form.py

@@ -183,7 +183,13 @@ class BulkEditForm(Screen[None]):
         return str(shared_id)
 
     def _compose_fk(self, name: str) -> ComposeResult:
-        target = resolve_fk_target(name, self._fk_nested_value(name), self._model)
+        target = resolve_fk_target(
+            name,
+            self._fk_nested_value(name),
+            self._model,
+            context_tag=self._tag,
+            context_resource=self._resource_name,
+        )
         self._fk_kinds[name] = target.kind
         shared_id = self._shared.get(name)
         if target.kind == "raw_id":
@@ -331,7 +337,13 @@ class BulkEditForm(Screen[None]):
             self._open_picker(fk)
 
     def _open_picker(self, name: str) -> None:
-        target = resolve_fk_target(name, self._fk_nested_value(name), self._model)
+        target = resolve_fk_target(
+            name,
+            self._fk_nested_value(name),
+            self._model,
+            context_tag=self._tag,
+            context_resource=self._resource_name,
+        )
         if target.list_op is None:
             return
         from nsc.tui.screens.record_picker import RecordPicker  # noqa: PLC0415

{netbox_super_cli-1.6.1 → netbox_super_cli-1.6.2}/nsc/tui/screens/detail.py

@@ -214,7 +214,13 @@ class DetailScreen(Screen[None]):
         editor.focus()
 
     def _edit_fk(self, name: str) -> None:
-        target = resolve_fk_target(name, self._record.get(name), self._model)
+        target = resolve_fk_target(
+            name,
+            self._record.get(name),
+            self._model,
+            context_tag=self._tag,
+            context_resource=self._resource_name,
+        )
         if target.kind == "raw_id" or target.list_op is None:
             spec = self._specs[name]
             self._open_input(name, spec)

{netbox_super_cli-1.6.1 → netbox_super_cli-1.6.2}/nsc/tui/screens/edit_form.py

@@ -174,7 +174,13 @@ class EditForm(Screen[None]):
         return name.endswith("_id") or is_fk_value(self._record.get(name))
 
     def _compose_fk(self, name: str, value: Any) -> ComposeResult:
-        target = resolve_fk_target(name, self._record.get(name), self._model)
+        target = resolve_fk_target(
+            name,
+            self._record.get(name),
+            self._model,
+            context_tag=self._tag,
+            context_resource=self._resource_name,
+        )
         if target.kind == "raw_id":
             text = "" if value is None else str(value)
             yield Input(value=text, id=f"field-{name}")
@@ -266,7 +272,13 @@ class EditForm(Screen[None]):
             self.staged[name] = list(selected)
 
     def _open_picker(self, name: str) -> None:
-        target = resolve_fk_target(name, self._record.get(name), self._model)
+        target = resolve_fk_target(
+            name,
+            self._record.get(name),
+            self._model,
+            context_tag=self._tag,
+            context_resource=self._resource_name,
+        )
         if target.list_op is None:
             return
         from nsc.tui.screens.record_picker import RecordPicker  # noqa: PLC0415

{netbox_super_cli-1.6.1 → netbox_super_cli-1.6.2}/nsc/tui/screens/filter.py

@@ -67,7 +67,12 @@ class FilterScreen(ModalScreen[dict[str, str]]):
         self._syncing = False
 
     def _is_fk(self, name: str) -> bool:
-        return resolve_fk_target(name, None, self._model).kind == "picker"
+        return (
+            resolve_fk_target(
+                name, None, self._model, context_tag=self._tag, context_resource=self._resource
+            ).kind
+            == "picker"
+        )
 
     @staticmethod
     def _apply_key(name: str) -> str:
@@ -187,7 +192,9 @@ class FilterScreen(ModalScreen[dict[str, str]]):
         raw.focus()
 
     def _open_fk_picker(self, name: str) -> None:
-        target = resolve_fk_target(name, None, self._model)
+        target = resolve_fk_target(
+            name, None, self._model, context_tag=self._tag, context_resource=self._resource
+        )
         if target.list_op is None:
             return
         from nsc.tui.screens.record_picker import RecordPicker  # noqa: PLC0415

{netbox_super_cli-1.6.1 → netbox_super_cli-1.6.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "netbox-super-cli"
-version = "1.6.1"
+version = "1.6.2"
 description = "Dynamic NetBox CLI generated from the live OpenAPI schema."
 readme = "README.md"
 requires-python = ">=3.12"

netbox_super_cli-1.6.2/tests/builder/test_fk_metadata.py

@@ -0,0 +1,148 @@
+"""Schema-driven foreign-key target metadata.
+
+NetBox types a writable FK as ``oneOf[integer, Brief<X>Request]``. The builder
+records the target serializer name (``<X>``) on the field and indexes which
+resource serves objects of each serializer, so the TUI can resolve an FK picker
+to the true target even when the field name does not match the resource name
+(e.g. a virtual-machine's ``role`` targets dcim ``device-roles``).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from nsc.builder.build import build_command_model
+from nsc.model.command_model import MODEL_FORMAT_VERSION, FkResourceRef
+from nsc.schema.loader import LoadedSchema, load_schema
+from nsc.schema.models import OpenAPIDocument
+
+_BUNDLED = Path("nsc/schemas/bundled/netbox-4.6.0.json.gz")
+
+
+@pytest.fixture(scope="module")
+def bundled_model():
+    return build_command_model(load_schema(str(_BUNDLED)))
+
+
+def test_fk_resources_index_maps_serializer_to_resource(bundled_model) -> None:
+    index = bundled_model.fk_resources
+    assert index["DeviceRole"] == FkResourceRef(tag="dcim", resource="device-roles")
+    assert index["ContactRole"] == FkResourceRef(tag="tenancy", resource="contact-roles")
+    assert index["InventoryItemRole"] == FkResourceRef(tag="dcim", resource="inventory-item-roles")
+    assert index["Role"] == FkResourceRef(tag="ipam", resource="roles")
+
+
+def test_field_fk_target_records_serializer_name(bundled_model) -> None:
+    devices = bundled_model.tags["dcim"].resources["devices"]
+    assert devices.create_op is not None
+    assert devices.create_op.request_body is not None
+    assert devices.create_op.request_body.fields["role"].fk_target == "DeviceRole"
+
+    vms = bundled_model.tags["virtualization"].resources["virtual-machines"]
+    assert vms.create_op is not None
+    assert vms.create_op.request_body is not None
+    # A VM's role is a device-role, despite the field/resource name mismatch.
+    assert vms.create_op.request_body.fields["role"].fk_target == "DeviceRole"
+
+
+def test_every_fk_target_resolves_in_index(bundled_model) -> None:
+    # Invariant: a field's declared FK target must exist in the index, or the TUI
+    # picker silently degrades to raw-ID entry. Catches list serializers whose
+    # name (e.g. DeviceWithConfigContext) doesn't normalize to the brief base.
+    index = bundled_model.fk_resources
+    missing: set[str] = set()
+    for _tag, _resource, op in bundled_model.iter_operations():
+        if op.request_body is None:
+            continue
+        for shape in op.request_body.fields.values():
+            if shape.fk_target is not None and shape.fk_target not in index:
+                missing.add(shape.fk_target)
+    assert not missing, f"FK targets with no resource in the index: {sorted(missing)}"
+
+
+def test_with_config_context_targets_resolve(bundled_model) -> None:
+    # Device/VirtualMachine list serializers carry a WithConfigContext suffix;
+    # the index must still key them under the brief base name.
+    index = bundled_model.fk_resources
+    assert index["Device"] == FkResourceRef(tag="dcim", resource="devices")
+    assert index["VirtualMachine"] == FkResourceRef(
+        tag="virtualization", resource="virtual-machines"
+    )
+
+
+def test_non_fk_field_has_no_fk_target(bundled_model) -> None:
+    devices = bundled_model.tags["dcim"].resources["devices"]
+    assert devices.create_op is not None
+    assert devices.create_op.request_body is not None
+    assert devices.create_op.request_body.fields["name"].fk_target is None
+
+
+def test_builder_stamps_current_format_version(bundled_model) -> None:
+    assert bundled_model.format_version == MODEL_FORMAT_VERSION
+
+
+def _loaded(doc: OpenAPIDocument) -> LoadedSchema:
+    return LoadedSchema(source="test", body=b"", hash="sha256:test", document=doc)
+
+
+def _doc(body_role: dict[str, Any]) -> OpenAPIDocument:
+    return OpenAPIDocument.model_validate(
+        {
+            "openapi": "3.0.0",
+            "info": {"title": "T", "version": "0"},
+            "paths": {
+                "/api/t/widgets/": {
+                    "post": {
+                        "operationId": "create",
+                        "tags": ["t"],
+                        "requestBody": {
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "properties": {"role": body_role},
+                                    }
+                                }
+                            }
+                        },
+                        "responses": {"200": {"description": "ok"}},
+                    }
+                }
+            },
+            "tags": [{"name": "t"}],
+        }
+    )
+
+
+def test_fk_target_extracted_from_plain_oneof() -> None:
+    doc = _doc({"oneOf": [{"type": "integer"}, {"$ref": "#/components/schemas/BriefThingRequest"}]})
+    model = build_command_model(_loaded(doc))
+    field = model.tags["t"].resources["widgets"].create_op.request_body.fields["role"]
+    assert field.fk_target == "Thing"
+
+
+def test_fk_target_extracted_from_nullable_allof_wrapper() -> None:
+    # NetBox wraps a nullable FK as oneOf[integer, {allOf:[$ref], nullable}].
+    doc = _doc(
+        {
+            "oneOf": [
+                {"type": "integer"},
+                {"allOf": [{"$ref": "#/components/schemas/BriefThingRequest"}], "nullable": True},
+            ],
+            "nullable": True,
+        }
+    )
+    model = build_command_model(_loaded(doc))
+    field = model.tags["t"].resources["widgets"].create_op.request_body.fields["role"]
+    assert field.fk_target == "Thing"
+
+
+def test_string_enum_role_is_not_an_fk() -> None:
+    # Some `role` fields (e.g. ip-addresses) are plain string enums, not FKs.
+    doc = _doc({"type": "string", "enum": ["loopback", "secondary"]})
+    model = build_command_model(_loaded(doc))
+    field = model.tags["t"].resources["widgets"].create_op.request_body.fields["role"]
+    assert field.fk_target is None