KUMIURU テンプレJSON仕様書（インポート用）

KUMIURUでは、テンプレJSONをインポートすることで、オプション（設問）・選択肢・条件表示・プリセット（自動入力）などの設定を一括で復元できます。
本記事では、テンプレJSONの構造・各フィールドの意味・条件表示のルール・よくあるミスまでを仕様として整理します。

---

1. テンプレJSONの全体構造

テンプレファイルのトップレベルは、次の3要素で構成されます。

フィールド定義

• version（string）
  テンプレ仕様バージョン。例："1.0"

• exportedAt（string / ISO8601）
  エクスポート日時（監査・更新確認用途）

• template（object）
  テンプレ本体（以降の章で詳細）

---

2. template オブジェクト

フィールド定義

• title（string）
  管理画面等で表示するテンプレ名

• handle（string）
  テンプレ識別子（英小文字＋ハイフン推奨）
  例："order-shirts", "size"

• useCustomPricing（boolean）
  価格計算を「カスタム扱い」に切り替えるフラグ

  • false：通常の価格加算（選択肢の加算中心）

  • true：カスタム価格ロジックを使う（主にサイズ系テンプレで利用）

• optionGroups（array）
  設問（オプション）グループの配列（テンプレの本体）

---

3. optionGroups（設問グループ）仕様

optionGroups[] の1要素が、画面に表示される1つの設問に相当します。
（例：襟型、カフス、刺繍の有無、数値入力の「首回り」など）

optionGroup の基本形

フィールド定義（重要）

• code（string / 必須）
  設問のユニークID。テンプレ内で重複禁止

  • 条件表示（親子）や presets 参照のキーになるため、命名は慎重に。

• label（string / 必須）
  画面に表示する設問タイトル

• description（string / 任意）
  補足説明。改行は \n を使用可。

• imageUrl（string / null）
  設問に紐づく画像URL。null可。
  ※複数URLをカンマ区切りで保持している例もあるため、実装側仕様に合わせること。

• layoutType（string）
  UI表示形式。例：

  • list：縦並び

  • grid-2 / grid-3 / grid-4：グリッド

  • select / buttons：実装により

• displayPrefix / displaySuffix（string / null）
  表示用の前後テキスト（数値入力で cm を suffix に付ける等）

• inputType（string / 必須）
  入力タイプ（重要）

  • select：選択肢（values が実質の候補）

  • text：テキスト入力

  • number：数値入力

• numberConfig（string / null）
  inputType: "number" のときの制約設定（JSON文字列として入る）
  例：

  
  

  
  

  "{\"min\":10,\"max\":50,\"step\":1,\"unit\":\"cm\"}"

  
  

• inputPriceCents（number）
  その設問自体に紐づく追加料金（通常 0 が多い）

• accordionDefaultOpen（boolean）
  アコーディオン初期開閉

• showInMore（boolean）
  「もっと見る」など、詳細枠に回す表示フラグ

• sortOrder（number）
  設問の表示順。小さいほど上。

• isRequired（boolean）
  必須設問かどうか

• depth（number）
  階層の深さ（0=最上位、1=子、2=孫…）
  ※UI/構造の目安として保持

• parentCode（string / null）
  親となる設問の code（条件表示で使用）

• visibleWhenParentValueCodes（array<string>）
  親の選択値に応じた表示条件（後述）

• values（array）
  選択肢（select）または内部用の値（text/numberでも登場）

---

4. values（選択肢）仕様

optionGroups[].values[] は、設問内の選択肢を表します。

value の基本形

フィールド定義

• code（string / 必須）
  選択肢のユニークID（同一 optionGroup 内で重複禁止）

• label（string / 必須）
  選択肢の表示名

• description（string / null）
  選択肢の補足説明

• imageUrl（string / null）
  選択肢の画像URL

• extraPriceCents（number）
  この選択肢を選んだときの追加料金

• isDefault（boolean）
  デフォルト選択かどうか
  ※selectの場合、基本は 最大1つ を推奨（実装依存）

• sortOrder（number）
  選択肢の並び順

• visibleChildGroupCodes（array<string>）
  この選択肢を選択したときに表示する「子 optionGroup の code」一覧（後述）

• presets（array）
  この選択肢を選んだとき、他の数値入力等へ値を自動セットする（後述）

---

5. 条件表示（親子関係）仕様：2つの方式

テンプレには、条件表示が 2種類あります。混在可能です。

A. 子側で条件を持つ方式（visibleWhenParentValueCodes）

子 optionGroup に以下を設定します。

• parentCode：親 optionGroup の code

• visibleWhenParentValueCodes：許可する親の選択値コードを列挙

指定形式

"親code:親value.code"

例：刺繍を「する」場合だけ「刺繍内容」を表示

visibleWhenParentValueCodes は配列なので、複数指定＝OR条件になります。

---

B. 親の選択肢が子を呼び出す方式（visibleChildGroupCodes）

親 optionGroup の value 側に以下を設定します。

• visibleChildGroupCodes：表示したい子 optionGroup の code を列挙

例：刺繍「する」を選ぶと、場所・色・内容・書体が表示

---

6. text/number の内部値 __HAS_INPUT__ 仕様（重要）

inputType: "text" または inputType: "number" の optionGroup では、values に以下のような 内部用ダミー値が入る場合があります。

ルール

• __HAS_INPUT__ は ユーザーに選ばせる値ではありません

• 入力が存在することを内部的に表現するための値として使われます

• テンプレ作成時は、基本的に 編集不要／削除しない を推奨します

---

7. presets（選択時の自動入力）仕様

presets は、選択肢を選んだ瞬間に、他の optionGroup（主に number 入力）へ値をセットする機能です。
サイズテンプレの「Sサイズから調整」等で利用されます。

presets の形

ルール

• targetGroupCode は 必ず存在する optionGroup.code を指定

• presetValue は 文字列で持つ（数値でも文字列で格納される想定）

• 既にユーザーが手入力した場合の優先順位（上書きする/しない）は、実装側仕様に依存
  → マニュアル運用上は「ベース値として入る」と説明するのが安全

---

8. 価格フィールド仕様（Cents表記）

テンプレ上の価格は以下2箇所に出ます。

• optionGroup：inputPriceCents

• value：extraPriceCents

注意（必読）

*Cents の単位が「円」なのか「円×100」なのか（Shopifyの minor unit 相当なのか）は、KUMIURU側の価格実装に依存します。
テンプレ作成・運用時は、以下のどちらかを必ず統一してください。

• 例1：800円 → 800 で保持

• 例2：800円 → 80000（円×100）で保持

添付テンプレでは 80000 や 50000 のような値が見られるため、運用単位が「円×100」の可能性があります。
ただし、最終判断は KUMIURU の価格処理仕様に合わせてください（ここは実装と必ず整合させるポイントです）。

---

9. 作成・編集時のチェックリスト（よくあるミス防止）

A. code の整合

• optionGroups[].code がテンプレ内で重複していない

• values[].code が同一 optionGroup 内で重複していない

B. 親子条件

• parentCode が存在する optionGroup.code を指している

• visibleWhenParentValueCodes の形式が "親code:親valueCode" になっている

• visibleChildGroupCodes が存在する optionGroup.code を指している

C. presets

• targetGroupCode が存在する optionGroup.code を指している

• presetValue が想定の型（通常は文字列）になっている

D. numberConfig

• numberConfig は JSON文字列（objectではなく string）で入っている

• min/max/step/unit のキーが実装と一致している

E. __HAS_INPUT__

• text/number の values に __HAS_INPUT__ が必要な仕様の場合、削除していない

---

10. 最小テンプレ例（コピペ用）

例：選択式（刺繍する/しない）＋「する」時だけ子を表示

---

付録：この仕様書を運用ルールに落とすときの推奨（短く）

• code 命名規則（例：英小文字＋ハイフン or スネークで統一）

• 価格単位（*Cents の単位）を必ず明文化

• 条件表示は **A方式（visibleWhenParentValueCodes）**に寄せるか、**B方式（visibleChildGroupCodes）**に寄せるか、チームで統一

• numberConfig は「JSON文字列」として扱うことを周知

• __HAS_INPUT__ は内部仕様として削除しない

---

もし次に、**「この仕様書を元に、テンプレ作成の手順書（運用マニュアル）」**もShopifyブログ用に作るなら、

• 例：オプション追加 → 選択肢追加 → 画像追加 → 条件表示 → プリセット → 価格
  の順で、画面キャプチャを差し込める構成にして用意できます。