fcode-json-schema

Factorial Code — 入力パラメータのスキーマ

プロセスの入力パラメータは、JSON Schema で parametersSchema.json に定義します。fcode-forms が Web フォームとして レンダリングするのも同じスキーマなので、スキーマの設計がフォームの設計に なります。値はコード内で fcode.context.parameters として受け取ります （fcode-javascript／fcode-python を参照）。

スキーマは react-jsonschema-form でレンダリングされるため、 その ui: オプションを適用できます。

スキーマの作成方法

1. 最上位を "type": "object" とし、properties マップ（フィールドごとに 1 エントリ）と、省略可能な required 配列を設定します。
2. フィールドごとに type（string、integer、number、boolean、array、object）を選び、バリデーション（minimum／maximum、format、enum／oneOf、uniqueItems、ネストした properties）を追加します。
3. フィールドごとの ui オブジェクトでレンダリングを制御します（例： "ui": { "ui:widget": "textarea" }）。
4. assets/parametersSchema.sample.json を開くと、サポートされているすべての型を網羅した、コピーして使える完全なスキーマを確認できます。形を推測するのではなく、そこからフィールドを調整してください。

フィールドの型とウィジェット（サンプル内）

• テキスト — "type": "string"、format: "email"、または textarea、 color、hidden、file の ui:widget。
• シークレット — "isSensitive": true を設定すると入力がマスクされます（パスワードやトークンなど）。
• 数値 — minimum／maximum を指定した integer／number。
• ブール値 — "type": "boolean"。
• 選択肢 — enum（セレクト）、{ const, title } の oneOf（ui:widget: "radio" を指定したラベル付きラジオボタン）、または ui:widget: "checkboxes" と uniqueItems を指定した配列。
• 構造化データ — 独自の properties／required を持つネストした object、文字列またはオブジェクトの配列（type: "array" と items）、"ui": { "ui:field": "json" } による生の JSON。
• 条件付きフィールド — 最上位の dependencies を使って、別のフィールドの値に応じてフィールドを表示／非表示にします（サンプルの anotherBooleanField を参照）。
• フィールドの前後に表示するコンテンツ — フィールドごとの markdown オブジェクトに before／after 文字列を設定すると、フィールドの上／下にブロック形式の Markdown（テーブルを含む完全な GFM）を表示できます。詳細と使用例は fcode-forms の references/advanced.md を参照してください。
• 長いフォーム — フィールドがおよそ 10 個以上ある場合は、ルートレベルの ui:steps ノードを使ってステップに分割します。fcode-forms の「§Multi-step forms」を参照してください。
• 外部アカウントの接続 — "ui": { "ui:widget": "oauth", "ui:options": { "authorizationUrl": … } } を指定した string または boolean は、ポップアップで OAuth フローを完了するボタンとしてレンダリングされます（object の場合は "ui:field": "oauth" を指定します。サンプルの oneOauthConnectField を参照）。仕様とコールバックについては fcode-forms の「§Connect an external account」を参照してください。

注意事項

• ファイルフィールド（"ui:widget": "file"）では、プロセスの実行前にファイルが自動的に Storage にアップロードされます。パラメータとして届くのはファイルの内容ではなく fcode.storage://… 参照です。fcode.storage.download(...) を呼び出す前にプレフィックスを取り除いてください。
• isSensitive: true は表示とマスキングにのみ影響します。値は引き続きシークレット変数から読み取り、ハードコードしないでください。
• OAuth フィールドの authorizationUrl には、preRenderProcess 変数から { "$ref": "#/variables/x" } を注入する必要があります。 {{x}} は使わないでください。Mustache により URL が HTML エスケープされ、ウィジェットが拒否します（コンソールに警告が表示され、ボタンは無効になります）。
• スキーマはフォームのフィールドの唯一の情報源です。フィールドを変更するには、フォームの埋め込みコードではなくスキーマを編集してください。
• スキーマはコードではなくデータです。 実行可能な JavaScript は使用できず、フォームのすべてのテキストは Markdown です（生の HTML はレンダリングされません）。クライアント側の動作は埋め込みページに実装してください。fcode-forms を参照してください。
• 表示テキストは翻訳できます。 スキーマ内の文字列（タイトル、説明、ui:placeholder）には fcode.i18n("key") トークンを指定できます。フォームが配信される前にサーバー側で置換されます。fcode-i18n を参照してください。