reference

Most relational fields in Odoo know their target model in advance: a salesperson is always a user, a customer is always a partner. Some do not. An activity can be attached to an order or a lead, a mailing can target anything, a log line can point at whatever raised it. Odoo's answer is the reference field, which stores a model name and a record id together in one column, and reference is the widget that edits it.

On screen it is two controls in a row: a plain dropdown listing the models the field allows, and next to it a normal record autocomplete. Choose the model, then choose the record. Once a value is set, the autocomplete behaves exactly like a many2one, with the same open, create and search behavior.

The widget also handles a second, less obvious case. If you put it on a char field whose value looks like res.partner,42, it reads that string, fetches the display name of the target record and renders the same two controls. That is how a text column can be made to behave like a relation without a schema change.

Reference fields exist for the parts of a business process that legitimately touch several object types. A complaint that might be about an invoice, a delivery or a subscription. An internal task whose source could be a lead or a helpdesk ticket. Forcing that into three separate many2one columns produces forms full of empty fields and reports nobody trusts.

The cost is that a reference is harder to report on than a many2one, because the target model varies row by row. The usual compromise in real projects is to keep the reference for capture and add a computed helper field for the one model you actually report on. Decide that early; retrofitting it after a year of data is the expensive version.

The model_field option is the underrated part. When a configuration record already holds the model in a many2one to ir.model, pointing the widget at it removes the second dropdown entirely and leaves users with one intuitive question instead of two. Automation rules and mailing configuration screens use exactly this shape.

Plain two-step picker

<field name="resource_ref" widget="reference"/>

Model dropdown plus record autocomplete. This is also what a reference field renders without any widget attribute, since the widget is the type's default.

Model driven by another field

<field name="model_id"/>
<field name="resource_ref" widget="reference"
       options="{'model_field': 'model_id'}"/>

One dropdown disappears. Change model_id and the reference is cleared automatically, so no orphan value survives.

Locked model, no creation from the dropdown

<field name="resource_ref" widget="reference"
       options="{'hide_model': True, 'no_create': True, 'no_open': True}"/>

no_create and no_open are inherited from the many2one widget and are not declared here, but they are honored.

A char field behaving as a relation

<field name="target" widget="reference"/>
<!-- target is Char and stores e.g. "res.partner,42" -->

Supported on purpose: supportedTypes lists char alongside reference. The display name is fetched with a separate read.

The interesting part of this file is the gap between what the widget declares and what it actually accepts. Its supportedOptions array has exactly two entries, hide_model and model_field. Its extractProps, however, starts by calling the shared many2one extractor and only then adds its own two props.

That extractor reads seven more keys: no_create, no_create_edit, no_open, no_quick_create, search_threshold, create_name_field and can_scan_barcode. All seven therefore work on a reference field. The last two are undeclared even on the many2one widget itself, which makes them doubly invisible. It also honors the can_create and can_write attributes on the field element.

The second thing worth knowing is how the value is kept in sync. When model_field is used, a record observer watches that many2one. On every change it reads the technical model name from ir.model and, if a model was already selected before, writes false into the reference field. That is deliberate: keeping a sale.order id after switching the model to crm.lead would produce a value that resolves to the wrong record.

In char mode a similar observer fetches the display name, and the result is stored in the model's specialDataCaches keyed by the raw value. The cache is per client session, so a target record renamed elsewhere keeps showing its old name until the page is reloaded.

Odoo 20 is expected at Odoo Experience in Brussels, 24 to 26 September 2026. The development branch is unstable, so treat this as a direction of travel and not a promise; we re-verify this page once Odoo 20 ships.

Options are unchanged. hide_model, model_field, the supported types and the inherited many2one behavior are all identical to Odoo 19.

One real fix. The development branch adds a third record observer for the standard case: when the stored value carries a model, the widget now syncs its internal current-relation state with it. On Odoo 19 that state is only set when the user picks a model, which is what makes a freshly loaded record occasionally render its selector as unset. The rest of the diff is the Owl props migration, which affects patches rather than views.