Child DocTypes in Frappe Framework (v15)
Complete Technical Documentation
1. Introduction & Context
A Child DocType in Frappe Framework is a special document type that cannot exist on its own. Instead, it is always linked to a Parent DocType through a Table fieldtype. Child DocTypes allow developers to structure repeatable or multi-row data inside a form—for example, Items in a Sales Invoice, Tasks in a Project, or Components in a BOM.
Child DocTypes are essential for building relational data structures in ERPNext and custom Frappe apps.
2. What Is a Child DocType in Frappe?
A Child DocType is a non-standalone DocType used to store multiple rows of related data inside a parent document.
Key Characteristics
- Cannot be created independently (no “New” button).
- Always displayed as a Table Grid inside the parent.
- Linked using the Table or Table MultiSelect fieldtype.
- The system automatically generates a field named parentfield, parenttype, and parent.
3. When Should You Use a Child DocType?
Use a Child DocType when you need:
Multiple rows of related data
Example: Sales Invoice Items.
Structured repeated information
Example: Contact numbers in an Address.
Nested records linked to a parent
Example: Project Tasks inside a Project.
Editable table/grid inside a form
Example: BOM Components – each row is editable.
4. How Child DocTypes Work Internally
Each row in a Child DocType includes hidden metadata fields:
| Field | Purpose |
| parent | Name of parent document |
| parenttype | Parent DocType name |
| parentfield | Parent DocField (Table field) storing this child |
| idx | Row index |
These fields ensure proper mapping and ordering of child rows.
5. Creating a Child DocType in Frappe v15
Step 1 — Create a New DocType
- Go to: Model → DocType → New
- Enter DocType Name (e.g., Sales Invoice Item)
Step 2 — Set “Is Child Table”
Under Settings:
- Enable Is Child Table
This disables standalone features such as:
- Permissions setup
- Naming series
- “New” button creation
Step 3 — Add Fields
Each field becomes a column in the child table.
Example Fields:
- Item Code (Link)
- Description (Data)
- Qty (Float)
- Rate (Currency)
- Amount (Currency)
6. Linking a Child DocType to a Parent DocType
Add a Table field in the Parent DocType:
| Property | Value |
| Label | Items |
| Fieldtype | Table |
| Options | Name of Child DocType |
| Fieldname | items |
Example (Parent → Sales Invoice):
{
"label": "Items",
"fieldname": "items",
"fieldtype": "Table",
"options": "Sales Invoice Item"
}
This creates a grid table inside the Sales Invoice form.
7. Code Example — Accessing Child Table Rows in Python
Inside a controller (e.g., validate()):
for row in self.items:
frappe.logger().info(f"Item: {row.item_code}, Qty: {row.qty}")
Updating Child Rows
for row in self.items:
row.amount = row.qty * row.rate
8. Common Use Cases for Child DocTypes
Child DocTypes power most tabular data across ERPNext.
| Module | Example Parent | Example Child DocType |
| Buying | Purchase Order | Purchase Order Item |
| Selling | Sales Invoice | Sales Invoice Item |
| Projects | Project | Project Task |
| HRMS | Employee | Employee Shift Detail |
| Manufacturing | BOM | BOM Item |
9. Best Practices for Child DocTypes
Keep Child DocTypes lightweight
Avoid unnecessary heavy logic in child tables.
Use naming as “Normal”
No naming series required.
Never manually set parent, parenttype, parentfield
Frappe manages these automatically.
Use fieldnames, not labels, in scripts
Example:
self.items[0].qty
10. Advanced Concepts
Table MultiSelect Child DocType
Allows selecting multiple link values with additional child fields.
Example: Selecting multiple email recipients with metadata.
Child DocType Permissions
Child DocTypes do not have permissions.
Parent DocType permissions apply automatically.
Fetching Child Records via REST API
GET Child Table Records
GET /api/resource/Sales Invoice/SINV-0001
Response includes:
"items": [
{
"item_code": "ITEM-001",
"qty": 5,
"rate": 100
}
]
11. Troubleshooting
Child Table not appearing?
Check:
- Fieldtype must be Table
- Options must match Child DocType name
- Child DocType must have “Is Child Table” enabled
Rows not saving?
Likely due to:
- Missing required fields
- Unhandled validation exceptions in child table
12. Cross-References (Internal Documentation Links)
Useful related Frappe topics:
- DocField
- DocType Permissions
- Naming in DocTypes
- Fieldtypes Overview
- Controllers & Hooks
Conclusion
Child DocTypes are foundational to how ERPNext and Frappe represent structured, multi-row datasets within a parent document. They provide flexibility, relational integrity, and a clean UI through table grids. Mastering Child DocTypes is crucial for building real-world ERP workflows, custom apps, and complex business logic in Frappe Framework v15.
