fcode-json-schema

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Factorial Code — input parameter schemas

Factorial Code — 输入参数模式

A process's input parameters are defined by a JSON Schema in

parametersSchema.json

. The same schema is what

fcode-forms

renders as a web form, so designing the schema is designing the form. Values arrive in code as

fcode.context.parameters

(see

fcode-javascript

fcode-python

Schemas render with react-jsonschema-form, so its

ui:

options apply.

流程的输入参数由

parametersSchema.json

中的JSON Schema定义。该模式同时也是

fcode-forms

渲染为网页表单的依据，因此设计模式就是设计表单。参数值在代码中通过

fcode.context.parameters

获取（详见

fcode-javascript

fcode-python

）。

模式使用react-jsonschema-form进行渲染，因此其

ui:

选项适用。

How to author one

如何编写输入参数模式

Top level is
```
"type": "object"
```
with a
```
properties
```
map (one entry per field) and an optional
```
required
```
array.

Pick a

type

per field (

string

integer

number

boolean

array

object

) and add validation (

minimum

maximum

format

enum

oneOf

uniqueItems

, nested

properties

Control rendering with a per-field
```
ui
```
object (e.g.
```
"ui": { "ui:widget": "textarea" }
```
).
Open
assets/parametersSchema.sample.json
for a complete, copy-pasteable schema exercising every supported type — adapt fields from it rather than guessing the shape.

顶级结构为
```
"type": "object"
```
，包含
```
properties
```
映射（每个字段对应一个条目）和可选的
```
required
```
数组。
为每个字段选择
```
type
```
类型（
```
string
```
、
```
integer
```
、
```
number
```
、
```
boolean
```
、
```
array
```
、
```
object
```
），并添加验证规则（
```
minimum
```
/
```
maximum
```
、
```
format
```
、
```
enum
```
/
```
oneOf
```
、
```
uniqueItems
```
、嵌套
```
properties
```
）。
通过每个字段的
```
ui
```
对象控制渲染（例如
```
"ui": { "ui:widget": "textarea" }
```
）。
**打开
```
assets/parametersSchema.sample.json
```
**获取完整的、可复制粘贴的模式示例，涵盖所有支持的类型——建议从中调整字段，而非自行猜测结构。

Field types & widgets (in the sample)

字段类型与组件（示例中包含）

Text —

"type": "string"

;

format: "email"

;

ui:widget

textarea

color

hidden

, or

file

Secret —
```
"isSensitive": true
```
masks the input (e.g. passwords/tokens).
Numbers —
```
integer
```
/
```
number
```
with
```
minimum
```
/
```
maximum
```
.
Boolean —
```
"type": "boolean"
```
.

Choices —

enum

(select),

oneOf

{ const, title }

(labeled radio with

ui:widget: "radio"

), or an array with

ui:widget: "checkboxes"

uniqueItems

Structured — nested
```
object
```
with its own
```
properties
```
/
```
required
```
; arrays of strings or of objects (
```
type: "array"
```
+
```
items
```
); raw JSON via
```
"ui": { "ui:field": "json" }
```
.
Conditional fields — use top-level
```
dependencies
```
to show/hide fields based on another field's value (see
```
anotherBooleanField
```
in the sample).

文本 —

"type": "string"

；

format: "email"

；

ui:widget

可选

textarea

、

color

、

hidden

或

file

。

敏感信息 —
```
"isSensitive": true
```
会屏蔽输入内容（如密码/令牌）。
数字 —
```
integer
```
/
```
number
```
类型，可设置
```
minimum
```
/
```
maximum
```
。
布尔值 —
```
"type": "boolean"
```
。
选择项 —
```
enum
```
（下拉选择）、
```
oneOf
```
搭配
```
{ const, title }
```
（带标签的单选框，需设置
```
ui:widget: "radio"
```
），或数组类型搭配
```
ui:widget: "checkboxes"
```
+
```
uniqueItems
```
。
结构化数据 — 嵌套
```
object
```
，包含自身的
```
properties
```
/
```
required
```
；字符串数组或对象数组（
```
type: "array"
```
+
```
items
```
）；通过
```
"ui": { "ui:field": "json" }
```
支持原始JSON输入。
条件字段 — 使用顶级
```
dependencies
```
根据其他字段的值显示/隐藏字段（详见示例中的
```
anotherBooleanField
```
）。

Gotchas

注意事项

A file field (
```
"ui:widget": "file"
```
) is auto-uploaded to Storage before the process runs; the parameter arrives as an
```
fcode.storage://…
```
reference, not the file contents. Strip the prefix before
```
fcode.storage.download(...)
```
.
isSensitive: true
only affects display/masking — still read the value from a secret variable, never hardcode it.
The schema is the single source of the form's fields — to change fields, edit the schema, not the form embed code.
The schema is data, not code. It cannot carry executable JavaScript:
```
embedFormOptions.onChange
```
and
```
embedFormOptions.fields.<field>.transformFn
```
were removed, and
```
rawHtml
```
content is sanitized (no
```
<script>
```
, no inline
```
on*
```
handlers, no
```
javascript:
```
URLs). Client-side behaviour belongs in the embedding page — see
```
fcode-forms
```
.
Visible text can be translated: schema strings (titles, descriptions,
```
ui:placeholder
```
) accept
```
fcode.i18n("key")
```
tokens, substituted server-side before the form is served — see
```
fcode-i18n
```
.

文件字段（
```
"ui:widget": "file"
```
）会在流程运行前自动上传至Storage；参数会以
```
fcode.storage://…
```
引用的形式传入，而非文件内容。调用
```
fcode.storage.download(...)
```
前需移除该前缀。
**
```
isSensitive: true
```
**仅影响显示/屏蔽——仍需从机密变量中读取值，切勿硬编码。
模式是表单字段的唯一数据源——如需修改字段，请编辑模式，而非表单嵌入代码。
模式是数据，而非代码。它无法承载可执行JavaScript：
```
embedFormOptions.onChange
```
和
```
embedFormOptions.fields.<field>.transformFn
```
已被移除，
```
rawHtml
```
内容会被 sanitize（不允许
```
<script>
```
、内联
```
on*
```
处理程序、
```
javascript:
```
URL）。客户端行为应放在嵌入页面中——详见
```
fcode-forms
```
。
可见文本可翻译：模式中的字符串（标题、描述、
```
ui:placeholder
```
）支持
```
fcode.i18n("key")
```
令牌，表单在服务端渲染前会替换这些令牌——详见
```
fcode-i18n
```
。