[Skip to content](#main)

[→](/)

[![Avunu](/brand/avunu-logo.svg)![Avunu](/brand/avunu-logo-light.svg)](/)[Services](/services/)[Consulting](/services/consulting/)[ERP](/services/erp/)[Odoo](/services/erp/odoo/)[ERPNext](/services/erp/erpnext/)[Custom software](/services/custom-software/)[Devices & IoT](/services/devices-iot/)[Websites](/services/websites/)[Infrastructure](/services/infrastructure/)[Partners](/partners/)

[Work](/work/)[Open source](/open-source/)[Knowledge base](/kb/)[About](/about/)

[About Avunu](/about/)[Team](/about/team/)[Insights](/insights/)[Contact](/contact/)

[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

- [Services](/services/)[Consulting](/services/consulting/)
- [ERP](/services/erp/)
- [Odoo](/services/erp/odoo/)
- [ERPNext](/services/erp/erpnext/)
- [Custom software](/services/custom-software/)
- [Devices & IoT](/services/devices-iot/)
- [Websites](/services/websites/)
- [Infrastructure](/services/infrastructure/)
- [Partners](/partners/)

[Work](/work/)[Open source](/open-source/)[Knowledge base](/kb/)[About](/about/)

- [About Avunu](/about/)
- [Team](/about/team/)
- [Insights](/insights/)
- [Contact](/contact/)

[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

[Knowledge base](/kb/)[Frappe](/kb/frappe/)Customizations API

Search the knowledge basePress/

ESC

Jump to

[Browse the knowledge base](/kb/)[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[NixOS](/kb/nixos/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

↵select↑↓navigateescclose

Search the knowledge base

[Skip to the article](#kb-article)[Frappe](/kb/frappe/)20 articles

- [Overview](/kb/frappe/)
- [Bench Operations](/kb/frappe/bench-operations/)
- [Builder Page Scripts](/kb/frappe/builder-page-scripts/)
- [Client-Side Recipes](/kb/frappe/client-side-recipes/)
- [Common Query Patterns](/kb/frappe/common-query-patterns/)
- [Custom Field Controllers](/kb/frappe/custom-field-controllers/)
- [Custom Pages](/kb/frappe/custom-pages/)
- [Custom Views](/kb/frappe/custom-views/)
- [Customizations API](/kb/frappe/customizations-api/)
- [Customizing Grid Columns for Child Tables](/kb/frappe/customizing-grid-columns-child-tables/)
- [Doctype States & Status Fields](/kb/frappe/doctype-states-status-fields/)
- [Grandchild Table Fields](/kb/frappe/grandchild-table-fields/)
- [Portal Views](/kb/frappe/portal-views/)
- [Project Structure & Hooks](/kb/frappe/project-structure-hooks/)
- [Query Builder & PyPika Extensions](/kb/frappe/query-builder-pypika/)
- [Quick Entry Forms](/kb/frappe/quick-entry-forms/)
- [Script Reports](/kb/frappe/script-reports/)
- [Testing on Live Databases](/kb/frappe/testing-live-databases/)
- [Type Annotations & Controller Overrides](/kb/frappe/type-annotations-controller-overrides/)
- [Vite & TypeScript Compilation](/kb/frappe/vite-typescript-compilation/)
- [Web Forms](/kb/frappe/web-forms/)

Other sections[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[NixOS](/kb/nixos/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

In Frappe: 20 articles

[Overview](/kb/frappe/)[Bench Operations](/kb/frappe/bench-operations/)[Builder Page Scripts](/kb/frappe/builder-page-scripts/)[Client-Side Recipes](/kb/frappe/client-side-recipes/)[Common Query Patterns](/kb/frappe/common-query-patterns/)[Custom Field Controllers](/kb/frappe/custom-field-controllers/)[Custom Pages](/kb/frappe/custom-pages/)[Custom Views](/kb/frappe/custom-views/)[Customizations API](/kb/frappe/customizations-api/)[Customizing Grid Columns for Child Tables](/kb/frappe/customizing-grid-columns-child-tables/)[Doctype States & Status Fields](/kb/frappe/doctype-states-status-fields/)[Grandchild Table Fields](/kb/frappe/grandchild-table-fields/)[Portal Views](/kb/frappe/portal-views/)[Project Structure & Hooks](/kb/frappe/project-structure-hooks/)[Query Builder & PyPika Extensions](/kb/frappe/query-builder-pypika/)[Quick Entry Forms](/kb/frappe/quick-entry-forms/)[Script Reports](/kb/frappe/script-reports/)[Testing on Live Databases](/kb/frappe/testing-live-databases/)[Type Annotations & Controller Overrides](/kb/frappe/type-annotations-controller-overrides/)[Vite & TypeScript Compilation](/kb/frappe/vite-typescript-compilation/)[Web Forms](/kb/frappe/web-forms/)

Other sections[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[NixOS](/kb/nixos/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

FrappeCustomizations API

Override doctypes from other apps with version-controlled JSON and Python controller pairs instead of Customize Form.

UpdatedMar 13, 2026

Tagsfrappecustomizationdoctypepython

Reading time5 min

On this page[File Structure](#file-structure)[JSON Customization File](#json-customization-file)[Custom Fields](#custom-fields)[Property Setters](#property-setters)[Links (Doctype Form Connections)](#links-doctype-form-connections)[Python Controller Override](#python-controller-override)[Registration in hooks.py](#registration-in-hookspy)[When to Use Each Component](#when-to-use-each-component)[Multiple Approaches Compared](#multiple-approaches-compared)

Override doctypes from other apps (Frappe, ERPNext, etc.) using hand-crafted JSON + Python controller pairs. This is the preferred alternative to the Customize Form UI for version-controlled, app-distributed customizations.

## File Structure

Place customization files in `<app>/<app>/custom/`:

```text
myapp/myapp/custom/
├── item.json          # Custom fields, property setters, links for Item
├── item.py            # Controller override for Item
├── bom.json           # Custom fields for BOM
├── bom.py             # Controller override for BOM
├── bom_item.json      # Custom fields for BOM Item (child table)
├── bom_item.py        # Controller override for BOM Item
└── notification.json  # Custom fields only (no .py needed)
```

**No `__init__.py`** — this is not a Python package, just a directory of paired files.

**Naming convention:** Files are named after the DocType in **snake_case** (e.g., `BOM Item` → `bom_item.json`/`bom_item.py`).

## JSON Customization File

Each `.json` file follows this schema:

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">{</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"custom_fields"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: [</span><span style="--shiki-dark:#FFA198;--shiki-dark-font-style:italic;--shiki-light:#82071E;--shiki-light-font-style:italic">...</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">],</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"custom_perms"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: [],</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"doctype"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Item"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"links"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: [</span><span style="--shiki-dark:#FFA198;--shiki-dark-font-style:italic;--shiki-light:#82071E;--shiki-light-font-style:italic">...</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">],</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"property_setters"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: [</span><span style="--shiki-dark:#FFA198;--shiki-dark-font-style:italic;--shiki-light:#82071E;--shiki-light-font-style:italic">...</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">],</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"sync_on_migrate"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">1</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}</span>
```

The `"sync_on_migrate": 1` flag tells Frappe to automatically apply these customizations during `bench migrate`. No explicit registration in `hooks.py` is needed for the JSON files.

### Custom Fields

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">{</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"custom_fields"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: [</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"dt"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Item"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"fieldname"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"valuation_uom"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"fieldtype"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Link"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"options"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"UOM"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"insert_after"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"valuation_rate"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"is_system_generated"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">1</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"label"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Valuation UOM"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"module"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"MyApp"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"name"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Item-valuation_uom"</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        },</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"dt"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"BOM"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"fieldname"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"part_group_measurements"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"fieldtype"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Table"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"options"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"BOM Part Group Measurement"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"insert_after"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"items"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"is_system_generated"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">1</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"label"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Part Groups"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"module"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"MyApp"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"name"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"BOM-part_group_measurements"</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        }</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    ]</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}</span>
```

Key properties:

**`dt`** — Target DocType

**`fieldname`** — Internal field name

**`fieldtype`** — Frappe field type (`Link`, `Data`, `Float`, `Table`, `Currency`, `Int`, `Percent`, etc.)

**`options`** — For Link/Table: the linked DocType

**`insert_after`** — Position: placed after this existing field

**`is_system_generated`** — Mark as `1` to distinguish from user-created custom fields

**`module`** — Your app's module name

**`name`** — Unique identifier following pattern `{DocType}-{fieldname}`

**`columns`**, **`in_list_view`**, **`read_only`** — Optional display properties

### Property Setters

Modify properties of **existing** standard fields:

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">{</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"property_setters"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: [</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"doc_type"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"BOM Item"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"doctype_or_field"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"DocField"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"field_name"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"item_code"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"is_system_generated"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">1</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"module"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"MyApp"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"name"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"BOM Item-item_code-columns"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"property"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"columns"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"property_type"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Int"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"value"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"1"</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        },</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"doc_type"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Item"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"doctype_or_field"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"DocType"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"is_system_generated"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">1</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"module"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"MyApp"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"name"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Item-main-search_fields"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"property"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"search_fields"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"property_type"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Data"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"value"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"item_code,item_name,customer_code"</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        }</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    ]</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}</span>
```

**Field-level** (`doctype_or_field: "DocField"`):

`name` pattern: `{DocType}-{field_name}-{property}`

`field_name` identifies the target field

**DocType-level** (`doctype_or_field: "DocType"`):

`name` pattern: `{DocType}-main-{property}`

`field_name` is omitted

Used for global doctype properties like `search_fields`, `show_title_field_in_link`

#### Workaround: JSON values in Property Setters (frappe/frappe#37967)

Frappe requires all `value` entries in `property_setters` to be strings. For complex properties like `field_order`, this means writing the entire array as a single escaped JSON string — unreadable and hard to maintain.

**The problem** — this causes `frappe.exceptions.ValidationError: Value for Set Value cannot be a list` at migrate time:

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">{</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"doc_type"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Purchase Order Item"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"doctype_or_field"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"DocType"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"name"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Purchase Order Item-field_order"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"property"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"field_order"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"property_type"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Data"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"value"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: [</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"item_code"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"item_name"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"qty"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"..."</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">]</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}</span>
```

**The fix** — override the `PropertySetter` controller to auto-serialize non-string values. Place this in `<app>/<app>/custom/property_setter.py`:

```
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">import</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> json</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">import</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">from</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">import</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> _</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">from</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe.custom.doctype.property_setter.property_setter </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">import</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> PropertySetter </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">as</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> BasePropertySetter</span>

<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">class</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">PropertySetter</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">BasePropertySetter</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">):</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"""Custom Property Setter override to support JSON-value customizations."""</span>

<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">def</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">validate</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(self) -> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">None</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"""Serialize non-string values to JSON before Frappe validates."""</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">if</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">not</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">isinstance</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">self</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.value, </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">str</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">):</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">try</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">                </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">self</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.value </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> json.dumps(</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">self</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.value)</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">except</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> (</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">TypeError</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">ValueError</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">):</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">                frappe.throw(_(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Invalid JSON value for Property Setter: </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">{0}</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">).format(</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">self</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.value))</span>

<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">super</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">().validate()</span>
```

Register it in `hooks.py`:

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">override_doctype_class </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Property Setter"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"myapp.myapp.custom.property_setter.PropertySetter"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}</span>
```

With this in place, `value` can be a native JSON array or object in your `.json` files and will be serialized automatically at migrate time. String values are passed through unchanged, so existing customizations are unaffected.

### Links (Doctype Form Connections)

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">{</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"links"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: [</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"custom"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">1</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"group"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Reference"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"link_doctype"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Sales Quote"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"link_fieldname"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"final_bom"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"parent"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"BOM"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"parentfield"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"links"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"parenttype"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Customize Form"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"is_child_table"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">0</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"table_fieldname"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">null</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            </span><span style="--shiki-dark:#7EE787;--shiki-light:#116329">"parent_doctype"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">null</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        }</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    ]</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}</span>
```

This adds a "Sales Quote" link in the BOM form's sidebar, showing all Sales Quotes where `final_bom` references the current BOM.

## Python Controller Override

Pair a `.py` file with the `.json` to override the controller class:

```
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">from</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> erpnext.stock.doctype.item.item </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">import</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> Item </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">as</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> BaseItem</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">from</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe.types </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">import</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">DF</span>

<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">class</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">Item</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">BaseItem</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">):</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"""Custom Item override with additional field types."""</span>

<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#8B949E;--shiki-light:#6E7781"># Custom fields from item.json — annotated for type checking</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    valuation_uom: </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">DF</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.Link </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">|</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">None</span>
```

See [Type Annotations & Controller Overrides](/kb/frappe/type-annotations-controller-overrides/) for comprehensive typing patterns.

## Registration in hooks.py

The JSON files sync automatically via `sync_on_migrate: 1`. The Python overrides must be registered:

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">override_doctype_class </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Item"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"myapp.myapp.custom.item.Item"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"BOM"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"myapp.myapp.custom.bom.BOM"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"BOM Item"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"myapp.myapp.custom.bom_item.BOMItem"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Customer"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"myapp.myapp.custom.customer.Customer"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}</span>
```

**Key:** Standard DocType name → **Value:** Dotted Python path to override class.

Frappe replaces the standard class with the override whenever that DocType is loaded via `frappe.get_doc()`.

## When to Use Each Component

| Need                                         | Mechanism                                   |
| -------------------------------------------- | ------------------------------------------- |
| Add fields to someone else's DocType         | `.json` with `custom_fields`                |
| Change properties of existing fields         | `.json` with `property_setters`             |
| Add sidebar links                            | `.json` with `links`                        |
| Custom permissions                           | `.json` with `custom_perms`                 |
| Override methods (validate, save, etc.)      | `.py` controller + `override_doctype_class` |
| Hook into document events without overriding | `doc_events` in hooks.py                    |
| Event hooks that apply to all DocTypes       | `doc_events` with `"*"` key                 |

## Multiple Approaches Compared

| Approach                               | Version Controlled | Team Friendly  | Survives Migrate         |
| -------------------------------------- | ------------------ | -------------- | ------------------------ |
| Customize Form UI                      | No (stored in DB)  | No (conflicts) | Fragile                  |
| `custom/*.json` with `sync_on_migrate` | Yes                | Yes            | Yes                      |
| Fixtures                               | Yes                | Yes            | Requires explicit import |

The `custom/*.json` approach is strongly preferred because it:

Lives in version control alongside the override code

Auto-syncs on every `bench migrate`

Pairs naturally with Python controller overrides

Uses the same schema as Frappe's internal customization storage

Need help with Frappe?

Our notes can take you a long way, but sometimes you'd rather have someone who's done it before.

[ERPNext implementation](/services/erp/erpnext/)

[← PreviousCustom Views](/kb/frappe/custom-views/)[Next →Customizing Grid Columns for Child Tables](/kb/frappe/customizing-grid-columns-child-tables/)

CC0This article is in the public domain ([CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/)), code samples included. Use it however helps you.

On this page

- [File Structure](#file-structure)
- [JSON Customization File](#json-customization-file)
- [Custom Fields](#custom-fields)
- [Property Setters](#property-setters)
- [Links (Doctype Form Connections)](#links-doctype-form-connections)
- [Python Controller Override](#python-controller-override)
- [Registration in hooks.py](#registration-in-hookspy)
- [When to Use Each Component](#when-to-use-each-component)
- [Multiple Approaches Compared](#multiple-approaches-compared)

[Back to top↑](#top)

Services

- [ERP implementation](/services/erp/)
- [Odoo](/services/erp/odoo/)
- [ERPNext](/services/erp/erpnext/)
- [Custom software](/services/custom-software/)
- [Devices & IoT](/services/devices-iot/)
- [Websites](/services/websites/)
- [Infrastructure](/services/infrastructure/)

Resources

- [Our work](/work/)
- [Open source](/open-source/)
- [Knowledge base](/kb/)
- [Insights](/insights/)

Company

- [About](/about/)
- [Team](/about/team/)
- [Partners](/partners/)
- [Contact](/contact/)

Clients

- [Project portal](https://erp.avunu.net/projects)
- [Invoices](https://erp.avunu.net/)
- [Support](https://erp.avunu.net/)

[![Avunu](/brand/avunu-logo-light.svg)](/)[\<av-icon data-jx-static>\<svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" stroke="none" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">\<path d="M20.400 20.500h-3.600v-5.600c0-1.300 0-3-1.800-3s-2.100 1.400-2.100 2.900v5.700H9.400V9h3.400v1.600c.5-.9 1.600-1.900 3.400-1.900 3.600 0 4.300 2.400 4.300 5.500v6.300zM5.300 7.400a2.100 2.100 0 1 1 0-4.100 2.100 2.100 0 0 1 0 4.100zm1.800 13.100H3.600V9h3.500v11.500zM22.200 0H1.800C.8 0 0 .8 0 1.700v20.600c0 .9.800 1.700 1.800 1.700h20.400c1 0 1.800-.8 1.800-1.700V1.700C24 .8 23.200 0 22.200 0z">\</path>\</svg>\</av-icon>](https://www.linkedin.com/company/avunu)[\<av-icon data-jx-static>\<svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" stroke="none" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">\<path d="M12 .3a12 12 0 0 0-3.8 23.4c.6.1.8-.3.8-.6v-2c-3.3.7-4-1.6-4-1.6-.6-1.4-1.4-1.8-1.4-1.8-1-.7.1-.7.1-.7 1.2.1 1.8 1.2 1.8 1.2 1 1.8 2.8 1.3 3.5 1 .1-.8.4-1.3.7-1.6-2.7-.3-5.5-1.3-5.5-5.9 0-1.3.5-2.4 1.2-3.2-.1-.3-.5-1.5.1-3.2 0 0 1-.3 3.3 1.2a11.500 11.500 0 0 1 6 0c2.300-1.500 3.300-1.200 3.300-1.200.6 1.700.2 2.900.1 3.200.8.8 1.200 1.900 1.200 3.200 0 4.600-2.800 5.600-5.500 5.900.4.400.8 1.100.8 2.200v3.300c0 .3.2.7.8.6A12 12 0 0 0 12 .3">\</path>\</svg>\</av-icon>](https://github.com/Avunu)[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

Avunu LLC · 948 East Philadelphia Street, York, PA 17403 · (717) 814-8540Knowledge base articles are in the public domain[Privacy](/privacy/)[Terms](/terms/)
