Script

Script は、フロントエンドが HTTP で呼び出す宣言型のバックエンドエンドポイントです。サーバーコードを書かずに「何をするか」を JSON で宣言すると、WEEGLOO エンジンが代わりに実行します。認証、条件チェック(guard)、連鎖 CRUD、外部 API 呼び出し、値の加工といった、フロントエンドを支える典型的なバックエンドの配管(BFF、Backend-for-Frontend)を Script 1 つで置き換えることが狙いです。

このドキュメント群は Script 文法の正本(reference)です。個々の文法の詳細は、以下の このグループのドキュメントで分けて扱います。

Script は CMA で作成し実行します(Weegloo User の身元)。製品に加入した会員(ServiceUser)の身元では ACMA でも同じ方法で使えます。Script API はこの 2 つの管理 API(CMA、ACMA)にのみあり、読み取り専用の配信 API(CDA、ACDA)にはありません。

メンタルモデル

• 1 つの Script は 1 つの HTTP エンドポイントです。 呼び出しメソッド(method)で、どの Script を実行するかをマッチングします。
• 本文は statements 配列です。 上から下へ順に実行されます。一般的なプログラミングの関数本体と同じです。
• コードではなく宣言です。 任意のコード(FaaS)を入れるのではなく、定められた statement タイプを組み合わせます。人が手で書くよりも、AI エージェントが MCP で生成する方に合わせて設計されています。
• 値は JSON Pointer テンプレートで流れます。 前のステップの結果、入力 payload、変数を { /pointer } で参照して次のステップへ渡します。条件や計算が必要なときは JsonLogic 演算子を使います。詳しいルールは 値式で扱います。

最上位構造 (ScriptDefinition)

1 つの Script は、次の ScriptDefinition 構造で定義します。

{
  "method": "Post",               // Get | Post | Put | Patch | Delete。呼び出し時にマッチングする HTTP メソッド(必須)
  "payloadSchema": { /* ... */ }, // (任意) JSON Schema。指定すると実行前にリクエスト payload を検証
  "executionMode": "Sync",        // "Sync" | "Async"(必須)
  "statements": [ /* Statement[]。上から下へ実行(必須、1 個以上) */ ]
}

payload は JSON のみを受け付けます。呼び出し body は /payload コンテキストルートでアクセスします({ /payload/... })。呼び出しのリクエスト HTTP ヘッダーは /headers ルートで参照します({ /headers/... }、キーは小文字)。コンテキストルート全体は 値式で扱います。

リクエストとレスポンス

Script は最終的に Return 文の値を呼び出し元へ返します。レスポンス(または Async のポーリング結果)の形は次のとおりです。

{
  "requestId": "…",     // 実行識別子(Async はこの id で結果をポーリング)
  "durationMs": 1234,   // 実行にかかった時間(ms)
  "statusCode": 200,    // 到達した Return の statusCode(デフォルト 200)
  "return": <value>     // Return.isError が false のときのみ。値が null なら ""
  // "error": <value>   // Return.isError が true のときのみ(このとき "return" はない)。値が null なら ""
}

• return と error は同時には出ません。Return 文の isError がどちらかを決めます。
• Return 文に到達しないまま Script が終わると、return と error はどちらも出ず、statusCode はデフォルト値(200)になります。
• 値が null の場合、そのフィールドは空文字列 "" として出ます。

Return の value・isError・statusCode でレスポンス本文とステータスコードを制御します。詳しくは Statement カタログの Returnで扱います。

実行モード: Sync と Async

• 外部 I/O があると Async のみ許可されます。 どの statement であれ、Http の外部呼び出し(ExternalIo)や Media ファイルのインジェスト(MediaIngest。url・base64)のようにネットワークを介す作業が 1 つでもあると、executionMode は必ず Async でなければならず、Sync で保存しようとすると保存の時点で拒否されます。リクエストスレッドを外部の遅延で塞がないためです。
• 実行位置の違いだけで、どちらであっても結果は Return の値です。

能力からモードへとつながるルールと限度の詳細は、実行セマンティクス、制約、セキュリティで扱います。

最小の例

リクエスト payload のタイトルと本文で記事の Content を作成し、そのまま公開したあと、作成した sys.id を返します。

{
  "method": "Post",
  "executionMode": "Sync",
  "statements": [
    { "type": "ResourceCreate", "resource": "Content",
      "contentType": { "sys": { "id": "ct_post" } },
      "fields": {
        "title": { "en-US": "{ /payload/fields/title }" },
        "body":  { "en-US": "{ /payload/fields/body }" }
      },
      "publish": true,
      "name": "post" },
 
    { "type": "Return", "value": { "id": "{ /post/sys/id }" }, "statusCode": 201 }
  ]
}

• ResourceCreate で Content を作成し、結果を post という名前にバインドします。
• Return が { "id": <新しい Content id> } を 201 で返します。
• Content の fields 値がロケールマップ({ "en-US": ... })である理由は、値式のロケールマップで扱います。

さらに多様なシナリオは クックブックにあります。

このグループのドキュメント

• 値式: { /pointer } 参照、リテラル、JsonLogic の演算と条件、コンテキストルート、ロケールマップを扱います。文法の中核です。
• Statement カタログ: 17 種の文(リソースの CRUD と読み取り、Http、SetVar、If、Loop、Parallel、Try、Return)のフィールドと結果を扱います。
• 実行セマンティクス、制約、セキュリティ: 実行順序、guard、補償、楽観的ロック、エラー、静的制約とプラン限度、セキュリティモデルを扱います。
• クックブック: upsert、クレジット guard、LLM プロキシ、ページネーション、並列、決済サガなど、完結した例を扱います。
• Script リソースとエンドポイント: Script リソースの sys 構造と作成、実行(/execute)の HTTP エンドポイント仕様を扱います。

初めてであれば、このページから 値式、Statement カタログの順に読むことをおすすめします。クックブックは丸ごと目を通しても構いません。