unclecatvn/agent-skills / skills/odoo-18.0
odoo-18
VerifiedOdoo 18 development reference for Python models and ORM (search, domain, read_group, compute fields), XML/CSV data and views, OWL/JS client code, QWeb reports, security (ACL, record rules, groups), cron and server actions, migrations and module upgrades, tests, i18n, and performance. Use this skill whenever work involves Odoo 18 or custom addons—even if the user only pastes a traceback, mentions addons/ or __manifest__.py, describes form/list/kanban/XML errors, HTTP controllers, or business rules on models—including building features, fixing bugs, refactoring, or reviewing addon code. Includes CSS/SCSS asset authoring and review for Odoo addons.
references/odoo-18-field-guide.md
View on GitHub---
name: odoo-18-field
description: Complete reference for Odoo 18 field types, parameters, and when to use each. Use this guide when defining model fields, choosing field types, or configuring field parameters.
globs: "**/models/**/*.py"
topics:
- Simple fields (Char, Text, Html, Boolean, Integer, Float, Monetary, Date, Datetime, Binary, Selection, Reference)
- Relational fields (Many2one, One2many, Many2many)
- Computed fields (compute, store, search, inverse)
- Related fields
- Field parameters (index, default, copy, store, groups, company_dependent, tracking)
when_to_use:
- Defining new model fields
- Choosing appropriate field types
- Configuring computed fields
- Setting up relational fields
- Optimizing field parameters
---
# Odoo 18 Field Guide
## Coding Conventions
Keep fields and their default, compute, inverse, and search helpers together.
Complete reference for Odoo 18 field types, parameters, and when to use each.
## Table of Contents
1. [Simple Fields](#simple-fields)
2. [Relational Fields](#relational-fields)
3. [Computed Fields](#computed-fields)
4. [Related Fields](#related-fields)
5. [Field Parameters](#field-parameters)
---
## Simple Fields
### Char - String Field
```python
name = fields.Char(
string='Name',
required=True,
size=100, # Optional: max length (not enforced by ORM)
translate=True, # Enable translation
default='', # Default value
)
# Short text (names, codes, etc.)
code = fields.Char(string='Code', index=True)
reference = fields.Char(string='Reference', copy=False) # Not copied on duplicate
```
**Use for**: Short text values (names, codes, references). Use `size` hint for UI only.
---
### Text - Long Text Field
```python
description = fields.Text(
string='Description',
translate=True,
)
# Notes, descriptions, long content
notes = fields.Text(string='Notes')
```
**Use for**: Long-form text content. Not searchable by default in database.
---
### Html - Rich Text Field
```python
content = fields.Html(
string='Content',
translate=True,
sanitize=True, # Sanitize HTML to prevent XSS
)
# Email body, website content
email_body = fields.Html(string='Email Body')
```
**Use for**: HTML content (email templates, website pages). Automatically sanitized.
---
### Boolean - True/False Field
```python
active = fields.Boolean(
string='Active',
default=True,
)
is_company = fields.Boolean(string='Is Company')
```
**Use for**: Yes/No values. Default is `False` if not specified.
---
### Integer - Whole Number Field
```python
quantity = fields.Integer(
string='Quantity',
default=1,
)
# Integer with range constraint
priority = fields.Integer(
string='Priority',
default=0,
)
```
**Use for**: Whole numbers. Large numbers should use `Float` or `Monetary` instead.
---
### Float - Decimal Number Field
```python
price = fields.Float(
string='Price',
digits='Product Price', # Named precision from decimal.precision
)
# Direct digits specification
weight = fields.Float(
string='Weight',
digits=(16, 3), # (total digits, decimal places)
)
```
**Use for**: Non-monetary decimal values. For currency, use `Monetary` field instead.
### Float Helper Methods (Odoo 18)
```python
# Float precision helpers
from odoo import fields
# Round to precision
rounded = fields.Float.round(
value,
precision_rounding=self.product_uom_id.rounding
)
# Check if value is zero at precision
is_zero = fields.Float.is_zero(
value,
precision_rounding=self.product_uom_id.rounding
)
# Compare two values at precision
result = fields.Float.compare(
value1,
value2,
precision_rounding=self.product_uom_id.rounding
)
# Returns: negative (v1 < v2), 0 (equal), positive (v1 > v2)
```
**Common Use Cases**:
```python
# Round quantity before display
display_qty = fields.Float.round(
self.quantity,
precision_rounding=self.uom_id.rounding
)
# Check if quantity is effectively zero
if fields.Float.is_zero(self.quantity, precision_rounding=0.001):
raise UserError("Quantity cannot be zero")
# Compare prices at precision
if fields.Float.compare(self.price, self.list_price, precision_rounding=0.01) >= 0:
# Price is greater than or equal to list price
pass
```
**Important**: Always use precision_rounding from the unit of measure (product.uom_id.rounding) or currency (res.currency.rounding) when working with Float fields to avoid floating-point comparison issues.
---
### Monetary - Currency Field
```python
amount = fields.Monetary(
string='Amount',
currency_field='currency_id', # many2one to res.currency
)
amount_total = fields.Monetary(
string='Total',
currency_field='company_id.currency_id',
)
```
**Use for**: All monetary values. Automatically handles currency formatting and precision.
**Important**: Always specify `currency_field` pointing to a `res.currency` many2one.
---
### Date - Date Field
```python
date = fields.Date(
string='Date',
default=fields.Date.context_today,
copy=False,
)
# Date computed field
date_deadline = fields.Date(
string='Deadline',
compute='_compute_date_deadline',
store=True,
)
```
**Use for**: Dates without time. Stored as date in database (no timezone issues).
---
### Datetime - Timestamp Field
```python
datetime = fields.Datetime(
string='DateTime',
default=fields.Datetime.now,
copy=False,
)
# Common pattern for tracking
create_date = fields.Datetime(string='Created on', readonly=True)
write_date = fields.Datetime(string='Last Updated on', readonly=True)
```
**Use for**: Dates with time. Stored as UTC, displayed in user timezone.
### Date/Datetime Helper Methods (Odoo 18)
```python
# Date helper methods
from odoo import fields
# Get start/end of period
start_of_month = fields.Date.start_of(fields.Date.today(), 'month')
end_of_quarter = fields.Date.end_of(fields.Date.today(), 'quarter')
# Add/subtract time periods
next_month = fields.Date.add(fields.Date.today(), months=1)
last_week = fields.Date.subtract(fields.Date.today(), weeks=2)
# Supported granularities: 'year', 'quarter', 'month', 'week', 'day', 'hour'
# Convert to/from string
date_obj = fields.Date.to_date('2024-01-15') # String to date
date_str = fields.Date.to_string(fields.Date.today()) # Date to string
# Context-aware today
today_tz = fields.Date.context_today(record) # Today in record's timezone
# Datetime helper methods
now_utc = fields.Datetime.now() # Current UTC datetime
today_midnight = fields.Datetime.today() # Today at midnight (00:00:00)
# Add/subtract datetime
next_hour = fields.Datetime.add(fields.Datetime.now(), hours=1)
yesterday = fields.Datetime.subtract(fields.Datetime.now(), days=1)
# Convert to/from string
datetime_obj = fields.Datetime.to_datetime('2024-01-15 14:30:00')
datetime_str = fields.Datetime.to_string(fields.Datetime.now())
# Context-aware timestamp
timestamp_tz = fields.Datetime.context_timestamp(record, datetime_obj)
```
**Common Use Cases**:
```python
# Get start of current month for reports
start_date = fields.Date.start_of(fields.Date.today(), 'month')
end_date = fields.Date.end_of(fields.Date.today(), 'month')
# Add 30 days to current date
due_date = fields.Date.add(fields.Date.today(), days=30)
# Get end of current quarter
quarter_end = fields.Date.end_of(fields.Date.today(), 'quarter')
```
---
### Binary - File/Attachment Field
```python
file = fields.Binary(
string='File',
attachment=True, # Show in attachments chatter
)
image = fields.Binary(string='Image')
image_1920 = fields.Binary(string='Image 1920', max_width=1920, max_height=1920)
```
**Use for**: File attachments and images. Use `attachment=True` for chatter integration.
**Note**: With `bin_size` context, returns size in bytes instead of content.
---
### Image - Image Field with Resize (Odoo 18)
```python
# Image field with automatic resize
image = fields.Image(
string='Image',
max_width=1920, # Resize if wider than 1920px
max_height=1080, # Resize if taller than 1080px
verify_resolution=True, # Check max resolution (50MP default)
)
# Product image
image_1920 = fields.Image(
string='Product Image',
max_width=1920,
max_height=1920,
)
# Without size limit
image_large = fields.Image(
string='Large Image',
max_width=0, # No limit
max_height=0, # No limit
verify_resolution=False,
)
```
**Important**:
- `Image` extends `Binary` field
- Automatically resizes images if they exceed `max_width`/`max_height` while maintaining aspect ratio
- `verify_resolution=True` checks against maximum image resolution (~50MP default)
- If `max_width` or `max_height` is 0 and `verify_resolution` is False, no verification is performed
---
### Many2oneReference - Dynamic Typed Reference (Odoo 18)
```python
# Many2oneReference - model stored in separate field
ref_id = fields.Many2oneReference(
string='Reference',
model_field='model_name', # Char field containing model name
)
# Example usage
class MyModel(models.Model):
_name = 'my.model'
model_name = fields.Char(string='Model Name') # Stores model name
ref_id = fields.Many2oneReference(
string='Reference',
model_field='model_name'
)
# Usage: ref_id can point to any model, model_name stores which model
# Stored as integer ID in database (more efficient than Reference string)
```
**Important**:
- `Many2oneReference` stores value as integer ID (unlike `Reference` which stores "model,id" string)
- Requires a separate Char field to store the model name
- More efficient than `Reference` for database queries and joins
- Use when you need dynamic references to multiple possible models
---
### Selection - Dropdown Field
```python
# Simple selection
state = fields.Selection([
('draft', 'Draft'),
('confirmed', 'Confirmed'),
('done', 'Done'),
], string='State', default='draft')
# Selection from model method
state = fields.Selection(
'_get_selection_states',
string='State'
)
@api.model
def _get_selection_states(self):
return [
('draft', 'Draft'),
('confirmed', 'Confirmed'),
]
```
**Use for**: Fixed set of options. Values are stored in database, must not change keys.
---
### Reference - Dynamic Reference
```python
ref_id = fields.Reference(
string='Reference',
selection='_models_get',
)
@api.model
def _models_get(self):
models = self.env['ir.model'].search([])
return [(model.model, model.name) for model in models]
```
**Use for**: References to multiple possible models. Stored as `model,id` string.
---
## Relational Fields
### Many2one - Many-to-One
```python
partner_id = fields.Many2one(
'res.partner',
string='Partner',
required=True,
ondelete='cascade', # 'set null', 'restrict', 'cascade'
domain=[('customer_rank', '>', 0)],
context={'default_customer_rank': 1},
default=lambda self: self.env.user.partner_id.id,
)
# Optional many2one
company_id = fields.Many2one(
'res.company',
string='Company',
ondelete='set null',
)
# With delegate (inherits)
partner_id = fields.Many2one(
'res.partner',
string='Partner',
required=True,
ondelete='cascade',
delegate=True, # Inherits all fields from partner
)
```
**Parameters**:
- `comodel_name` - Target model (positional argument)
- `ondelete` - What to do when referenced record is deleted: `'set null'`, `'restrict'`, `'cascade'`
- `domain` - Domain for searchable dropdown
- `context` - Context passed to action
- `default` - Default value (can be callable)
- `delegate` - Enable inheritance (delegate pattern)
---
### One2many - One-to-Many
```python
# Inverse of Many2one - MUST specify inverse_name
line_ids = fields.One2many(
'sale.order.line',
'order_id',
string='Order Lines',
)
# One2many with computed domain (Odoo 18)
active_line_ids = fields.One2many(
'sale.order.line',
'order_id',
string='Active Lines',
domain=[('state', '!=', 'cancel')],
)
```
**Parameters**:
- `comodel_name` - Target model (positional argument)
- `inverse_name` - Many2one field on target model that points back (REQUIRED)
- `domain` - Domain filter for displayed records
- `copy` - Copy lines on duplicate (default `True`)
**Important**: Always define the corresponding `Many2one` on the child model.
---
### Many2many - Many-to-Many
```python
tag_ids = fields.Many2many(
'sale.order.tag',
'sale_order_tag_rel',
'order_id',
'tag_id',
string='Tags',
)
# Without relation table name (auto-generated)
category_ids = fields.Many2many(
'res.partner.category',
string='Categories',
)
# Many2many with domain
allowed_category_ids = fields.Many2many(
'res.partner.category',
string='Allowed Categories',
domain=[('parent_id', '=', False)],
)
```
**Parameters**:
- `comodel_name` - Target model (positional argument)
- `relation` - Relation table name (optional, auto-generated if omitted)
- `column1` - Column name for this model's ID in relation table
- `column2` - Column name for target model's ID in relation table
- `domain` - Domain for displayed records
---
## Computed Fields
### Basic Compute Field
```python
amount_total = fields.Float(
string='Total',
compute='_compute_amount_total',
)
@api.depends('amount_untaxed', 'tax_amount', 'discount_amount')
def _compute_amount_total(self):
for record in self:
record.amount_total = (
record.amount_untaxed
+ record.tax_amount
- record.discount_amount
)
```
### Stored Compute Field
```python
# Stored - can be searched, used in domains
amount_total = fields.Float(
string='Total',
compute='_compute_amount_total',
store=True,
)
@api.depends('line_ids.price_subtotal')
def _compute_amount_total(self):
for order in self:
order.amount_total = sum(order.line_ids.mapped('price_subtotal'))
```
### Compute with Search
```python
# Allow searching on computed field
display_name = fields.Char(
string='Display Name',
compute='_compute_display_name',
search='_search_display_name',
)
@api.depends('name', 'ref')
def _compute_display_name(self):
for record in self:
record.display_name = f"[{record.ref}] {record.name}"
def _search_display_name(self, operator, value):
return ['|', ('name', operator, value), ('ref', operator, value)]
```
### Compute with Inverse
```python
# Allow writing to computed field (bidirectional)
name = fields.Char(
string='Name',
compute='_compute_name',
inverse='_inverse_name',
)
@api.depends('first_name', 'last_name')
def _compute_name(self):
for record in self:
record.name = f"{record.first_name} {record.last_name}"
def _inverse_name(self):
for record in self:
parts = record.name.split(' ', 1)
record.first_name = parts[0]
record.last_name = parts[1] if len(parts) > 1 else ''
```
---
## Related Fields
### Basic Related Field
```python
partner_name = fields.Char(
string='Partner Name',
related='partner_id.name',
readonly=True,
)
# Store related field (for search/group by)
partner_country_id = fields.Many2one(
'res.country',
string='Country',
related='partner_id.country_id',
store=True,
)
```
### Multi-Level Related
```python
partner_country_code = fields.Char(
string='Country Code',
related='partner_id.country_id.code',
readonly=True,
)
```
### Related with Company Dependency
```python
company_currency_id = fields.Many2one(
'res.currency',
related='company_id.currency_id',
string='Company Currency',
readonly=True,
)
```
---
## Field Parameters
### Common Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `string` | str | Field label (display name) |
| `required` | bool | Field must have value (validation) |
| `readonly` | bool | Field is read-only in UI (not enforced in code) |
| `index` | bool/str | Create database index (`'btree'`, `'btree_not_null'`, `'trigram'`) |
| `default` | value/callable | Default value |
| `copy` | bool | Copy field on duplicate (default `True`, `False` for o2many) |
| `store` | bool | Store in database (default `True`, `False` for computed) |
| `groups` | str | Comma-separated group XML IDs for access control |
| `company_dependent` | bool | Value varies by company (stored as jsonb) |
| `help` | str | Tooltip text |
| `translate` | bool | Enable translation |
| `tracking` | bool/int | Track changes in chatter (`1`=always, `2`=only if set) |
### Index Types
```python
# Standard btree index (good for many2one, equality)
code = fields.Char(string='Code', index=True)
code = fields.Char(string='Code', index='btree')
# Btree not null (most values are NULL)
category_id = fields.Many2one('category', index='btree_not_null')
# Trigram index (full-text search)
name = fields.Char(string='Name', index='trigram')
```
### Default Value Patterns
```python
# Static default
active = fields.Boolean(default=True)
# Callable default (evaluated per record)
date = fields.Date(default=fields.Date.context_today)
datetime = fields.Datetime(default=fields.Datetime.now)
# Lambda default (can access self/env)
user_id = fields.Many2one(
'res.users',
string='User',
default=lambda self: self.env.user,
)
# Company-dependent default
company_id = fields.Many2one(
'res.company',
string='Company',
default=lambda self: self.env.company,
)
```
### Company Dependent Fields
```python
# Value varies by company (property field)
payment_term_id = fields.Many2one(
'account.payment.term',
string='Payment Terms',
company_dependent=True,
)
# Access for specific company
record.with_context(company_id=1).payment_term_id
```
---
## Odoo 18 Field Parameters
### aggregator (Odoo 18)
**Replaces**: `group_operator` (deprecated since Odoo 18)
```python
# Odoo 18+ - use aggregator
amount = fields.Float(
string='Amount',
aggregator='sum', # NEW in Odoo 18
)
# Supported aggregators (from READ_GROUP_AGGREGATE):
# - sum, avg, max, min
# - bool_and, bool_or
# - array_agg, recordset
# - count, count_distinct
```
### precompute (Odoo 18)
Compute field before record insertion.
```python
sequence = fields.Integer(
string='Sequence',
compute='_compute_sequence',
precompute=True, # Compute at form init
store=False,
)
@api.depends('date_order')
def _compute_sequence(self):
for order in self:
if order.date_order:
order.sequence = self.env['ir.sequence'].next_by_code(...)
```
**Warning**: `precompute=True` can be counterproductive for:
- Statistics fields (count, sum over search)
- Fields that require database reads
- One-off record creation (not batch)
### recursive (Odoo 18)
For fields with recursive dependencies like `parent_id.X`.
```python
# Field has dependency like parent_id.X
total = fields.Float(
string='Total',
compute='_compute_total',
store=True,
recursive=True, # Declare recursive dependency explicitly
)
```
### compute_sudo (Odoo 18)
Whether field should be recomputed as superuser.
```python
# Default: True for stored fields, False for non-stored
amount = fields.Float(
string='Amount',
compute='_compute_amount',
store=True,
compute_sudo=True, # Compute as admin (default for stored)
)
price = fields.Float(
string='Price',
compute='_compute_price',
compute_sudo=False, # Compute as current user (default for non-stored)
)
```
### group_operator (Deprecated)
**Deprecated in Odoo 18**: Use `aggregator` instead.
```python
# OLD (deprecated)
amount = fields.Float(group_operator='sum')
# NEW (Odoo 18+)
amount = fields.Float(aggregator='sum')
```
---
## Field Type Selection Guide
| Requirement | Use Field |
|-------------|-----------|
| Short text (name, code) | `Char` |
| Long text (description) | `Text` |
| HTML content (email, web) | `Html` |
| Yes/No | `Boolean` |
| Whole number | `Integer` |
| Decimal (non-currency) | `Float` |
| Money | `Monetary` |
| Date only | `Date` |
| Date + time | `Datetime` |
| File/Attachment | `Binary` |
| Dropdown options | `Selection` |
| Many-to-one relation | `Many2one` |
| One-to-many relation | `One2many` |
| Many-to-many relation | `Many2many` |
| Derived from other fields | `compute` |
| Field from related record | `related` |
| Multi-company value | `company_dependent=True` |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |