Frappe_Claude_Skill_Package frappe-syntax-doctypes

install

source · Clone the upstream repo

git clone https://github.com/OpenAEC-Foundation/Frappe_Claude_Skill_Package

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/OpenAEC-Foundation/Frappe_Claude_Skill_Package "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/source/syntax/frappe-syntax-doctypes" ~/.claude/skills/openaec-foundation-frappe-claude-skill-package-frappe-syntax-doctypes && rm -rf "$T"

manifest: skills/source/syntax/frappe-syntax-doctypes/SKILL.md

source content

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

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

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

Aspect	Table	Table MultiSelect
UI	Full editable grid with "Add Row"	Tag-style picker, no "Add Row"
Child DocType	Full child with many fields	Typically 1 Link field only
Use case	Line items, detail rows	Multi-select references

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

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