JSON Schema for Typed Workflow Inputs (Forms, APIs, and Agents)

One input contract, three surfaces: the Hub form on /w/{slug}, your backend’s POST /w/{slug}/runs, and your agent’s wf_<slug> MCP tool all read from the same JSON Schema. That is how Wavemaker avoids the classic generative-API problem — undocumented prompt blobs — on the workflow API. This post covers promotion, schema shape, validation, and codegen — not Comfy node widgets (those transpile separately; see Import ComfyUI workflows).

Answer-first: what integrators download

curl -s https://api.wavemaker.io/api/v1/w/product-teaser \
  -H "Authorization: Bearer mcp_your_key" | jq '.workflow.input_schema'

You get Draft 2020-12 JSON Schema describing the inputs object for runs:

• Required fields match what the compile gate enforced at publish time.
• Enums surface when the builder locked choices (aspect ratio presets, voice ids from allowlists).
• Format hints (uri, image_asset) map to platform validators — not every JSON Schema keyword is exposed to anonymous clients on premium listings, but runners always see enough to submit.

The static app page hydrates the same document client-side (Publish your AI workflow as an app).

From builder fields to $input wiring

Authors declare promoted inputs in the workflow editor — each input has:

Concept	Role
key	Stable id referenced as $input.product_url in block params
type	string, number, boolean, enum, image, etc.
default	Optional; shown on Hub and applied when omitted if allowed
label / description	UX + agent-readable help

At compile time, the compiler resolves $input.* references, typechecks against block manifests, and builds the cost envelope from literal + input-driven params. At publish, the promoted input list freezes into workflow_spec_versions — API consumers pin version to keep the schema stable (workflows as API endpoints).

Changing inputs after publish requires a new published version; integrators on default “latest published” pick up schema changes when creators ship — plan semver-style communication with your customers.

Server-side validation on run and estimate

POST /w/{slug}/estimate and /runs share validation:

1. Parse JSON body inputs.
2. Validate against the pinned version’s schema (or latest published).
3. On success, estimate computes line items; run enqueues kernel execution.

Validation errors return structured 400s with JSON Pointer paths — feed them to agents for self-repair loops (AI agents that build pipelines). Estimates are free; use them as a dry-run validator in CI.

Image and URL inputs

• URL fields must be HTTPS reachable from Wavemaker runners (scraping blocks enforce robots and size caps).
• Image inputs typically reference upload keys from POST /api/v1/uploads or dataset items — not raw megabyte base64 in JSON. The schema documents allowed patterns; MCP tools mirror the same constraints.

Brand-site URLs often pair with scrape blocks — schema describes one string; behavior lives in the graph (Turn a website URL into a video covers managed video; workflows use the same scrape primitives in blocks).

Client codegen patterns

Because GET /api/v1/openapi.json describes routes but per-slug input shapes vary, most teams:

1. Fetch GET /w/{slug} at deploy time (or when creators publish).
2. Generate a TypeScript interface or JSON Schema file checked into repo.
3. Call estimate in CI with fixture inputs before promoting config.

OpenAPI alone cannot enumerate every Hub workflow — combine platform OpenAPI (OpenAPI for generative media) with per-slug schema artifacts. For agents, paste input_schema into context or rely on MCP tool parameters (Dynamic MCP tools).

Hub form parity

AppPageIsland renders from the same schema — conditional fields, enum selects, and estimate buttons. Runners see what API integrators get; no hidden required params. Signed-out visitors may see redacted premium pricing but still read input definitions for SEO and sharing.

Published Hub app page at /w/{slug} with typed inputs and Run.

Version pinning and schema drift

Strategy	Schema source
Default latest published	Changes when creator publishes
"version": N in run body	Frozen to version N’s promotion set
Fork after remix	New spec id + slug under your org

Remix lineage is visible on Hub pages (Remixing AI workflows) — schema diffs should be release-noted when you maintain public integrations.

Enum and constraint patterns

Authors use enums when integrators should not send free-form strings:

• Aspect ratio presets matching engine capability grids
• Voice id from org allowlist after design_voice bindings
• Style profile ids from published style-locked workflows (Style-locked workflows)

JSON Schema minimum / maximum on numeric inputs guard duration and batch sizes at validation time — compile may still fail if block manifests require stricter bounds.

Anonymous vs authenticated schema reads

Hub SEO pages expose input labels to crawlers; premium listings may hide creator graph but keep runner-facing schema on authenticated API. Public estimate previews on /w/{slug} let signed-out visitors see approximate pricing — integrators should always authenticate for production quotes with BYOK lines (BYOK AI media generation).

Multi-input workflows and $expr

Advanced specs combine inputs with lightweight expressions (concat labels, conditional defaults). The promoted schema exposes only inputs, not internal $expr — runners stay unaware of graph glue. When debugging validation failures, fetch compile diagnostics — they reference internal node ids while API 400s reference JSON Pointer paths under inputs.

Testing schemas in staging

1. Clone Open workflow from Hub via remix (Remixing AI workflows).
2. Publish to staging org slug.
3. Snapshot input_schema into repo; wire contract test to estimate endpoint.
4. On creator publish notification, diff schema in CI.

Interop with form builders

Because schema is Draft 2020-12, @rjsf/core, react-jsonschema-form, and similar renderers work against GET /w/{slug} responses. File upload widgets map to Wavemaker upload keys — flow: POST /uploads → pass key in inputs.image_ref (exact key names per workflow).

FAQs for schema authors

Optional vs required: optional inputs must have defaults or blocks must tolerate absence — compile fails otherwise.

Breaking changes: renaming keys breaks integrators; prefer additive keys and deprecate in description text.

Premium workflows: schema + pricing only — graph remains hidden.

Style and image inputs in schema

Workflows with style-locked references or image inputs declare typed fields — runners upload via API first, then pass keys in inputs. Schema descriptions should link to max file sizes and moderation rules (workflows overview). Agents using MCP must call upload tools in full mode or REST uploads before wf_ tools when inputs require asset keys.

Premium hide and public SEO

Search engines index /w/{slug} copy and input labels; JSON-LD FAQ from blog posts is separate. Schema on public pages helps LLM crawlers (AI workflow builder) understand required runner fields without leaking premium graph JSON.

Migrating from untyped JSON configs

Teams often start with { "prompt": "..." } blobs in config files. Migration path:

1. Publish workflow with promoted inputs replacing free text where possible.
2. Fetch input_schema and replace config keys one field at a time.
3. Run estimate in CI until legacy keys are removed.

Typed inputs reduce agent hallucination — enums especially for aspect ratio and model pins.

Where to go next

• REST slug runs: /workflow-api
• Idempotency + webhooks on validated submits: Idempotency and webhooks
• MCP typed tools: Agent-driven workflows (MCP builder)
• Platform overview: Workflow platform field guide