Single Type DocType in Frappe Framework v15
Introduction & Context
A Single Type DocType in Frappe Framework v15 is designed to store exactly one record for the entire system. Instead of managing multiple documents, Single DocTypes act as centralized configuration or settings pages, making them ideal for global preferences, feature toggles, and system-wide parameters.
This documentation explains what Single DocTypes are, when to use them, and how they behave internally—strictly aligned with Frappe Framework Version 15.
What Is a Single Type DocType?
A Single DocType is a special DocType where:
- Only one record exists per site
- Data is stored as key-value pairs
- No naming series or document list is required
- The form behaves like a settings page
It is commonly used for system configuration, not transactional data.
How Single DocTypes Differ from Standard DocTypes
| Aspect | Standard DocType | Single DocType |
| Number of Records | Multiple | One only |
| Database Table | Dedicated table | Stored in tabSingles |
| Naming Series | Required | Not required |
| List View | Yes | No |
| Use Case | Transactions | Configuration |
When Should You Use a Single DocType?
Use a Single DocType when:
- You need global settings
- Data applies to the entire site
- Only one configuration record makes sense
- You want a clean, form-based settings UI
Common Examples
- Company-wide preferences
- Integration credentials
- Feature flags
- Default values and thresholds
How Single DocTypes Are Stored Internally
In Frappe v15, Single DocType values are stored in the database table:
tabSingles
Each field is saved as a (doctype, field, value) entry. This design allows flexible storage without schema duplication.
How to Create a Single Type DocType
Step 1: Create a New DocType
- Navigate to DocType List
- Click New
- Enter a DocType name
Step 2: Enable “Is Single”
- Check the Is Single option
- Save the DocType
Once enabled, Frappe automatically enforces single-record behavior.
How Users Interact with Single DocTypes
Users experience Single DocTypes as:
- A direct form view
- No list or multiple records
- Immediate access from the module
This reduces cognitive load and improves usability for administrators.
Accessing Single DocType Values in Code
Reading Values
Single DocType values are retrieved using Frappe’s API for singles. Internally, Frappe resolves values from tabSingles and returns them as a dictionary-like structure.
Writing Values
When a user saves the form, Frappe updates the existing single record rather than creating a new document.
No custom logic is required to enforce uniqueness.
Best Practices for Single DocTypes
- Keep fields simple and minimal
- Avoid transactional or user-specific data
- Group related settings logically
- Use clear field labels and descriptions
- Add validations only when necessary
Advanced Usage Scenarios
Configuration-Driven Features
Single DocTypes are often used to:
- Enable or disable modules
- Control automation thresholds
- Store API keys or endpoints
- Define default operational rules
Integration Patterns
Single DocTypes integrate seamlessly with:
- Background jobs
- Scheduled tasks
- REST API logic
- Custom scripts and hooks
They provide a single source of truth for system-wide logic.
Troubleshooting Common Issues
“Why can’t I create multiple records?”
This is expected behavior. Single DocTypes are restricted by design.
“Why is there no list view?”
Single DocTypes skip list views intentionally to avoid confusion.
“Where is the data stored?”
All values are stored in the tabSingles table, not a custom DocType table.
Industry Relevance & Use Case Mapping
Single DocTypes are widely used in:
- ERP systems – Global accounting or tax settings
- Manufacturing – Plant-wide configuration
- Healthcare – Compliance or system preferences
- Real Estate – Project-level default rules
They simplify administration and reduce data duplication.
Target Audience
- ERPNext Developers
- Frappe Framework Developers
- System Administrators
- ERP Consultants
Summary: Why Single DocTypes Matter
Single Type DocTypes in Frappe Framework v15 provide a clean, reliable, and scalable way to manage global configuration. By design, they eliminate duplication, simplify user experience, and ensure consistent system behavior—making them an essential building block in ERPNext and custom Frappe apps.
