DocTypes in Frappe Framework (Version 15): Complete Documentation

(Strictly based on Frappe v15 official documentation & GitHub repository)

DocTypes are the core data model of the Frappe Framework. Every document—whether a Customer, Sales Invoice, Item, User, or custom entity—is defined as a DocType. Understanding DocTypes is essential for ERPNext development, Frappe app development, data modeling, business logic creation, and system customization.

This guide provides a complete, structured, SEO-optimized, AEO-ready, and GEO-friendly explanation of DocTypes in Frappe Framework v15.

1. What Is a DocType in Frappe?

A DocType is the metadata definition of any document in Frappe. It describes:

• The fields it contains
• The permissions applied
• The behavior of the document
• How the document is displayed
• Data validation rules
• Links to controllers and workflows

Every table in the database corresponds to a DocType unless it is a Single DocType.

In simple terms:

A DocType is both your database schema and your form definition.

2. How DocTypes Work Internally (v15 Architecture)

When you create a DocType, Frappe automatically generates:

Database Table

tab<DocType Name>
For example:

DocType: Customer → Table: tabCustomer

JSON Metadata File

Stored in:

/your_app/your_app/doctype/<your_doctype>/<your_doctype>.json

Python Controller File

(optional)

/your_app/your_app/doctype/<your_doctype>/<your_doctype>.py

JavaScript Client Script File

(optional)

/your_app/your_app/doctype/<your_doctype>/<your_doctype>.js

Form Template (HTML)

(optional for custom UI)

DocTypes form the bridge between database storage, UI rendering, API access, and business logic.

3. Types of DocTypes in Frappe v15

Frappe supports multiple DocType types, each serving a different purpose.

3.1 Standard DocType (Most common)

• Creates a database table
• Stores records as rows
• Most ERPNext DocTypes use this type

Examples:

• Customer
• Sales Invoice
• Item

3.2 Single DocType

A Single DocType stores only one record.

• No database table is created
• Values are stored in tabSingles table

Used for Settings, Configurations, and System Setup.

Examples:

• System Settings
• Website Settings
• Print Settings

3.3 Child Table DocType

Used to store rows inside a parent document.

• Cannot exist independently
• No list view
• No standalone form view

Examples:

• Sales Invoice Item
• Purchase Order Item
• Contact Phone Number

Child tables are essential for line items and nested tables.

3.4 Tree DocType

Used for hierarchical structures.

Examples:

• Item Group
• Cost Center
• Department

Features:

• Tree view
• Parent-child relationships
• Nested categorization

3.5 Submittable DocType

Supports document workflow with statuses:

Draft → Submitted → Cancelled

Examples:

• Purchase Order
• Stock Entry
• Sales Invoice

These DocTypes maintain audit trails and enforce accounting/stock rules in ERPNext.

3.6 Table MultiSelect

Provides multi-selection of linked documents using a child table pattern.

Examples:

• Assign multiple territories
• Select allowed companies

4. DocType File Structure (v15)

A Frappe DocType consists of:

JSON Metadata

Defines:

• Fields
• Permissions
• Actions
• Field layout
• Search fields
• Is Tree / Is Child Table
• Workflow properties

Example JSON snippet from GitHub:

{
"doctype": "DocType",
"name": "Task",
"module": "Projects",
"fields": [
{
"fieldname": "subject",
"fieldtype": "Data",
"label": "Subject",
"reqd": 1
}
],
"permissions": [
{
"role": "System Manager",
"read": 1,
"write": 1,
"create": 1
}
]
}

Python Controller (.py)

Contains server-side logic:

• Validations
• Lifecycle events (validate, on_update, before_save)
• Business rules
• Custom server functions

Example:

import frappe
from frappe.model.document import Document
class Task(Document):
def validate(self):
if not self.subject:
frappe.throw("Subject is required.")

JavaScript Form Script (.js)

Contains client-side logic:

• Field triggers
• Child table modifications
• Async server calls
• Dynamic UI behavior

Example:
frappe.ui.form.on("Task", {
refresh(frm) {
frm.add_custom_button("Hello", () => {
frappe.msgprint("Hello from JS!");
});
}
});

5. DocType Fields (DocField Types in v15)

Some important field types:

Every field is represented as a DocField in JSON metadata.

6. Document Lifecycle

All DocTypes follow the same lifecycle:

1. Creation
Document is inserted into the database (insert event)
 2. Validation
Server validates fields (validate event)
3. Save
Document is stored (before_save, after_save)
4. Submit (if submittable)
Document is locked for auditing (on_submit)
5. Cancel
Document is cancelled (on_cancel)
6. Amend
Creates a new version with reference to original

Developers can hook into every step using:

• DocType Python controller
• Hooks
• Form scripts

7. How DocTypes Appear in the UI

DocTypes automatically generate:

• List View
• Form View
• Report View
• Kanban View (optional)
• Calendar View (optional)
• Dashboard (if configured)

You can customize:

• Filters
• Sorting
• Columns
• Form layout (Sections, Columns, Tabs)

8. API Access — DocTypes Expose REST API Automatically

Each DocType gets automatic REST endpoints:

Create
POST /api/resource/Task

Read
GET /api/resource/Task/TASK-0001

List
GET /api/resource/Task

Update
PUT /api/resource/Task/TASK-0001

Delete
DELETE /api/resource/Task/TASK-0001

No extra code is needed.

9. Best Practices for Creating DocTypes in Frappe v15

1. Use naming series for business documents
(SINV-#####, PO-#####)

2. Keep fieldnames lowercase & no spaces
Use: customer_name
Not: Customer Name

3. Use correct fieldtypes
Avoid storing large text in Data fields.

4. Avoid custom scripts for server logic
Use Python controller instead.

5. Break complex DocTypes into child tables
Improves maintainability.

6. Never modify ERPNext core DocTypes
Override using hooks.

10. Common Errors & Troubleshooting

Conclusion

DocTypes are the heart of the Frappe Framework.
They define the schema, behavior, UI, permissions, and business rules of every document in ERPNext and Frappe apps. Understanding DocTypes is essential for building reliable, scalable, and maintainable applications in Frappe v15.