値式 (Value Expressions)

Script で値が必要となるすべての箇所(URL、リクエスト body、フィールド値、条件、フィルター値、対象 id など)は、以下の 3 つの形式のいずれかです。このドキュメントでは、その 3 つの形式と、値がどこから来るのか(コンテキストルート)、そして WEEGLOO データ特有のロケールマップのルールを説明します。Statement カタログのすべてのフィールドがこのルールに従います。

3 つの形式

3 つの形式はネストできます。JsonLogic のオペランドに参照を、参照の結果を再び演算に入れる形で組み合わせます。

参照: { /json-pointer }

波括弧の中に RFC 6901 JSON Pointer(必ず / で始まる)を入れます。波括弧の周囲の空白は許可されます({ /a/b } は {/a/b} と同じです)。

単一ポインターと混合テンプレート: 型のルール

• 文字列全体が単一ポインターの場合、その値の元の型をそのまま維持します(数値なら数値、オブジェクトならオブジェクト、配列なら配列)。
• リテラルテキストと混ざると文字列として連結(concatenation) されます。

"{ /payload/fields/count }"                 // 数値なら数値のまま (例: 42)
"{ /payload/fields/tags }"                  // 配列なら配列のまま
"page-{ /payload/fields/n }-of-10"          // 文字列連結 → "page-42-of-10"
"Bearer { /payload/fields/token }"          // 文字列連結 → "Bearer abc123"

存在しない値とエスケープ

• パスが存在しないか値が空の場合、単一ポインターは null、混合テンプレートは空文字列として処理されます。
• { をリテラルとして使うには \{ でエスケープします(その位置はポインターとして解釈されません)。

コンテキストルート: 値はどこから来るのか

{ /pointer } の最上位セグメントは、以下の 5 つのいずれかです。

statement の結果の形

name を持つ statement の結果の形は、型ごとに異なります。

• ResourceFind はマッチがない場合 null をバインドします。{ "==": [ "{ /found }", null ] } で存在の有無を分岐します。
• ResourceRead(単一)は対象が存在しない場合はエラーです(Try で処理できます)。詳しくは Statement カタログのリソース読み取りで扱います。

演算と条件: JsonLogic

計算や条件が必要なときは、jsonlogic.com 仕様の演算子オブジェクトを使います。

• データアクセスは vanilla の var(dot-path) ではなく { /ptr } 参照に統一します。エンジンはまずオペランドのポインターを resolve し、その後で演算子を適用します。
• 単一キーのオブジェクトのキーが登録済みの演算子であれば演算として、そうでなければ通常のオブジェクトとして扱います。

演算子の表

配列を反復する演算子(map, filter, reduce, all, some, none)はサポートしていません。Script は配列を Loop で反復します(Statement カタログの Loop)。

数値変換と例

数値変換のルールは次のとおりです。数値はそのままにし、true は 1、false は 0、文字列はパースし(パースできない場合は計算失敗値)、null は 0 に変換します。

{ "-":  [ "{ /wallet/fields/balance/en-US }", "{ /payload/fields/cost }" ] }   // 残高 - 費用
{ "<":  [ "{ /wallet/fields/balance/en-US }", "{ /payload/fields/cost }" ] }   // 残高 < 費用 → boolean
{ "and": [ { "<": [ "{ /a/body/risk }", 0.5 ] }, { ">=": [ "{ /b/body/score }", 700 ] } ] }
{ "cat": [ "id-", "{ /payload/sys/id }" ] }                                    // "id-<uuid>"
{ "!!": "{ /found/sys/id }" }                                                  // 存在すれば true
{ "merge": [ "{ /vars/ids }", [ "{ /row/sys/id }" ] ] }                        // 配列に要素を1つ蓄積
{ "if": [ "{ /page/next }", "{ /page/next }", "END" ] }                        // next があれば next、なければ "END"

真偽の判定 (Truthiness)

if、and、or、!、!! と If.condition、Loop.while は、以下のルールで真偽を判定します。

• falsy: null、false、数値 0、空文字列 ""、空のコレクション(空の配列)。
• truthy: それ以外すべて(0 でない数値、空でない文字列と配列、すべてのオブジェクト)。

キーも参照できます

fields のようなマップのキーも { /ptr } 参照をサポートします。キーは実行時に resolve されます。

"fields": { "{ /payload/fields/fieldName }": { "en-US": "{ /payload/fields/fieldValue }" } }

2 つのキーが同じ値に resolve されると、衝突してエンジンエラーになります。

ロケールマップ (LocaleValueMap): Content と Media 特有のルール

WEEGLOO の Content と Media の各フィールドは、値ではなくロケールごとのマップです(例: balance が { "en-US": 1, "ko-KR": 10 })。そのため、読み書きの際はロケールも一緒に扱う必要があります。Media も title と description(スカラー)、file(インジェスト指示)がロケールマップです。/payload や HTTP レスポンスのように Content でも Media でもない JSON は、このルールとは無関係です(スキーマが定めた構造そのままで、スカラーならスカラーです)。

読み取り

• スカラーを得るには ロケールまで指定します: { /<name>/fields/<field>/<locale> }(例: { /post/fields/title/en-US })。
• ロケールを指定せず { /<name>/fields/<field> } とすると、ロケールマップのオブジェクト全体が返ります。
• localized:false のフィールドは既定ロケールのバケットにのみ存在するため、その既定ロケールのコードで読み取ります。

書き込み (ResourceCreate, ResourceUpdate, ResourcePatch の fields)

値はロケールマップ { "<locale>": <スカラー値式> } です。読み取りと対称です。

"fields": {
  "title":  { "en-US": "Hello", "ko-KR": "안녕" },   // 複数のロケールはバケットを列挙
  "status": { "en-US": "paid" }
}

• ResourceCreate は populate するすべてのフィールドに space の既定ロケールのバケットを必ず含める必要があります(default-locale ルール)。
• ResourceUpdate は全体の置き換えです。fields にないフィールドとロケールは削除されます(file を含む)。
• ResourcePatch は指定したフィールドとバケットのみを更新します(残りのフィールドとロケールは維持)。
• リテラルの null で削除します: 値がリテラルの null であれば、その (field, locale) バケットを削除します(Patch で特定のロケールを空にする際の標準)。""(空文字列)は削除ではなく空の値の設定です。値式({ /ptr })が実行時に null と評価される場合は、削除ではなくエラーです(payload の欠落を黙って飲み込むことはありません)。削除はリテラルの null のみが該当します。
• Media の file: 値はスカラーではなくインジェスト指示 { "source": …, "encoding": "url"|"base64" } です。ファイルを含む書き込みは Async 専用です(Statement カタログの ResourceCreate)。
• localized:false のフィールドは既定ロケールのバケットにのみ入れます。
• ロケールコード(マップのキー)も { /ptr } 参照が可能です(上記 キーも参照できます を参照)。動的なロケールを作るときに使います。

locale 便宜フィールド

ResourceCreate、ResourceUpdate、ResourcePatch に locale を与えると、エンジンが fields の各値を自動的に { <locale>: 値 } バケットで包みます。 つまり、スカラーだけを与えればよいのです。

// 以下の2つは同じ
{ "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_post" } },
  "locale": "en-US", "fields": { "title": "Hello" } }
 
{ "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_post" } },
  "fields": { "title": { "en-US": "Hello" } } }

locale を与えつつ、値にすでにロケールマップ({ "en-US": … })をネストしていると、{ <locale>: { "en-US": … } } のように二重にネストされます(作成者のミス)。locale を使うならスカラーのみ、使わないなら明示的なロケールマップのみ、というように 1 つに統一します。

where と order のロケール

• where と order では、fields.X にエンジンが space の既定ロケールを自動的に適用します(CMA の照会と同じ)。
• 特定のロケールを狙うには、fields.X.<locale> のように明示します。

"where": { "fields.slug": { "eq": "{ /payload/fields/slug }" } }   // 既定ロケールの slug
"where": { "fields.title.ko-KR": { "prefix": "안" } }              // 特定のロケール

関連ドキュメント

• Statement カタログ: 値式を使う 17 種の文のフィールドと結果。
• 実行セマンティクス、制約、セキュリティ: 実行順序、エラー、楽観的ロック、静的制約。
• クックブック: 値式を組み合わせた完結した例。
• Script 概要: 最上位構造と実行モード。