/frappe-syntax-doctypes

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

| Property | Type | Purpose | |----------|------|---------| | `name` | str | DocType identifier (singular, e.g. "Sales Invoice") | | `module` | str | App module this DocType belongs to | | `is_submittable` | bool | Enables Draft -> Submitted -> Cancelled workflow | | `is_tree` | bool | Enables NestedSet hierarchy (lft/rgt columns) | | `is_virtual` | bool | No database table; data from custom backend | | `issingle` | bool | Single-instance settings document | | `istable` | bool | Child table DocType (embedded in parent) | | `is_calendar_and_gantt` | bool | Enables calendar/gantt views | | `track_changes` | bool | Stores version history on every save | | `track_seen` | bool | Tracks which users viewed the document | | `track_views` | bool | Counts total document views | | `allow_rename` | bool | Permits renaming after creation | | `allow_copy` | bool | Enables "Duplicate" action | | `allow_import` | bool | Enables Data Import for this DocType | | `naming_rule` | str | Naming method selector (see Naming section) | | `autoname` | str | Naming pattern string | | `title_field` | str | Field used as display title | | `search_fields` | str | Comma-separated fields for search results | | `show_title_field_in_link` | bool | Display title instead of name in Link fields | | `image_field` | str | Field containing image for avatar display | | `sort_field` | str | Default sort column | | `sort_order` | str | "ASC" or "DESC" | | `default_print_format` | str | Print Format name | | `max_attachments` | int | Attachment limit |

Common Fieldtypes (Quick Lookup)

| Fieldtype | Stores | DB Column | |-----------|--------|-----------| | Data | Text up to 140 chars | VARCHAR(140) | | Link | Reference to another DocType | VARCHAR(140) | | Dynamic Link | Reference to any DocType | VARCHAR(140) | | Select | Single choice from options | VARCHAR(140) | | Table | Child table rows | Separate table | | Table MultiSelect | Multi-select link rows | Separate table | | Check | Boolean 0/1 | TINYINT | | Int | Whole number | INT | | Float | Decimal (9 places) | DECIMAL | | Currency | Money value (6 decimals) | DECIMAL | | Date | Calendar date | DATE | | Datetime | Date + time | DATETIME | | Text Editor | Rich text (HTML) | LONGTEXT | | Attach | File reference | VARCHAR(140) | | Small Text | Short multi-line text | TEXT | | Long Text | Unlimited text | LONGTEXT |

> Full fieldtype reference with all 35+ types: [references/fieldtypes.md](references/fieldtypes.md)

Essential Field Properties

| Property | Type | Purpose | |----------|------|---------| | `reqd` | bool | Field is mandatory | | `unique` | bool | Database UNIQUE constraint | | `search_index` | bool | Database INDEX for faster queries | | `in_list_view` | bool | Show in list view columns | | `in_standard_filter` | bool | Show as filter in list view | | `in_preview` | bool | Show in document preview | | `allow_on_submit` | bool | Editable after submission | | `read_only` | bool | Not editable by user | | `hidden` | bool | Not visible on form | | `depends_on` | str | Visibility condition (e.g. `eval:doc.status=="Active"`) | | `mandatory_depends_on` | str | Conditional mandatory | | `read_only_depends_on` | str | Conditional read-only | | `fetch_from` | str | Auto-populate from linked doc (e.g. `customer.customer_name`) | | `fetch_if_empty` | bool | Only fetch when field is empty | | `options` | str | Fieldtype-specific (DocType name, select options, etc.) | | `default` | str | Default value (supports `__user`, `Today`, etc.) | | `description` | str | Help text below field | | `collapsible` | bool | Section starts collapsed (Section Break only) |

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.

| naming_rule Value | autoname Pattern | Example Output | |-------------------|------------------|----------------| | Set by User | _(empty)_ | User types name manually | | Autoincrement | _(empty)_ | `1`, `2`, `3` | | By Fieldname | `field:{fieldname}` | Value of that field | | By Naming Series | `naming_series:` | `INV-2024-00001` (from series field) | | Expression | `PRE-.#####` | `PRE-00001`, `PRE-00002` | | Expression (Old Style) | `{prefix}-{YYYY}-{#####}` | `INV-2024-00001` | | Random | `hash` | Random 10-char string | | UUID | _(empty)_ | `550e8400-e29b-...` |