name: frappe-syntax-doctypes description: > Use when creating or modifying DocType JSON definitions, choosing fieldtypes, configuring naming rules, adding child tables, or setting up tree structures. Prevents invalid DocType configurations from wrong fieldtype choices, broken naming rules, and misconfigured child table links. Covers DocType JSON schema, all fieldtypes and their properties, autoname/naming_rule patterns, child table (Table fieldtype), tree DocTypes, virtual DocTypes, Single DocTypes. Keywords: DocType, fieldtype, naming_rule, autoname, child table, tree, virtual DocType, Single, JSON definition, Custom Field, Customize Form, add field without code, hierarchy, tree view, field types list.. license: MIT compatibility: "Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16." metadata: author: OpenAEC-Foundation version: "2.0"

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