Frappe DocType creation patterns, field types, controller hooks, and data modeling best practices. Use when creating DocTypes, designing data models, adding fields, or setting up document relationships in Frappe/ERPNext.
This skill inherits all available tools. When active, it can use any tool Claude has access to.
Comprehensive guide to creating and configuring DocTypes in Frappe Framework, the core building block for all Frappe applications.
When you create a DocType named "My Custom DocType" in module "My Module":
my_app/
└── my_module/
└── doctype/
└── my_custom_doctype/
├── my_custom_doctype.json # DocType definition
├── my_custom_doctype.py # Python controller
├── my_custom_doctype.js # Client script
├── test_my_custom_doctype.py # Test file
└── __init__.py
{
"name": "My Custom DocType",
"module": "My Module",
"doctype": "DocType",
"engine": "InnoDB",
"field_order": ["field1", "field2"],
"fields": [
{
"fieldname": "field1",
"fieldtype": "Data",
"label": "Field 1",
"reqd": 1
}
],
"permissions": [
{
"role": "System Manager",
"read": 1,
"write": 1,
"create": 1,
"delete": 1
}
],
"autoname": "naming_series:",
"naming_rule": "By \"Naming Series\" field",
"is_submittable": 0,
"istable": 0,
"issingle": 0,
"track_changes": 1,
"sort_field": "modified",
"sort_order": "DESC"
}
| Type | Description | Use Case |
|---|---|---|
Data | Single line text (140 chars) | Names, codes, short text |
Small Text | Multi-line text | Short descriptions |
Text | Multi-line text (unlimited) | Long descriptions |
Text Editor | Rich text with formatting | Content, notes |
Code | Syntax-highlighted code | Python, JS, JSON |
HTML Editor | WYSIWYG HTML | Email templates |
Markdown Editor | Markdown input | Documentation |
Password | Masked input | Secrets (stored encrypted) |
| Type | Description | Use Case |
|---|---|---|
Int | Integer | Counts, quantities |
Float | Decimal number | Measurements |
Currency | Money with precision | Prices, amounts |
Percent | 0-100 percentage | Discounts, rates |
Rating | Star rating (0-1) | Reviews, scores |
| Type | Description | Use Case |
|---|---|---|
Date | Date only | Birth dates, due dates |
Datetime | Date and time | Timestamps |
Time | Time only | Schedules |
Duration | Time duration | Task duration |
| Type | Description | Use Case |
|---|---|---|
Select | Dropdown options | Status, type |
Check | Boolean checkbox | Flags, toggles |
Autocomplete | Text with suggestions | Tags |
| Type | Description | Use Case |
|---|---|---|
Link | Reference to another DocType | Foreign key relationship |
Dynamic Link | Reference based on another field | Polymorphic links |
Table | Child table (1-to-many) | Line items, details |
Table MultiSelect | Many-to-many via link | Multiple selections |
| Type | Description | Use Case |
|---|---|---|
Attach | Single file attachment | Documents |
Attach Image | Image with preview | Photos, logos |
Image | Display image from URL field | Gallery |
Signature | Signature pad | Approvals |
Geolocation | Map coordinates | Locations |
Barcode | Barcode/QR display | Inventory |
JSON | JSON data | Configuration |
| Type | Description | Use Case |
|---|---|---|
Section Break | Horizontal section divider | Form organization |
Column Break | Vertical column divider | Multi-column layout |
Tab Break | Tab navigation | Large forms |
HTML | Static HTML content | Instructions, headers |
Heading | Section heading | Visual separation |
Button | Clickable button | Actions |
{
"fieldname": "customer",
"fieldtype": "Link",
"label": "Customer",
"options": "Customer",
"reqd": 1,
"unique": 0,
"in_list_view": 1,
"in_standard_filter": 1,
"in_global_search": 1,
"bold": 1,
"read_only": 0,
"hidden": 0,
"print_hide": 0,
"no_copy": 0,
"allow_in_quick_entry": 1,
"translatable": 0,
"default": "",
"description": "Select the customer",
"depends_on": "eval:doc.is_customer",
"mandatory_depends_on": "eval:doc.status=='Active'",
"read_only_depends_on": "eval:doc.docstatus==1"
}
{
"fieldname": "customer",
"fieldtype": "Link",
"options": "Customer",
"filters": {
"disabled": 0,
"customer_type": "Company"
},
"ignore_user_permissions": 0
}
{
"fieldname": "status",
"fieldtype": "Select",
"options": "\nDraft\nPending\nApproved\nRejected",
"default": "Draft"
}
{
"fieldname": "party_type",
"fieldtype": "Link",
"options": "DocType"
},
{
"fieldname": "party",
"fieldtype": "Dynamic Link",
"options": "party_type"
}
{
"autoname": "naming_series:",
"naming_rule": "By \"Naming Series\" field"
}
Add a naming_series field:
{
"fieldname": "naming_series",
"fieldtype": "Select",
"options": "INV-.YYYY.-\nINV-.MM.-.YYYY.-",
"default": "INV-.YYYY.-"
}
{
"autoname": "field:customer_code",
"naming_rule": "By fieldname"
}
{
"autoname": "format:{customer_type}-{###}",
"naming_rule": "Expression"
}
{
"autoname": "hash",
"naming_rule": "Random"
}
{
"autoname": "Prompt",
"naming_rule": "Set by user"
}
# my_doctype.py
import frappe
from frappe.model.document import Document
class MyDocType(Document):
# ===== BEFORE DATABASE OPERATIONS =====
def autoname(self):
"""Set the document name before saving"""
self.name = f"{self.prefix}-{frappe.generate_hash()[:8]}"
def before_naming(self):
"""Called before autoname, can modify naming logic"""
pass
def validate(self):
"""Validate data before save (called on insert and update)"""
self.validate_dates()
self.calculate_totals()
def before_validate(self):
"""Called before validate"""
pass
def before_save(self):
"""Called before document is saved to database"""
self.modified_by_script = True
def before_insert(self):
"""Called before new document is inserted"""
self.set_defaults()
# ===== AFTER DATABASE OPERATIONS =====
def after_insert(self):
"""Called after new document is inserted"""
self.notify_users()
def on_update(self):
"""Called after document is saved (insert or update)"""
self.update_related_docs()
def after_save(self):
"""Called after on_update, always runs"""
pass
def on_change(self):
"""Called when document changes in database"""
pass
# ===== SUBMISSION WORKFLOW =====
def before_submit(self):
"""Called before document is submitted"""
self.validate_for_submit()
def on_submit(self):
"""Called after document is submitted"""
self.create_gl_entries()
def before_cancel(self):
"""Called before document is cancelled"""
self.validate_cancellation()
def on_cancel(self):
"""Called after document is cancelled"""
self.reverse_gl_entries()
def on_update_after_submit(self):
"""Called when submitted doc is updated (limited fields)"""
pass
# ===== DELETION =====
def before_delete(self):
"""Called before document is deleted"""
self.check_dependencies()
def after_delete(self):
"""Called after document is deleted"""
self.cleanup_attachments()
def on_trash(self):
"""Called when document is trashed"""
pass
def after_restore(self):
"""Called after document is restored from trash"""
pass
# ===== CUSTOM METHODS =====
def validate_dates(self):
if self.end_date and self.start_date > self.end_date:
frappe.throw("End date cannot be before start date")
def calculate_totals(self):
self.total = sum(d.amount for d in self.items)
{
"fieldname": "items",
"fieldtype": "Table",
"label": "Items",
"options": "My DocType Item",
"reqd": 1
}
{
"name": "My DocType Item",
"module": "My Module",
"doctype": "DocType",
"istable": 1,
"editable_grid": 1,
"fields": [
{
"fieldname": "item",
"fieldtype": "Link",
"options": "Item",
"in_list_view": 1,
"reqd": 1
},
{
"fieldname": "qty",
"fieldtype": "Float",
"in_list_view": 1
},
{
"fieldname": "rate",
"fieldtype": "Currency",
"in_list_view": 1
},
{
"fieldname": "amount",
"fieldtype": "Currency",
"in_list_view": 1,
"read_only": 1
}
]
}
For application settings that have only one record:
{
"name": "My App Settings",
"module": "My Module",
"doctype": "DocType",
"issingle": 1,
"fields": [
{
"fieldname": "enable_feature",
"fieldtype": "Check",
"label": "Enable Feature"
},
{
"fieldname": "api_key",
"fieldtype": "Password",
"label": "API Key"
}
]
}
Access in code:
settings = frappe.get_single("My App Settings")
if settings.enable_feature:
do_something()
DocType without database table, computed on-the-fly:
{
"name": "My Virtual DocType",
"module": "My Module",
"doctype": "DocType",
"is_virtual": 1
}
Controller:
class MyVirtualDocType(Document):
@staticmethod
def get_list(args):
# Return list of virtual documents
return [{"name": "doc1", "value": 100}]
@staticmethod
def get_count(args):
return len(MyVirtualDocType.get_list(args))
@staticmethod
def get_stats(args):
return {}
{
"permissions": [
{
"role": "System Manager",
"read": 1,
"write": 1,
"create": 1,
"delete": 1,
"submit": 1,
"cancel": 1,
"amend": 1,
"report": 1,
"export": 1,
"import": 1,
"share": 1,
"print": 1,
"email": 1
},
{
"role": "Sales User",
"read": 1,
"write": 1,
"create": 1,
"if_owner": 1
}
]
}
customer_namein_list_view for key fieldsin_standard_filter for filterable fieldssearch_index: 1read_only to prevent unnecessary validationmax_attachmentsunique: 1 for unique constraintsreqd (required) flagsdepends_on for conditional visibilitymandatory_depends_on for conditional requirements{
"fieldname": "status",
"fieldtype": "Select",
"options": "\nDraft\nPending Approval\nApproved\nRejected",
"default": "Draft",
"in_list_view": 1,
"in_standard_filter": 1,
"read_only": 1,
"allow_on_submit": 1
}
[
{"fieldname": "qty", "fieldtype": "Float"},
{"fieldname": "rate", "fieldtype": "Currency"},
{"fieldname": "amount", "fieldtype": "Currency", "read_only": 1}
]
With controller:
def validate(self):
for item in self.items:
item.amount = flt(item.qty) * flt(item.rate)
self.total = sum(item.amount for item in self.items)
{
"fieldname": "customer",
"fieldtype": "Link",
"options": "Customer",
"reqd": 1
},
{
"fieldname": "customer_name",
"fieldtype": "Data",
"fetch_from": "customer.customer_name",
"read_only": 1
}