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

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

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

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

Select Field Options

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

Dynamic Link

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

Naming Patterns (autoname)

Naming Series

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

Field-Based Naming

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

Expression-Based

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

Hash/Random

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

Prompt (Manual)

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

Controller Lifecycle Hooks

# 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

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

Child DocType 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:

{
  "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()

Virtual DocType

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

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

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

[
  {"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)

Linked Document Pattern

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