Defer relationship DTO resolution until schema finalization

[adiberk]

Problem

When a relationship field is generated for a related SQLAlchemy model that also has an explicit GraphQL DTO name, Strawchemy can bind the relationship to the synthesized default DTO type instead of the explicitly registered DTO.

That means custom fields declared on the explicit DTO are not present on the relationship field type.

This is not module discovery: if the related DTO module is never imported/decorated, Strawchemy cannot know about it. The issue is the case where the explicit DTO exists, but relationship generation has already selected or synthesized the default related DTO name.

Minimal example

from sqlalchemy import ForeignKey, Integer, String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
from strawberry import Schema
from strawchemy import Strawchemy, StrawchemyConfig

class Base(DeclarativeBase):
    pass

class Account(Base):
    __tablename__ = "accounts"
    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    name: Mapped[str] = mapped_column(String)

class Template(Base):
    __tablename__ = "templates"
    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    account_id: Mapped[int] = mapped_column(ForeignKey("accounts.id"))
    account: Mapped[Account] = relationship()

sc = Strawchemy(StrawchemyConfig(dialect="postgresql"))

@sc.type(Template, name="TemplateNode", include=["id", "account"])
class TemplateNode:
    pass

@sc.type(Account, name="AccountNode", include=["id", "name"])
class AccountNode:
    @strawberry.field
    def custom_label(self) -> str:
        return "custom"

@strawberry.type
class Query:
    template: TemplateNode | None = None

schema = Schema(query=Query)
print(schema.as_str())

Expected relationship field:

account: AccountNode!

Observed with default DTO naming:

account: AccountType!

The AccountNode.customLabel field is therefore not available on TemplateNode.account.

Why deferred/schema-time resolution would help

If relationship fields stored a deferred reference keyed by the related model and DTO purpose/scope instead of immediately binding to the currently synthesized class/name, schema construction/finalization could resolve that reference to the explicit registered DTO when one exists.

That would avoid import-order workarounds such as registering otherwise-unused related-node imports purely so relationship fields bind to the desired type.

Possible direction

• Keep a registry keyed by (model, purpose/mode, scope) that records explicit DTO registrations.
• Let relationship field generation emit a model-keyed deferred reference rather than an eagerly chosen default DTO class/name.
• At schema build or finalization time, resolve pending relationship references to the explicit registered DTO if present; otherwise fall back to generated defaults.
• If this is expected to be handled by the future scope behavior mentioned in Walker auto-registers stub types that collide with subsequent @sc.type declarations (partial-port footgun) #159, document whether scope will also cover relationship-target resolution for explicitly named DTOs.

Workaround

In our app we can work around this by customizing DTO naming so synthesized relationship DTO names match our explicit *Node convention, but that is project-specific and feels like it should not be required for relationship fields to point at explicit registered DTOs.

[adiberk]

Small clarification after talking through the lifecycle in a real app:

In our full schema path, this is not primarily a package-discovery problem. schema.py imports the query/mutation surface, and those imports pull in the node modules that are part of the API. By the time strawberry.Schema(...) is constructed, the intended DTO classes have generally been imported and registered.

The problem is that relationship field types appear to be chosen earlier, during @sc.type(...) decoration/module import. If TemplateNode is decorated before AccountNode has registered, the Template.account relationship can bind to a synthesized/default DTO. Later, when AccountNode is imported before schema construction, the relationship field does not reliably re-resolve to the explicit DTO.

So the concrete ask is not automatic module scanning. It is deferred/final relationship-target resolution after the schema import graph has loaded, or a registry update path that reliably rewrites pending relationship refs when the explicit related DTO registration arrives.

[adiberk]

One more framing note: I don't think this is just an application-specific *Node naming issue.

It exposes a more fundamental invariant problem: relationship DTO selection should not depend on Python module import order during decoration. If the final schema imports/registers an explicit DTO for a related model before strawberry.Schema(...) is built, relationship fields for that model should resolve to that final registered DTO deterministically.

Otherwise two schemas with the same final registered DTO set can produce different relationship field types solely because modules were imported in a different order. That makes relationship generation fragile for any project with explicit DTO classes, custom fields, overrides/scopes, or multiple DTO surfaces for the same model.

[adiberk]

I put together a concrete candidate fix in the Lev fork, based on upstream main plus PR #169:

• Branch: https://github.com/levco/strawchemy/tree/lev/main-pr169-relationship-finalization
• Commit: levco@ae28b31

The change makes explicit user-defined override=True DTO registrations resolve pending refs to generated/default DTOs for the same model, while preserving the existing scope="schema" behavior. It also adds a regression test where FruitNode.color initially binds through the generated related DTO, then resolves to the later explicit ColorNode registration before schema construction.

Validation on the fork:

• uv run pytest tests/unit -q --snapshot-warn-unused -> 209 passed, 2 skipped
• uv run ruff check src/strawchemy/utils/registry.py tests/unit/mapping/test_schemas.py
• uv run ruff format --check src/strawchemy/utils/registry.py tests/unit/mapping/test_schemas.py

[adiberk]

Opened PR #176 with the relationship DTO reference fix: #176

[gazorby]

That's weird. The scope feature has been designed specifically for this use-case, wouldn't adding scope="schema" to the AccountNode decoration solves that issue?

It should instruct the mapper to always use AccountNode whenever it encounters an Account relationship in models.