← Roadmap

Concept explainer · R97 · theme: classification-model

Consumer-derived input tables

An input type never has to declare which database table it maps to. The consuming field's return type already answers that, so @table on an input is a copy of a fact graphitron can read for free. This page is the intuition for why the directive is redundant, and the deeper reason the input has nothing to classify at all.

The problem, concretely

Take a Sakila filter query. The field returns Film, and Film is bound to the film table:

type Query {
    films(filter: FilmConditionInput!): [Film!]!
}

type Film @table(name: "film") { ... }

input FilmConditionInput @table(name: "film") {
    title: String
    releaseYear: Int
}

The input carries @table(name: "film") so graphitron knows title resolves to film.title and releaseYear to film.release_year. But look at where that name comes from: the field films returns [Film!]!, and Film is @table(name: "film"). The input's directive and the return type's directive say the identical word, film. One of them is redundant, and it is the one on the input.

input FilmConditionInput
    @table(name: "film")   // says "film"

input FilmConditionInput {  // no @table
    title: String
}
// films(): [Film] already says "film"

This holds for every fixture pattern in Sakila: INSERT/UPDATE/DELETE mutations whose field returns a @table type, filter and condition inputs, lookup-key inputs like FilmActorKey. In each the input's @table names a table the consuming field already fixes. R97 removes the directive and reads the table off the consumer instead.

The deeper reason: the input is not an entity

The redundancy argument is the easy half. The load-bearing half comes from the fact-based model (R333): a schema coordinate lowers to a graph of output-field facts, a condition, a write target, a projection. The input does not appear in that graph as a node. It only supplies the data those facts consume.

So the question "what table is this input bound to?" is asking the wrong thing to answer it. The input does not answer that; the consuming field's fact does. The condition fact binds the input's values to columns. The mutation's write-target fact derives the table. "Bound table" is a property of the fact, read through the input, not a property stored on the input.

The boundary: when the input does become an entity

"The input is only data" is true for exactly the era this item covers. There is one use case where modelling the input as a first-class entity is warranted, and it is already filed: Jakarta validation (R92, R98).

The distinction is clean. A constraint, a DB CHECK lifted to @Pattern/@Min, an SDL-declared rule, a Jakarta annotation, is a fact about the input itself: it is true no matter which field consumes the input. That cannot be reduced to an output-field fact, so the input earns its own node in the model. Until then, the input is data for output facts, and consumer-derived resolution is the whole story.

Reuse across consumers: the case that exposes the difference

What happens when one input is used by two fields? Say FilmConditionInput filters both Query.films and Query.filmsByGenre, both returning [Film]. Both consumer-derived resolutions land on film, so nothing differs. The interesting case is when they disagree.

When convention cannot tie-break: argMapping grouping

Consumer-derivation is convention: the return-type table plus by-name column matching. Convention runs out when an input fans out, its fields scatter across multiple service-method parameters, or multiple jOOQ records. Rather than a new directive, R97 extends the existing argMapping escape valve with a grouping form.

@service(service: {
  method: "filmsByPath",
  argMapping: "filmIds: input.ids"
})

argMapping: """
  order: { orderNumber: input.orderNumber,
           customerId: input.customerId },
  shipTo: { street: input.street,
            city: input.city }
"""

This subsumes the @param directive proposed in JIRA GG-376: the group's left-hand side is GG-376's name, the target type is derived from the service method's parameter type (not declared), and the group entries are GG-376's fields. No new directive; the fan-out is expressed on the directive that already carries mappings.

What still leans on @table, and how each unwinds

The directive is not gone yet; several consumers still read it, and R97 is phased so each is made consumer-derived before the declaration is removed. The mutation write-target verbs have been landing one at a time.

• Arg-level @lookupKey (composite lookup like FilmActorKey) runs only on the TableInputType arm today. R97 re-derives it: resolve the plain input's fields against the consumer's table and build the same lookup carrier.
• UPDATE write target is the last mutation verb hard-requiring @table on its input; DELETE (R457) and INSERT (R515) already went field-relative. UPDATE inherits the same precedence ladder: return-derived table, then @mutation(table:), then the @table bridge.
• The global machinery, findReturnTablesForInput and the isUsedWithOverrideCondition routing gate, retires once nothing needs the auto-promotion.
• The LSP/catalog seams lose their data source when every input goes plain; the final phase decides affirmatively whether per-consumer resolution feeds the input-type hover, or the input-field coordinates are dropped and R337 owns re-surfacing them.

The @table-on-input deprecation is already announced (R332 shipped the warning). Depth on how arguments resolve against a table lives in the argument-resolution reference; the classifier's mental model is in the classifier mental model; the discipline of turning an unbuildable shape into a named rejection is typed rejection.

Where it stands (as of 2026-07-24)

• landedSubstrate this item builds on: query-side plain-input resolution is field-relative (R205, R215, R330); the mutation write-target verbs went field-relative one at a time, DELETE (R457), the grounding substrate (R514), INSERT (R515); the sibling directive retirements shipped, @record reflection-driven binding (R96), the input-records carrier (R94), and the @table-on-input deprecation warning (R332).
• in progressR97: the residual. Route arg-level @lookupKey through the consumer-derived table; retire findReturnTablesForInput and the isUsedWithOverrideCondition gate; migrate UPDATE's write target off the input's @table (Phase 2b, carved out like the other verbs when picked up); narrow the @table directive scope to OBJECT | INTERFACE and decide the LSP projection story affirmatively. The argMapping grouping (Phase 1) is orthogonal and splits into its own item when scheduled.
• boundaryR92 (Spec) and R98 (Backlog): where the deferral ends and the input earns a first-class entity again, on the strength of constraints that are facts about the input itself. R97 covers the input-as-data era up to this point.
• follow-onR337 (Backlog): the nested-grouping projection surfacing residual, revived narrowly if R97 lands but leaves the input-field LSP coordinates on the PojoInput(null) label.