Frappe DocType Patterns

Comprehensive guide to creating and configuring DocTypes in Frappe Framework, the core building block for all Frappe applications.

When to Use This Skill

Creating new DocTypes
Adding or modifying fields on DocTypes
Designing data models and relationships
Setting up naming patterns and autoname
Configuring permissions and workflows
Creating child tables
Working with Virtual or Single DocTypes

DocType Directory Structure

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

DocType JSON Structure

json

{
  "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"
}

Field Types Reference

Text Fields

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)

Numeric Fields

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

Date/Time Fields

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

Selection Fields

Type	Description	Use Case
`Select`	Dropdown options	Status, type
`Check`	Boolean checkbox	Flags, toggles
`Autocomplete`	Text with suggestions	Tags

Link Fields

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

Special Fields

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

Layout Fields

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

Field Options

Common Field Properties

json

{
  "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"
}

Link Field Options

json

{
  "fieldname": "customer",
  "fieldtype": "Link",
  "options": "Customer",
  "filters": {
    "disabled": 0,
    "customer_type": "Company"
  },
  "ignore_user_permissions": 0
}

Select Field Options

json

{
  "fieldname": "status",
  "fieldtype": "Select",
  "options": "\nDraft\nPending\nApproved\nRejected",
  "default": "Draft"
}

Dynamic Link

json

{
  "fieldname": "party_type",
  "fieldtype": "Link",
  "options": "DocType"
},
{
  "fieldname": "party",
  "fieldtype": "Dynamic Link",
  "options": "party_type"
}

Naming Patterns (autoname)

Naming Series

json

{
  "autoname": "naming_series:",
  "naming_rule": "By \"Naming Series\" field"
}

Add a naming_series field:

json

{
  "fieldname": "naming_series",
  "fieldtype": "Select",
  "options": "INV-.YYYY.-\nINV-.MM.-.YYYY.-",
  "default": "INV-.YYYY.-"
}

Field-Based Naming

json

{
  "autoname": "field:customer_code",
  "naming_rule": "By fieldname"
}

Expression-Based

json

{
  "autoname": "format:{customer_type}-{###}",
  "naming_rule": "Expression"
}

Hash/Random

json

{
  "autoname": "hash",
  "naming_rule": "Random"
}

Prompt (Manual)

json

{
  "autoname": "Prompt",
  "naming_rule": "Set by user"
}

Controller Lifecycle Hooks

python

# 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)

Child Table (Table Field)

Parent DocType

json

{
  "fieldname": "items",
  "fieldtype": "Table",
  "label": "Items",
  "options": "My DocType Item",
  "reqd": 1
}

Child DocType JSON

json

{
  "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
    }
  ]
}

Single DocType (Settings)

For application settings that have only one record:

json

{
  "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:

python

settings = frappe.get_single("My App Settings")
if settings.enable_feature:
    do_something()

Virtual DocType

DocType without database table, computed on-the-fly:

json

{
  "name": "My Virtual DocType",
  "module": "My Module",
  "doctype": "DocType",
  "is_virtual": 1
}

Controller:

python

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

json

{
  "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
    }
  ]
}

Best Practices

Naming Conventions

Use singular names: "Customer" not "Customers"
Use Title Case with spaces: "Sales Invoice"
Fieldnames use snake_case: customer_name

Field Design

Put most important fields first
Use Section Breaks to organize
Use Tab Breaks for complex forms
Set in_list_view for key fields
Set in_standard_filter for filterable fields

Performance

Index frequently queried fields with search_index: 1
Use read_only to prevent unnecessary validation
Limit child table rows with max_attachments

Data Integrity

Use unique: 1 for unique constraints
Set appropriate reqd (required) flags
Use depends_on for conditional visibility
Use mandatory_depends_on for conditional requirements

Common Patterns

Status Field Pattern

json

{
  "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
}

Amount Calculation Pattern

json

[
  {"fieldname": "qty", "fieldtype": "Float"},
  {"fieldname": "rate", "fieldtype": "Currency"},
  {"fieldname": "amount", "fieldtype": "Currency", "read_only": 1}
]

With controller:

python

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)

Linked Document Pattern

json

{
  "fieldname": "customer",
  "fieldtype": "Link",
  "options": "Customer",
  "reqd": 1
},
{
  "fieldname": "customer_name",
  "fieldtype": "Data",
  "fetch_from": "customer.customer_name",
  "read_only": 1
}

Frappe DocType Patterns ​

When to Use This Skill ​

DocType Directory Structure ​

DocType JSON Structure ​

Field Types Reference ​

Text Fields ​

Numeric Fields ​

Date/Time Fields ​

Selection Fields ​

Link Fields ​

Special Fields ​

Layout Fields ​

Field Options ​

Common Field Properties ​

Link Field Options ​

Select Field Options ​

Dynamic Link ​

Naming Patterns (autoname) ​

Naming Series ​

Field-Based Naming ​

Expression-Based ​

Hash/Random ​

Prompt (Manual) ​

Controller Lifecycle Hooks ​

Child Table (Table Field) ​

Parent DocType ​

Child DocType JSON ​

Single DocType (Settings) ​

Virtual DocType ​

Permissions ​

Best Practices ​

Naming Conventions ​

Field Design ​

Performance ​

Data Integrity ​

Common Patterns ​

Status Field Pattern ​

Amount Calculation Pattern ​

Linked Document Pattern ​

Frappe DocType Patterns

When to Use This Skill

DocType Directory Structure

DocType JSON Structure

Field Types Reference

Text Fields

Numeric Fields

Date/Time Fields

Selection Fields

Link Fields

Special Fields

Layout Fields

Field Options

Common Field Properties

Link Field Options

Select Field Options

Dynamic Link

Naming Patterns (autoname)

Naming Series

Field-Based Naming

Expression-Based

Hash/Random

Prompt (Manual)

Controller Lifecycle Hooks

Child Table (Table Field)

Parent DocType

Child DocType JSON

Single DocType (Settings)

Virtual DocType

Permissions

Best Practices

Naming Conventions

Field Design

Performance

Data Integrity

Common Patterns

Status Field Pattern

Amount Calculation Pattern

Linked Document Pattern