fcode-json-schema

Factorial Code — input parameter schemas

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.

How to author one

1. Top level is "type": "object" with a properties map (one entry per field) and an optional required array.
2. Pick a type per field (string, integer, number, boolean, array, object) and add validation (minimum/maximum, format, enum/oneOf, uniqueItems, nested properties).
3. Control rendering with a per-field ui object (e.g. "ui": { "ui:widget": "textarea" }).
4. Open assets/parametersSchema.sample.json for a complete, copy-pasteable schema exercising every supported type — adapt fields from it rather than guessing the shape.

Field types & widgets (in the sample)

• Text — "type": "string"; format: "email"; ui:widget of 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 of { 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).
• Content around a field — a per-field markdown object with before / after strings renders block markdown (full GFM, incl. tables) above/below the field. Detail and a worked example in fcode-forms (references/advanced.md).
• Long forms — split roughly ten or more fields into steps with a root-level ui:steps node; see fcode-forms §Multi-step forms.
• Connect an external account — a string or boolean with "ui": { "ui:widget": "oauth", "ui:options": { "authorizationUrl": … } } renders a button that completes an OAuth flow in a popup ("ui:field": "oauth" for an object; see oneOauthConnectField in the sample). Contract and callback in fcode-forms §Connect an external account.

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.
• An oauth field's authorizationUrl must be injected with { "$ref": "#/variables/x" } from a preRenderProcess variable — never {{x}}, which Mustache HTML-escapes into a URL the widget refuses (the button renders disabled with a console warning).
• 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 — no executable JavaScript, and all form text is markdown (raw HTML is never rendered). 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.