frappe-syntax-doctypes

DocType JSON の設計

DocType は、すべての Frappe アプリケーションの基盤です。DocType はデータモデル（データベーススキーマ）とビュー（フォームレイアウト）の両方を定義します。コントローラーのロジックを書く前に、必ず DocType を設計してください。

クイックリファレンス

DocType JSON のトップレベルプロパティ

プロパティ	型	用途
name	str	DocType 識別子（単数形。例："Sales Invoice"）
module	str	この DocType が属するアプリのモジュール
is_submittable	bool	Draft -> Submitted -> Cancelled のワークフローを有効にします
is_tree	bool	NestedSet の階層構造（lft/rgt 列）を有効にします
is_virtual	bool	データベーステーブルを持たず、カスタムバックエンドからデータを取得します
issingle	bool	単一インスタンスの設定ドキュメント
istable	bool	子テーブル DocType（親に埋め込まれます）
is_calendar_and_gantt	bool	カレンダー／ガントチャートビューを有効にします
track_changes	bool	保存するたびにバージョン履歴を記録します
track_seen	bool	ドキュメントを閲覧したユーザーを記録します
track_views	bool	ドキュメントの閲覧総数をカウントします
allow_rename	bool	作成後の名前変更を許可します
allow_copy	bool	「Duplicate」アクションを有効にします
allow_import	bool	この DocType のデータインポートを有効にします
naming_rule	str	名前付け方法の選択（「Naming」セクションを参照）
autoname	str	名前付けパターンの文字列
title_field	str	表示タイトルとして使うフィールド
search_fields	str	検索結果に使うフィールド（カンマ区切り）
show_title_field_in_link	bool	Link フィールドで名前の代わりにタイトルを表示します
image_field	str	アバター表示用の画像を格納するフィールド
sort_field	str	デフォルトの並べ替え列
sort_order	str	"ASC" または "DESC"
default_print_format	str	Print Format の名前
max_attachments	int	添付ファイルの上限

一般的な Fieldtype（クイック参照）

Fieldtype	格納内容	DB 列
Data	最大140文字のテキスト	VARCHAR(140)
Link	別の DocType への参照	VARCHAR(140)
Dynamic Link	任意の DocType への参照	VARCHAR(140)
Select	選択肢から1つ選択	VARCHAR(140)
Table	子テーブルの行	別テーブル
Table MultiSelect	複数選択リンクの行	別テーブル
Check	ブール値 0/1	TINYINT
Int	整数	INT
Float	小数（小数点以下9桁）	DECIMAL
Currency	金額（小数点以下6桁）	DECIMAL
Date	日付	DATE
Datetime	日付と時刻	DATETIME
Text Editor	リッチテキスト（HTML）	LONGTEXT
Attach	ファイル参照	VARCHAR(140)
Small Text	短い複数行テキスト	TEXT
Long Text	文字数制限のないテキスト	LONGTEXT

35種類以上のすべてのタイプを網羅した Fieldtype の完全なリファレンス：references/fieldtypes.md

必須のフィールドプロパティ

プロパティ	型	用途
reqd	bool	フィールドを必須にします
unique	bool	データベースの UNIQUE 制約
search_index	bool	クエリを高速化するデータベース INDEX
in_list_view	bool	リストビューの列に表示します
in_standard_filter	bool	リストビューのフィルターとして表示します
in_preview	bool	ドキュメントのプレビューに表示します
allow_on_submit	bool	送信後も編集できます
read_only	bool	ユーザーによる編集を不可にします
hidden	bool	フォームに表示しません
depends_on	str	表示条件（例：eval:doc.status=="Active"）
mandatory_depends_on	str	条件付きで必須にします
read_only_depends_on	str	条件付きで読み取り専用にします
fetch_from	str	リンク先のドキュメントから自動入力します（例：customer.customer_name）
fetch_if_empty	bool	フィールドが空の場合のみ取得します
options	str	Fieldtype 固有の値（DocType 名、選択肢など）
default	str	デフォルト値（__user、Today などに対応）
description	str	フィールドの下に表示するヘルプテキスト
collapsible	bool	セクションを折りたたんだ状態で開始します（Section Break のみ）

判断ツリー：どの DocType タイプを選ぶか？

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)

命名規則

DocType には必ず naming_rule を設定してください。パターンは autoname フィールドに指定します。

naming_rule の値	autoname パターン	出力例
ユーザー指定	(empty)	ユーザーが名前を手動で入力
自動採番	(empty)	1、2、3
フィールド名による	field:{fieldname}	そのフィールドの値
命名シリーズによる	naming_series:	INV-2024-00001（シリーズフィールドから取得）
式	PRE-.#####	PRE-00001、PRE-00002
式（旧形式）	{prefix}-{YYYY}-{#####}	INV-2024-00001
ランダム	hash	ランダムな10文字の文字列
UUID	(empty)	550e8400-e29b-...
スクリプトによる	(custom)	コントローラーの autoname() で決定

本番環境では自動採番を絶対に使用しないでください。レコードが削除されると欠番が発生します。代わりに式または命名シリーズを使用してください。

命名の詳細： references/naming.md

子テーブルの設計

子 DocType は istable=1 の DocType です。必ず親に属します。

親側 -- 次のフィールドを追加します。

• fieldtype：Table（または Table MultiSelect）
• options：子 DocType の名前

子レコードには次の値が自動的に設定されます。

• parent -- 親ドキュメントの名前
• parenttype -- 親の DocType
• parentfield -- 親の Table フィールドのフィールド名
• idx -- 行の順序（1から始まる）

# 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()

istable=1 なしで子 DocType を作成しないでください。Table フィールドで子ではない DocType を参照しないでください。

Table と Table MultiSelect の比較

項目	Table	Table MultiSelect
UI	「行を追加」ボタン付きの完全な編集可能グリッド	タグ形式の選択欄。「行を追加」なし
子 DocType	多数のフィールドを持つ完全な子 DocType	通常は Link フィールドのみ
用途	明細項目、詳細行	複数選択の参照

Single DocType（設定パターン）

issingle=1 を設定します。データは専用テーブルではなく、キーと値のペアとして tabSingles に保存されます。

# 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")

• Single DocType にはインスタンスが1つしかないため、リストビューがあると想定しないでください。
• アプリ全体の設定（API キー、デフォルト値、機能切り替え）には必ず使用してください。

Tree DocType（NestedSet）

is_tree=1 を設定します。Frappe は lft、rgt、parent_{doctype_fieldname}、old_parent 列を自動的に追加します。

• DocType JSON では必ず parent_field を定義してください（例：勘定科目表では parent_account）。
• NestedSet モデルは、サブツリーを効率的に検索するために lft／rgt の整数値を使用します。
• lft／rgt の値を手動で編集しないでください。破損した場合は frappe.utils.nestedset.rebuild_tree() を使用してください。

# 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

is_virtual=1 を設定します。データベーステーブルは作成されません。コントローラーで次のメソッドを必ず実装してください。

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

Virtual DocType のデータに frappe.db.* 呼び出しを使用しないでください。これはサイトのデータベースに対してのみ機能し、カスタムバックエンドには対応していません。

カスタマイズ API

Custom Fields（プログラムによる設定）

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（プログラムによる設定）

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")

カスタマイズの詳細： references/customization.md

データマスキング（v16+）

mask=1 が設定されたフィールドは、そのフィールドの permlevel で mask 権限を持たないユーザーには機密値を表示しません。サーバーはクライアントに送信する前に、値を XXXXXXXX のようなパターンに置き換えます。管理者には必ずマスクされていない値が表示されます。

{ "fieldname": "phone", "fieldtype": "Data", "options": "Phone", "mask": 1, "permlevel": 1 }

マスキングの詳細： references/data-masking.md

Python 型スタブ

Frappe は TypeExporter を介して、コントローラーファイル内の型注釈を自動生成します。フィールドには TYPE_CHECKING ガード内で DF.* 型が設定されます。

if TYPE_CHECKING:
    from frappe.types import DF
    customer: DF.Link
    items: DF.Table[SalesInvoiceItem]
    status: DF.Literal["Draft", "Submitted", "Paid"]

# begin: auto-generated types と # end: auto-generated types の間のコードは絶対に変更しないでください。

型スタブの詳細： references/type-stubs.md

重要なルール

1. DocType 名は必ず単数形にしてください（「Sales Invoices」ではなく「Sales Invoice」）。
2. DB テーブル名は tab が接頭辞に付くことを常に意識してください。DB テーブル名は tabSales Invoice です。
3. Data／Link／Select フィールドの値は、必ず 140 文字以内にしてください。
4. 頻繁にフィルターや get_list 呼び出しで使用するフィールドには、必ず search_index=1 を設定してください。
5. ユーザーが頻繁にフィルターするフィールドには、必ず in_standard_filter=1 を設定してください。
6. 合計を再計算しない場合、計算に影響する子テーブルのフィールドで allow_on_submit=1 を使用しないでください。
7. ユーザーによる編集を上書きする場合を除き、fetch_from と併せて必ず fetch_if_empty=1 を設定してください。
8. depends_on に生の Python を定義しないでください。eval:doc.fieldname == "value" 構文を使用してください。

関連項目

• references/fieldtypes.md -- フィールドタイプの完全なリファレンス
• references/naming.md -- すべての命名方法と例
• references/examples.md -- 実際の DocType JSON の例
• references/anti-patterns.md -- よくあるスキーマ設計上の誤り
• references/customization.md -- Custom Fields と Property Setter API
• references/data-masking.md -- プライバシー保護のためのフィールドレベルのデータマスキング（v16+）
• references/type-stubs.md -- Python の型ヒント、DF 型、TypeExporter