DocType JSON Design

DocTypes are the foundation of every Frappe application. A DocType defines both the data model (database schema) and the view (form layout). ALWAYS design DocTypes before writing any controller logic.

Quick Reference

DocType JSON Top-Level Properties

Common Fieldtypes (Quick Lookup)

Full fieldtype reference with all 35+ types: references/fieldtypes.md

Essential Field Properties

Decision Tree: Which DocType Type?

Need to store data?
├─ YES: Need multiple records?
│  ├─ YES: Need submit/cancel workflow?
│  │  ├─ YES → Standard DocType + is_submittable=1
│  │  └─ NO: Need hierarchy/tree?
│  │     ├─ YES → Tree DocType (is_tree=1)
│  │     └─ NO: Embedded in parent?
│  │        ├─ YES → Child DocType (istable=1)
│  │        └─ NO → Standard DocType
│  └─ NO: Single config/settings → Single DocType (issingle=1)
└─ NO: Data from external source → Virtual DocType (is_virtual=1)

Naming Rules

ALWAYS set naming_rule on the DocType. The autoname field holds the pattern.

NEVER use Autoincrement in production -- gaps appear when records are deleted. Use Expression or Naming Series instead.

Full naming reference: references/naming.md

Child Table Design

A Child DocType is a DocType with istable=1. It ALWAYS belongs to a parent.

Parent side -- add a field with:

• fieldtype: Table (or Table MultiSelect)
• options: Child DocType name

Child records automatically get:

• parent -- name of the parent document
• parenttype -- DocType of the parent
• parentfield -- fieldname of the Table field in parent
• idx -- row order (1-based)

# Adding child rows programmatically
doc = frappe.get_doc("Sales Invoice", "INV-001")
doc.append("items", {
    "item_code": "ITEM-001",
    "qty": 5,
    "rate": 100.0
})
doc.save()

NEVER create a Child DocType without istable=1. NEVER reference a non-child DocType in a Table field.

Table vs Table MultiSelect

Single DocType (Settings Pattern)

Set issingle=1. Data is stored in tabSingles as key-value pairs, NOT in a dedicated table.

# Access Single DocType
settings = frappe.get_single("My Settings")
value = settings.some_field

# Or directly
value = frappe.db.get_single_value("My Settings", "some_field")

• NEVER expect a list view for Single DocTypes -- they have exactly one instance.
• ALWAYS use for app-wide configuration (API keys, default values, feature toggles).

Tree DocType (NestedSet)

Set is_tree=1. Frappe adds lft, rgt, parent_{doctype_fieldname}, old_parent columns automatically.

• ALWAYS define a parent_field in the DocType JSON (e.g. parent_account for Chart of Accounts).
• The NestedSet model uses lft/rgt integers for efficient subtree queries.
• NEVER manually edit lft/rgt values. Use frappe.utils.nestedset.rebuild_tree() if corrupted.

# Get all descendants
descendants = frappe.get_all("Account",
    filters={"lft": [">", node.lft], "rgt": ["<", node.rgt]})

# Get ancestors (path to root)
ancestors = frappe.get_all("Account",
    filters={"lft": ["<", node.lft], "rgt": [">", node.rgt]},
    order_by="lft asc")

Virtual DocType

Set is_virtual=1. No database table is created. ALWAYS implement these controller methods:

class MyVirtualDoc(Document):
    def db_insert(self, *args, **kwargs):
        # Persist to your custom backend
        pass

    def load_from_db(self):
        # Load document data from your source
        pass

    def db_update(self, *args, **kwargs):
        # Update in your custom backend
        pass

    def delete(self):
        # Remove from your custom backend
        pass

    @staticmethod
    def get_list(args):
        # Return list of documents
        pass

    @staticmethod
    def get_count(args):
        # Return total count
        pass

    @staticmethod
    def get_stats(args):
        # Return statistics
        pass

NEVER use frappe.db.* calls for Virtual DocType data -- they only work with the site database, not your custom backend.

Customization APIs

Custom Fields (Programmatic)

from frappe.custom.doctype.custom_field.custom_field import create_custom_fields

# Dict format: {DocType: [field_dicts]}
create_custom_fields({
    "Sales Invoice": [
        dict(fieldname="custom_tracking", label="Tracking ID",
             fieldtype="Data", insert_after="naming_series")
    ],
    "Purchase Order": [
        dict(fieldname="custom_vendor_ref", label="Vendor Ref",
             fieldtype="Data", insert_after="supplier")
    ]
}, update=True)

Property Setter (Programmatic)

from frappe.custom.doctype.property_setter.property_setter import make_property_setter

# Change a field property on an existing DocType
make_property_setter("Sales Invoice", "customer", "reqd", 1, "Check")
make_property_setter("Sales Invoice", "posting_date", "default", "Today", "Text")

Full customization reference: references/customization.md

Data Masking (v16+)

Fields with mask=1 hide sensitive values from users without mask permission at the field's permlevel. The server replaces values with patterns like XXXXXXXX before sending to the client. Administrator ALWAYS sees unmasked values.

{ "fieldname": "phone", "fieldtype": "Data", "options": "Phone", "mask": 1, "permlevel": 1 }

Full masking reference: references/data-masking.md

Python Type Stubs

Frappe auto-generates type annotations in controller files via TypeExporter. Fields get DF.* types inside a TYPE_CHECKING guard:

if TYPE_CHECKING:
    from frappe.types import DF
    customer: DF.Link
    items: DF.Table[SalesInvoiceItem]
    status: DF.Literal["Draft", "Submitted", "Paid"]

NEVER modify code between # begin: auto-generated types and # end: auto-generated types.

Full type stubs reference: references/type-stubs.md

Critical Rules

1. ALWAYS name DocTypes in singular form ("Sales Invoice", not "Sales Invoices").
2. ALWAYS use the tab prefix mentally -- the DB table is tabSales Invoice.
3. NEVER exceed 140 characters for Data/Link/Select field values.
4. ALWAYS set search_index=1 on fields used in frequent filters or get_list calls.
5. ALWAYS set in_standard_filter=1 on fields users frequently filter by.
6. NEVER use allow_on_submit=1 on child table fields that affect calculations without recalculating totals.
7. ALWAYS set fetch_if_empty=1 alongside fetch_from unless you want to overwrite user edits.
8. NEVER define depends_on with raw Python -- use eval:doc.fieldname == "value" syntax.

See Also

• references/fieldtypes.md -- Complete fieldtype reference
• references/naming.md -- All naming methods with examples
• references/examples.md -- Real DocType JSON examples
• references/anti-patterns.md -- Common schema design mistakes
• references/customization.md -- Custom Fields and Property Setter APIs
• references/data-masking.md -- Field-level data masking for privacy (v16+)
• references/type-stubs.md -- Python type hints, DF types, TypeExporter