doctype-development

Frappe DocType Development

Build and modify DocTypes—the core data model abstraction in Frappe Framework.

When to use

• Creating new DocTypes (standard, single, child table, submittable, tree)
• Adding or modifying fields on existing DocTypes
• Implementing controller logic (validate, before_save, on_submit, etc.)
• Setting up naming series and auto-naming
• Configuring permissions and workflows
• Building child tables and parent-child relationships

Inputs required

• Target app and module path
• DocType name and type (standard/single/child/submittable/tree)
• Field definitions (name, type, options)
• Permission requirements by role
• Whether workflow is needed

Procedure

0) Verify environment

# Ensure developer mode is enabled
bench --site <site> console
>>> frappe.conf.developer_mode  # Must be True

1) Choose DocType type

Type	Use Case	Key Setting
Standard	Multiple records	Default
Single	Config/settings (one record)	issingle: 1
Child Table	Rows in parent table	istable: 1
Submittable	Draft→Submit→Cancel workflow	is_submittable: 1
Tree	Hierarchical data	is_tree: 1
Virtual	External data source	is_virtual: 1

2) Create DocType

Option A: Via UI (recommended for new DocTypes)

1. Navigate to DocType List → New
2. Define fields, permissions, settings
3. Save (exports to app in developer mode)

Option B: Via code

# Create DocType JSON in: 
# <app>/<module>/doctype/<doctype_name>/<doctype_name>.json

3) Define fields

Common field patterns:

{
  "fieldname": "customer",
  "fieldtype": "Link",
  "label": "Customer",
  "options": "Customer",
  "reqd": 1
}

See references/field-types.md for all field types.

4) Implement controller

Create <doctype_name>.py alongside the JSON:

import frappe
from frappe.model.document import Document

class MyDocType(Document):
    def validate(self):
        # Lightweight validation
        if not self.customer:
            frappe.throw("Customer is required")
    
    def before_save(self):
        # Pre-save normalization
        self.full_name = f"{self.first_name} {self.last_name}"
    
    def after_insert(self):
        # Post-create side effects
        frappe.publish_realtime("new_doc", {"name": self.name})