frappe-syntax-doctypes

# 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-...` |
| By Script | _(custom)_ | Controller `autoname()` decides |

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

> Full naming reference: [references/naming.md](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)

```python
# 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(