DocTypes
A DocType is Frappe's core model — like a database table, but with a schema, permissions, lifecycle hooks, and a generated UI.
What a DocType has
| Property |
Purpose |
| Name |
Singular form by convention (Sales Invoice, not Sales Invoices) |
| Module |
Which app/module it belongs to |
| Fields |
Columns — each has a type, label, and properties (see Field Types below) |
| Permissions |
Per-role access rules |
| Naming |
How new records get their primary key (Naming Series, hash, by-field) |
| Workflow |
Optional state machine |
Types of DocType
| Type |
Use |
| Document |
Has a DB table; users create many records |
| Single |
One record only — for settings (System Settings, Email Settings) |
| Child Table |
Embedded inside a parent — Sales Invoice Item lives in Sales Invoice |
| Submittable |
Has a Submit action; submitted records are immutable, changes require Cancel + Amend |
Standard vs Custom
| Type |
Origin |
| Standard |
Defined by an app — shipped with code in <app>/<module>/doctype/ |
| Custom |
Created in the Desk by an admin — stored in the database |
For one-off needs, a Custom DocType is fast. For reusable models across multiple sites, write a Frappe app. See Developers.
Naming conventions
- DocTypes are singular:
Sales Invoice, not Sales Invoices
- Field names are snake_case:
customer_name, posting_date
- Use Title Case in labels (what users see) and snake_case in fieldnames (what code uses)
Field Types
When defining a DocType, every field has a type that controls storage and rendering.
Text & content
| Type |
Storage |
Use |
| Data |
varchar(140) |
Short strings — names, codes |
| Small Text |
text |
Up to ~64KB |
| Long Text |
longtext |
Up to 4GB — articles, content |
| Text Editor |
longtext |
Rich HTML editing |
| Code |
longtext |
Code with syntax highlighting |
| Markdown Editor |
longtext |
Markdown with preview |
| HTML Editor |
longtext |
Direct HTML editing |
Numbers
| Type |
Storage |
Use |
| Int |
int |
Whole numbers |
| Float |
float |
Floating-point |
| Currency |
decimal(18,6) |
Monetary — locale-formatted |
| Percent |
float |
Shown with % suffix |
Dates
| Type |
Format |
| Date |
YYYY-MM-DD |
| Time |
HH:MM:SS |
| Datetime |
YYYY-MM-DD HH:MM:SS |
| Duration |
Hours/minutes/seconds — interval |
Selection & links
| Type |
Use |
| Select |
Drop-down with a fixed list of options |
| Link |
Link to another DocType — autocomplete |
| Dynamic Link |
Link where the target DocType is itself a field |
| Table |
Child table — embedded list of records |
| Table MultiSelect |
Multi-select from another DocType |
| Autocomplete |
Free text with suggestions |
| Type |
Use |
| Attach |
File link — stores URL |
| Attach Image |
Same with image preview |
| Color |
Color picker — hex value |
| Signature |
Drawing canvas, stored as image |
Layout
| Type |
Use |
| Section Break |
Visual grouping |
| Column Break |
New column in current section |
| Tab Break |
Top-level tab |
| Fold |
Collapsible group |
| HTML |
Static HTML in the form |
| Heading |
Visual heading |
Special
| Type |
Use |
| Check |
Boolean — 0 or 1 |
| Password |
Encrypted at rest |
| JSON |
Stores valid JSON; validated on save |
| Geolocation |
Map picker |
| Rating |
Star rating widget |
| Read Only |
Pure-display, no input |
| Barcode |
Renders barcode from value |
