netbox-custom-objects

NetBox Custom Objects

Custom Objects に関する知識は古くなっている可能性があります。 フィールドタイプ、リレーションシップのオプション、ブランチの動作、API の仕様はプラグインのリリースごとに変わります（0.5 → 0.7 ではポリモーフィックフィールド、ポータブルスキーマ、ブランチ、GraphQL、コンフィグコンテキスト、coordinates、display_expression が追加されました）。事前学習済みの知識よりも、情報を取得して確認することを優先してください。

情報の取得元

情報源	URL / 方法	用途
Custom Objects のドキュメント	https://netboxlabs.com/docs/custom-objects/	概要、ワークフロー、コンフィグコンテキスト、コンフィグテンプレート
フィールド属性	https://netboxlabs.com/docs/custom-objects/field-attributes/	タイプごとの属性
REST API	https://netboxlabs.com/docs/custom-objects/rest-api/	エンドポイント、ペイロード
GraphQL	https://netboxlabs.com/docs/custom-objects/graphql/	クエリのフィールド名、型のマッピング
ブランチ	https://netboxlabs.com/docs/custom-objects/branching/	バージョン要件、ブランチの動作
ポータブルスキーマ	https://netboxlabs.com/docs/custom-objects/portable-schema/	エクスポート／プレビュー／適用
リリースノート	https://github.com/netboxlabs/netbox-custom-objects/blob/main/docs/releases.md	インストール済みバージョンでの変更点
NetBox MCP サーバー	設定されている場合 — 既存のカスタムオブジェクトタイプとインスタンスを一覧表示	スキーマの検出
NetBox Platform MCP	設定されている場合 — カスタムオブジェクトに対する完全な CRUD	タイプの作成、インスタンスの管理

最初に：接続とバージョンを確認

# Plugin installed? (404 = not installed; 403 = token lacks custom_objects permissions)
curl -s -H "Authorization: Bearer $NETBOX_TOKEN" "$NETBOX_URL/api/plugins/custom-objects/custom-object-types/" | python -m json.tool

# Which plugin version? (core /api/status/ lists installed plugins and versions)
curl -s -H "Authorization: Bearer $NETBOX_TOKEN" "$NETBOX_URL/api/status/" | python -c "import sys,json; d=json.load(sys.stdin); print(d['netbox-version'], d['plugins'].get('netbox_custom_objects'))"

バージョンに関する注意： このスキルは、NetBox 4.5.2 から 4.7.x に対応するプラグイン v0.7.x（最新は v0.7.0、2026-09-15）を対象としています。プラグインのバージョンによって動作が異なる箇所には、インラインでタグ（v0.5+、v0.6+、v0.6.1+、v0.7+）を付けています。NetBox 4.7 が必要な機能には NetBox 4.7+ のタグを付けています。必ず最初にインストール済みのバージョンを確認してください。ブランチモデルは 0.6.0 で全面的に変更されました。

---

コードを書かずに NetBox のデータモデルを拡張できます。Custom Objects を使うと、管理者は UI、REST API、GraphQL（読み取り）、またはポータブルスキーマドキュメントを通じて、型付きフィールド、検証ルール、リレーションシップを備えた新しいオブジェクトタイプを定義できます。

このスキルを使用する場面

• NetBox に新しいオブジェクトタイプ（例：DHCP スコープ、契約、アプリケーション）を作成する
• カスタムオブジェクトタイプにフィールド（テキスト、数値、オブジェクト参照、座標など）を追加する
• REST、GraphQL、または pynetbox を介してカスタムオブジェクトを作成または利用するインテグレーションを構築する
• CI/CD でポータブルスキーマのエクスポート／プレビュー／適用を使用して、カスタムオブジェクトタイプのプロビジョニングを自動化する
• リンクされたオブジェクトをクエリする（コアオブジェクトからカスタムオブジェクトを逆引きする）
• ブランチ、コンフィグコンテキスト、またはデバイスコンフィグテンプレートでカスタムオブジェクトを使用する

クイックリファレンス

基本概念

概念	説明
カスタムオブジェクトタイプ（COT）	新しいモデル定義です。データベーステーブルに似ています。name（内部名）、slug（URL／API パス）、表示名、フィールドを持ちます。
カスタムオブジェクトタイプフィールド（COTF）	COT の列です。型、検証、順序、グループ化を設定できます。
カスタムオブジェクト	COT のインスタンスです。テーブルの行に似ています。
プライマリフィールド	値がオブジェクトの表示名になる COTF です（デフォルト名は <Type> <id>）。
表示式 (v0.6.1+)	COT 上の Jinja2 テンプレート（display_expression）で、複数のフィールドから表示名を構成します。設定されている場合、プライマリフィールドより優先されます。
コンテキストフィールド	context: true が設定された COTF です。その値は、別のオブジェクトがこのオブジェクトを参照する場所、および REST の _context キーに表示されます。
グループ名	ナビゲーションサイドバー（COT の場合）またはフォーム内のフィールド（COTF の場合）で、関連する COT をまとめます。

API エンドポイント

エンドポイント	目的
/api/plugins/custom-objects/custom-object-types/	型定義の CRUD（?slug= フィルターが機能します。v0.5.2 以降）
/api/plugins/custom-objects/custom-object-type-fields/	フィールド定義の CRUD
/api/plugins/custom-objects/{slug}/	インスタンスの CRUD（型ごとに 1 つのエンドポイントがあり、slug をキーにします）
/api/plugins/custom-objects/linked-objects/	逆引き：指定したオブジェクトを参照するカスタムオブジェクト
/api/plugins/custom-objects/schema/preview/	ポータブルなスキーマドキュメントと稼働中の DB との差分を表示します（読み取り専用）
/api/plugins/custom-objects/schema/apply/	ポータブルなスキーマドキュメントを適用します（アトミック。COT への add+change が必要です）
/graphql/ (v0.6+)	custom_objects_<slug> / custom_objects_<slug>_list としてカスタムオブジェクトを読み取ります

フィールドタイプ（14 種類）

タイプ	説明	タイプ固有のオプション
text	短いテキスト	validation_regex
longtext	複数行のテキスト（テキストエリア）	validation_regex
integer	整数、64 ビット（v0.6+）	validation_minimum、validation_maximum
decimal	小数	validation_minimum、validation_maximum
boolean	真／偽	—（unique は使用できません）
date	ISO 8601 日付（YYYY-MM-DD）	—
datetime	ISO 8601 日時	—
url	URL と任意のリンクタイトル（v0.7+：REST では <name> と <name>_title を公開します）	validation_regex
json	任意の JSON	—
select	選択肢セットから 1 つ選択	choice_set（必須）
multiselect	選択肢セットから複数選択	choice_set（必須）
object	1 つのオブジェクトへの参照	app_label+model または is_polymorphic+related_object_types_input；related_object_filter、related_name、on_delete_behavior
multiobject	複数のオブジェクトへの参照	object と同じですが、on_delete_behavior は除きます。unique は使用できません
coordinates (v0.6+)	緯度／経度のペア。REST では <name>_latitude と <name>_longitude を公開します（両方指定するか、どちらも指定しません）	—（unique、default は使用できません）

リリースノートでは座標タイプを「location」と呼んでいますが、API の type 値は coordinates です。

v0.5.1 以降の変更点

バージョン	変更
0.5.2	ポリモーフィックフィールドで related_name が機能するようになりました（逆引きアクセサー）。COT リストで ?slug= フィルターが機能するようになりました。POST/PATCH のタグが保存されるようになりました。select フィールドに生のキーではなくラベルが表示されるようになりました。任意のオブジェクトフィールドで null が受け入れられるようになりました
0.6.0	ブランチ対応：COT、フィールド、インスタンスがブランチを認識するようになりました（NetBox ≥ 4.6.2、netbox-branching ≥ 1.0.4 が条件）。GraphQL 読み取りをサポート。設定コンテキストをサポート（config_context_enabled）。オブジェクト／multiobject フォームフィールドでクイック追加に対応。連絡先に対応。所有者（owner）に対応。64 ビット整数。coordinates タイプ
0.6.1	display_expression。NetBox 4.7+ の config-template アクセス（custom_objects.<name>、'<name>' | custom_objects）。一括編集の「Set null」。インスタンスフィルターの ?id= とルックアップサフィックス（__gt、__ic、…）を修正。NetBox 4.7 に対応
0.7.0	参照先のすべてのオブジェクトに「Custom Objects」関連タブを追加（権限でフィルタリング）。URL のリンクタイトル。スキーマのプレビュー／適用で YAML を受け入れ、返すようになりました。グローバル検索にコンテキストフィールドを表示

カスタムオブジェクトタイプの作成

ステップ 1：タイプを作成する

POST /api/plugins/custom-objects/custom-object-types/

{
  "name": "dhcp_scope",
  "slug": "dhcp-scopes",
  "description": "DHCP address scopes",
  "verbose_name": "DHCP Scope",
  "verbose_name_plural": "DHCP Scopes",
  "group_name": "IPAM Extensions",
  "version": "1.0.0",
  "display_expression": "{{ scope_name }}{% if vlan %} (VLAN {{ vlan }}){% endif %}",
  "config_context_enabled": false
}

タイプのプロパティ：

プロパティ	説明
name	内部名：^[a-z0-9]+(_[a-z0-9]+)*$ — 小文字、アンダースコアを使用し、先頭・末尾・連続したアンダースコアは不可です。一意である必要があります。設定テンプレートで使用されます。
slug	URL セーフな識別子です。REST パス、GraphQL フィールド名、CUSTOM_VALIDATORS のキー、COT 間の参照で使用されます。一意である必要があります。
verbose_name / verbose_name_plural	表示名です。デフォルトでは、タイトルケースにした name / verbose_name + "s" が使用されます。
group_name	任意です。このタイプをサイドバーでほかのタイプとグループ化します。
version	任意の PEP 440 形式の文字列です。ポータブルスキーマ機能で使用されます。
display_expression (v0.6.1+)	任意の Jinja2 テンプレートです。フィールド名を使ってフィールド値をレンダリングします。未定義のフィールドは空文字列としてレンダリングされます。レンダリングエラーが発生した場合は、通知なしでプライマリフィールドにフォールバックします。UI フォームでは Jinja 構文が検証されますが、REST API では検証されません。
config_context_enabled (v0.6+)	作成時のみ設定できます。 すべてのインスタンスに local_context_data と「Config Context」タブを追加します。後から切り替えることはできません（API は検証エラーを返します）。

ステップ 2：フィールドを追加する

POST /api/plugins/custom-objects/custom-object-type-fields/

{
  "custom_object_type": 1,
  "name": "scope_name",
  "label": "Scope Name",
  "type": "text",
  "required": true,
  "unique": true,
  "primary": true,
  "validation_regex": "^[a-zA-Z0-9_-]+$"
}

主なフィールドプロパティ：

プロパティ	用途	説明
primary	このフィールドの値をオブジェクトの表示名として使用します	タイプごとに 1 つ設定できます。COT の display_expression がこれより優先されます
context	オブジェクトが参照される場所で、この値を追加コンテキストとして表示します	REST では _context として表示されます。グローバル検索にも反映されます（v0.7+）
required	フィールドに値が必要です	作成時と更新時に（API と UI で）適用されます
unique	すべてのインスタンス間で値が一意である必要があります	boolean、multiobject、coordinates では使用できません
weight	表示順序（値が小さいほど上位）	デフォルト：100
group_name	フォームでの視覚的なグループ化	同じ group_name のフィールドはまとめて表示されます
search_weight	検索順位（100＝高、500＝中、1000＝低、0＝対象外）	デフォルト：500
filter_logic	loose（部分一致）、exact、disabled	デフォルト：loose。テキスト形式のフィールドの REST フィルターに適用されます
ui_visible / ui_editable	always/if-set/hidden および yes/no/hidden	非表示のフィールドも API 経由で書き込み可能です
default	デフォルト値。JSON として保存されます	REST： JSON 値をそのまま送信します（"default": "active"、"default": 86400、"default": true）。UI フォーム： JSON リテラルを入力します（文字列には引用符が必要です）。coordinates では使用できません。
is_cloneable	オブジェクトの複製時に含めます	デフォルト：false
deprecated、deprecated_since、scheduled_removal	移行の猶予期間中にフィールドを読み取り専用としてマークします	PEP 440 形式の文字列です。ポータブルスキーマで使用されます
schema_id	ポータブルスキーマで使用される読み取り専用の安定した ID	自動的に割り当てられます

ステップ 3：インスタンスを作成する

POST /api/plugins/custom-objects/dhcp-scopes/

{
  "scope_name": "office-floor-2",
  "ip_range": 5,
  "vlan": 100,
  "tags": [{"name": "production"}],
  "owner": 3
}

エンドポイントのパスには、COT の slug（name ではありません）を使用します。すべてのインスタンスには、id、url、display、owner (v0.6+、NetBox の所有権 — 使用しない場合は省略)、tags、created、last_updated が含まれます。また、タイプにコンテキストフィールドがある場合は _context が、設定コンテキストが有効な場合は local_context_data が含まれます。

オブジェクト参照フィールド

object フィールドと multiobject フィールドを使用して、NetBox のコアオブジェクト、プラグインモデル、またはほかのカスタムオブジェクトを参照します。

コアオブジェクトの参照

{
  "custom_object_type": 1,
  "name": "site",
  "label": "Site",
  "type": "object",
  "app_label": "dcim",
  "model": "site",
  "related_name": "dhcp_scopes",
  "on_delete_behavior": "protect"
}

よく使われる app_label.model の組み合わせ：dcim.device、dcim.site、dcim.rack、dcim.interface、ipam.prefix、ipam.ipaddress、ipam.vlan、ipam.iprange、tenancy.tenant、circuits.circuit、virtualization.virtualmachine。

• on_delete_behavior (v0.5+)：set_null（デフォルト）、cascade、または protect — 参照先オブジェクトが削除されたときに、カスタムオブジェクトがどうなるかを指定します。object フィールドのみが対象です。multiobject では無視されます。
• related_name：参照先での逆引きアクセサーです（例：エクスポート／設定テンプレートでの site.dhcp_scopes.all()）。ポリモーフィックフィールドでも機能します (v0.5.2+)。参照先のタイプごとに一意である必要があります。
• レスポンスには related_object_type（読み取り専用のネストされた {id, app_label, model}）が含まれます。app_label／model は書き込み専用です。

他のカスタムオブジェクトの参照

app_label を "custom-objects" に設定し、model に対象の COT のスラッグを指定します。

{
  "custom_object_type": 2,
  "name": "parent_scope",
  "label": "Parent Scope",
  "type": "object",
  "app_label": "custom-objects",
  "model": "dhcp-scopes"
}

自己参照フィールド（COT が自身を参照するフィールド）は使用できます。異なる COT 間の循環参照は、ポリモーフィックフィールド経由の場合も含め、検出されて 400 エラーで拒否されます (v0.5.2+)。

ポリモーフィック参照フィールド

object／multiobject フィールドでは、複数のオブジェクトタイプを参照できます (v0.5+)。is_polymorphic: true を設定し、app_label／model の代わりに related_object_types_input で許可するタイプを列挙します。

{
  "custom_object_type": 9,
  "name": "linked_resource",
  "label": "Linked Resource",
  "type": "object",
  "is_polymorphic": true,
  "related_object_types_input": [
    {"app_label": "dcim", "model": "device"},
    {"app_label": "custom-objects", "model": "servers"}
  ]
}

インスタンス値は辞書として指定します：{"app_label": "dcim", "model": "device", "object_id": 7}（content_type_id と id も別名として受け付けるため、読み取り表現をそのまま書き戻せます）。ポリモーフィックな multiobject では、このような辞書のリストを渡します。is_polymorphic と許可するタイプは、作成後に変更できません。変更するにはフィールドを削除して再作成してください。

オブジェクト選択の絞り込み

related_object_filter（query_params の辞書）を使って、UI のドロップダウンを絞り込みます。

{"type": "object", "app_label": "dcim", "model": "device", "related_object_filter": {"status": "active"}}

(v0.6+) オブジェクトおよびマルチオブジェクトのフォームフィールドは NetBox のクイック追加に対応しているため、ユーザーは参照先オブジェクトをインラインで作成できます。

リンクされたオブジェクト（逆引き）

指定したオブジェクト（コアまたはカスタム）を参照しているカスタムオブジェクトをすべて検索します。

GET /api/plugins/custom-objects/linked-objects/?object_type=dcim.device&object_id=42

{
  "count": 1,
  "results": [
    {
      "custom_object_type": {"id": 1, "name": "server", "slug": "servers"},
      "field_name": "primary_device",
      "object": {"id": 7, "display": "web-server-01"}
    }
  ]
}

両方のパラメーターが必須です。UI (v0.7+) では、参照されている各オブジェクトにカスタムオブジェクトタブが表示され、検索、タイプ／タグのフィルター、件数バッジとともに、すべてのタイプにわたる同じ関連情報が一覧表示されます。表示内容は、閲覧者がタイプごとに持つ表示権限に基づいて絞り込まれます（閲覧可能な項目がない場合、タブは非表示になります）。max_multiobject_display（プラグイン設定、デフォルトは 3）で、行ごとに表示するマルチオブジェクトの参照先数を制限します。

インスタンスの絞り込み

GET /api/plugins/custom-objects/dhcp-scopes/?scope_name=office        # text: substring (filter_logic=loose)
GET /api/plugins/custom-objects/dhcp-scopes/?lease_time__gte=3600       # numeric/date lookups (v0.6.1+)
GET /api/plugins/custom-objects/dhcp-scopes/?site=5&site_id=5          # object fields: either form
GET /api/plugins/custom-objects/dhcp-scopes/?target_dcim_device=7      # polymorphic: <field>_<app>_<model>
GET /api/plugins/custom-objects/dhcp-scopes/?id=1&id=2&tag=production&q=office

• テキスト形式のフィールド（text、longtext、url、json）は、デフォルトで icontains になります。filter_logic: "exact" を設定すると、完全一致と NetBox のサフィックス検索（__ic、__isw、__n、…）が利用できます。filter_logic: "disabled" を指定すると、フィルターが無効になります。
• 標準の NetBox パラメーター（q、tag、created__gte、limit／offset、ordering）を使用できます。タイプごとに生成されるフィルターの一覧は /api/schema/swagger-ui/ を参照してください。

GraphQL（v0.6+、読み取り専用）

query {
  custom_objects_dhcp_scopes_list { id display scope_name site { id name region { name } } }
  custom_objects_dhcp_scopes(id: 42) { id display }
}

• ルートフィールドは custom_objects_<slug> と custom_objects_<slug>_list です。スラッグ内の識別子として使用できない文字は _ に置き換えられます。単独のスラッグ名（dhcp_scopes_list）は存在しません。
• リレーションシップフィールドは、参照先のネイティブな NetBox GraphQL タイプを解決します（さらにたどることができます）。ポリモーフィックフィールドはユニオンです。... on DeviceType { } フラグメントを使用してください。
• coordinates フィールドと URL のタイトルは GraphQL では公開されません。REST を使用してください。
• 0.7.0 スキーマにはミューテーションとサーバー側のフィールドフィルターがありません。書き込みと絞り込みには REST を使用してください。
• 詳細：references/graphql-and-branching.md。

ブランチ分岐

モデルは v0.6.0 で変更されました。案内する前に、インストールされているプラグインのバージョンを確認してください。

プラグイン	ブランチ上の COT／フィールドの変更	ブランチ上のインスタンスの書き込み	ブランチ上のスキーマ適用
v0.6+	ブランチ対応：追跡、マージ、取り消しが可能（フィールドの追加／名前変更／削除、型の削除）	許可され、他の NetBox オブジェクトと同様に追跡されます	許可されます。DDL はブランチのスキーマに適用されます
v0.4–v0.5	main に直接書き込まれ、ブランチの差分には表示されません	拒否されます	ブロックされます

バージョン要件（v0.6+）： netbox_branching が PLUGINS に含まれている場合、このプラグインには NetBox ≥ 4.6.2 と netbox-branching ≥ 1.0.4 が必要です。それ以外の場合、システムチェック netbox_custom_objects.E001 / E002 により起動に失敗します。netbox-branching がインストールされていない場合は、通常の互換性マトリックス（NetBox 4.5.2–4.7.x）が適用されます。ブランチ分岐に必要な最小バージョンをインストールするには、pip install "netboxlabs-netbox-custom-objects[branching]" を実行してください。NetBox 4.7 では netbox-branching 1.2.x を、4.4–4.6 では 1.1.x を使用してください（netbox-branching を参照）。

exempt_models に関する警告： 公開されているブランチ分岐のドキュメントページには、0.6 より前の PLUGINS_CONFIG['netbox_branching']['exempt_models'] の設定例（customobjecttype / customobjecttypefield を除外）と、「インスタンスの書き込みは許可されない」という記述がまだ掲載されています。v0.6+ の統合は、除外設定なしでテストされています。v0.6+ でスキーマモデルを除外すると、インスタンスがブランチにある一方で、型／フィールドの変更は main に反映されます。お使いのバージョンのリリースノートで必要とされていない限り、この設定例を引き継がないでください。実行中のバージョンで確認してください。

詳細：references/graphql-and-branching.md。

Config Context と Config Templates

• Config context (v0.6+)：config_context_enabled: true を指定して COT を作成します。インスタンスには local_context_data（REST で書き込み可能な JSON）と Config Context タブが追加されます。ソース ConfigContext はフィールド名の規則に基づいて集約されます。ポリモーフィックでない object フィールドの名前が site、tenant、role、platform、location、device_type、または cluster で、一致するモデルを参照している場合、そのディメンションに反映されます。これらのフィールドがない型には、ローカルデータのみが適用されます（グローバルコンテキストは適用されません）。
• Config templates （v0.6.1 以降、NetBox 4.7 以降）：COT の内部 name（slug ではありません）を使って、デバイス／VM の config template からカスタムオブジェクトを参照します。

{% for iface in custom_objects.ospf_interface.filter(device=device) %}
interface {{ iface.name }}
 ip ospf area {{ iface.area }}
{% endfor %}
{# equivalent filter form: #}
{% for peer in 'bgp_peer' | custom_objects %}...{% endfor %}
{# names starting with a digit: #} {% for o in custom_objects['123foo'].all() %}...{% endfor %}

不明な名前は警告としてログに記録され、空のチェーン可能なプレースホルダーとしてレンダリングされます（行はなく、エラーもありません）。NetBox < 4.7 では、custom_objects 変数自体が存在しません。

ポータブルスキーマ（v0.5+）

COT 定義を YAML／JSON としてエクスポートし、バージョン管理して、他のインスタンスに適用できます。POST schema/preview/ は差分（is_new、has_destructive_changes、field_changes[]）を返します。POST schema/apply/ は {"allow_destructive": false, "schema": {...}} を指定してスキーマを適用し、列の削除が含まれていて許可されていない場合は 409 destructive_changes を返します。どちらも Content-Type: application/yaml または application/json を受け付け（YAML は v0.7 以降）、Accept: application/yaml の指定がない限り JSON を返します。フィールドは安定した schema_id で照合されます。削除には removed_fields の tombstone が必要です。ワークフローの全容：references/api-workflow.md。

プログラムからのアクセス（スクリプトとプラグイン）

カスタムスクリプトとプラグイン向けのドキュメント化されたパターン：

from netbox_custom_objects.models import CustomObjectType

DHCPScope = CustomObjectType.objects.get(name="dhcp_scope").get_model()
scope = DHCPScope.objects.filter(scope_name="office-floor-2").first()

返されるクラスは標準の Django モデルと同様に動作します（filter、create、update、delete、annotate）。pynetbox 7.8 以降では、CustomObjectsExtension を登録すると、JSON 列のラウンドトリップが可能になり、型ごとのエンドポイントが型付きレコードを返すようになります。例は references/api-workflow.md を参照してください。

継承される NetBox の機能

各カスタムオブジェクトには、タグ、ブックマーク、ジャーナリング、変更ログ、連絡先 (v0.6+)、所有権 (v0.6+)、一覧／詳細ビュー、インポート／エクスポート、グローバル検索（フィールドごとの search_weight）、イベントルールと通知、カスタムリンク、複製、タイプを参照する NetBox カスタムフィールド、REST フィルタリング／ページネーション／ETag（NetBox 4.6+）、オブジェクト権限が自動的に追加されます。

重要な制約

1. 削除は破壊的です：COT を削除するとテーブルが削除され、COTF を削除するとカラムが削除されます。元に戻せません。
2. インスタンス API では一括作成／更新／削除はできません — 配列を POST すると失敗します。オブジェクトごとに処理するか、UI の一括インポート／編集を使用してください。
3. API 書き込みでは検証が適用されます (v0.5+)：required、validation_regex、validation_minimum/maximum、および netbox_custom_objects.<cot-slug> をキーとする CUSTOM_VALIDATORS が対象です。
4. タイプの最大数：デフォルトでは 50（max_custom_object_types。0／None で無効になります）。
5. 予約済みフィールド名（32 個）：id、pk、tags、owner、contacts、local_context_data、created、last_updated、custom_object_type、custom_field_data、bookmarks、journal_entries、model、objects、save、delete、clean、clone、snapshot、… — API エラーにすべて一覧表示されます。
6. 一意性は、boolean、multiobject、coordinates フィールドには適用できません。
7. 名前の形式：COT と COTF の名前は ^[a-z0-9]+(_[a-z0-9]+)*$ に一致する必要があります。
8. 作成後は変更不可：is_polymorphic と許可されたタイプ、config_context_enabled、フィールドのタイプを複数カラムのタイプ（coordinates、url）との間で変更すること。
9. CSV インポートでは URL 値のみが設定され、<name>_title や座標のバックアップカラムは設定できません。
10. 必要な最小 NetBox バージョン：v0.5.x～v0.7.x では NetBox 4.5.2+ が必要です。4.7.x には v0.6.1+ が必要です。ブランチの追加により、下限は 4.6.2 / 1.0.4 になります。

アンチパターン

アンチパターン	失敗する理由	代わりに行うこと
lat/long フィールドに "type": "location" を指定する	有効な型ではありません。値は coordinates です（リリースノートでは「location」という語が使われています）	"type": "coordinates" を指定し、<name>_latitude と <name>_longitude をセットで記述します
REST 経由で "default": "\"active\"" を指定する	default は JSON です。エスケープした形式では、引用符を含む文字列が保存されます	"default": "active" を指定します（引用符で囲んだリテラルを入力するのは UI フォームです）
JSON 配列を /custom-objects/<slug>/ に POST する	エンドポイントは一括配列を受け付けません	オブジェクトごとにループし、それぞれ 201 が返ることを確認します
ブランチ上のインスタンスへの書き込みは拒否されると思い込む	v0.4～v0.5 でのみ該当します	v0.6 以降ではブランチで追跡されます。/api/status/ でプラグインのバージョンを確認してください
exempt_models の記述を v0.6 以降のインストール環境にコピーする	スキーマ（main）とインスタンス（branch）が分離されます。v0.6 以降のテストでは、この設定がなくても実行できます	お使いのバージョンのドキュメントに記載がない限り、COT/COTF は exempt にしないでください
GraphQL の dhcp_scopes_list / dhcpScopesList	ルートフィールドには接頭辞が付き、snake_case が使われます	custom_objects_dhcp_scopes_list を使います
GraphQL のミューテーションや filters: を送信する	0.7.0 のスキーマにはありません	書き込みとサーバー側のフィルターには REST を使います
ラベル名や誤字のあるフィールドを参照する display_expression	未定義の名前は空で表示されます。描画エラーはプライマリフィールドに暗黙的にフォールバックします。API は構文チェックを行いません	フィールドの name を参照し、{% if field %} でガードし、UI フォームでテストします
設定テンプレートに custom_objects.dhcp-scopes を指定する	内部の name で解決され、ハイフンは Jinja で有効ではありません	custom_objects.dhcp_scope（または custom_objects['123foo']）を使います
config_context_enabled を PATCH する	作成時のみ設定できます	タイプを再作成するか、そのままにします
multiobject フィールドに on_delete_behavior を指定する	無視されます	object フィールドでのみ意味があります
フィールド名に owner、contacts、local_context_data を使う	予約済みです（v0.6 以降で追加されました）	別の名前を選びます（owning_team など）
CUSTOM_VALIDATORS['netbox_custom_objects.dhcp_scope']	キーは slug です	netbox_custom_objects.dhcp-scopes を使います
"model": "table3model" で別の COT を参照する	内部名であり、v0.5 で削除されました	"app_label": "custom-objects", "model": "<target-slug>" を使います
slug が my_type の場合に pynetbox の nb.plugins.custom_objects.my_type を使う	属性アクセスでは _ が - に変換されます	nb.plugins.custom_objects.endpoint("my_type") を使います
フィールド追加後も GraphiQL の自動補完が更新されると期待する	Explorer はページ読み込みごとにスキーマをキャッシュします	「Re-fetch GraphQL schema」をクリックします。サーバー側はすでに最新です

参考資料

必要に応じて読み込みます：

• references/field-type-guide.md — フィールドを設定するときに読み込みます：型ごとの属性、coordinates/url の複数カラムでの動作、検証マトリクス、選択肢セット。
• references/api-workflow.md — エンドツーエンドの REST 連携を構築するときに読み込みます：DHCP スコープの完全な手順、フィルタリング、エラーテーブル、移植可能なスキーマのプレビュー／適用、pynetbox 拡張。
• references/graphql-and-branching.md — GraphQL 経由で読み取る場合、または netbox-branching と Custom Objects を併用する場合に読み込みます：フィールド名、型のマッピング、ユニオン、バージョンの条件、ブランチ対応の有無、設定コンテキストの集約ルール。
• references/modeling-patterns.md — 新しいタイプを設計するときに読み込みます：ルックアップテーブル、ブリッジ、階層、表示式、設定コンテキストの規則。

関連スキル

• netbox-data-modeling — カスタムオブジェクトを作成する前に、組み込みモデルで対応できるか確認します
• netbox-api-integration — 認証、ページネーション、一括処理のパターン、pynetbox の基本
• netbox-branching — ブランチのライフサイクル、バージョン系列（NetBox ≤ 4.6 では 1.1.x、4.7 では 1.2.x）
• netbox-plugin-development — カスタムオブジェクトだけでは不十分な場合
• netbox-custom-scripts — スクリプトでのカスタムオブジェクトの使用

リソース

• GitHub リポジトリ（ソース公開、NetBox Limited Use License）
• リリースノート
• 互換性マトリックス
• pynetbox Custom Objects 拡張機能