Generating from a schema

Both generators take a schema you already have and return a form definition that has already been validated against the bundled GolemUI schemas. They never invent fields silently: anything the mapper can’t handle is reported in unmapped.

From a JSON Schema

generate_from_json_schema maps a data-shape schema (an API request body, a Zod-derived schema, …) into widgets. Strings with a format become specialized widgets, numbers become number inputs, booleans become checkboxes, enums become selects, and required carries through to validators.

Call:

{
  "jsonSchema": {
    "type": "object",
    "properties": {
      "email": { "type": "string", "format": "email" },
      "age": { "type": "integer", "minimum": 18 },
      "newsletter": { "type": "boolean" }
    },
    "required": ["email"]
  }
}

Result:

{
  "formDefinition": {
    "$schema": "https://golemui.com/schemas/form.schema.json",
    "form": [
      {
        "kind": "input",
        "type": "textinput",
        "path": "email",
        "label": "Email",
        "validator": { "type": "string", "required": true, "format": "email" }
      },
      {
        "kind": "input",
        "type": "number",
        "path": "age",
        "label": "Age",
        "validator": { "type": "integer", "minimum": 18 }
      },
      {
        "kind": "input",
        "type": "checkbox",
        "path": "newsletter",
        "label": "Newsletter"
      },
      {
        "kind": "action",
        "type": "button",
        "actionType": "submit",
        "label": "Submit",
        "props": { "variant": "filled" }
      }
    ]
  },
  "unmapped": [],
  "validation": {
    "valid": true,
    "errors": [],
    "warnings": [],
    "expressionWarnings": []
  }
}

Append submitAction: false to omit the submit button, or set layout to horizontal or grid to change the top-level layout.

From an OpenAPI operation

generate_from_openapi resolves a single operation, dereferences its request-body $refs, and maps the body to a form. Pass the spec as a parsed document or a documentUrl, and name the operation as "METHOD /path" or an operationId.

Call:

{
  "operation": "POST /users",
  "document": { "...": "a parsed OpenAPI 3.x document" }
}

Result (for an operation whose body has name: string and role: enum):

{
  "resolvedOperation": { "method": "POST", "path": "/users" },
  "formDefinition": {
    "$schema": "https://golemui.com/schemas/form.schema.json",
    "form": [
      {
        "kind": "input",
        "type": "textinput",
        "path": "name",
        "label": "Name",
        "validator": { "type": "string", "required": true }
      },
      {
        "kind": "input",
        "type": "select",
        "path": "role",
        "label": "Role",
        "validator": { "type": "string", "enum": ["admin", "member"] },
        "props": {
          "options": [
            { "label": "Admin", "value": "admin" },
            { "label": "Member", "value": "member" }
          ]
        }
      },
      {
        "kind": "action",
        "type": "button",
        "actionType": "submit",
        "label": "Create user",
        "props": { "variant": "filled" }
      }
    ]
  },
  "unmapped": [],
  "validation": {
    "valid": true,
    "errors": [],
    "warnings": [],
    "expressionWarnings": []
  }
}

The submit button’s label defaults to the operation summary (here, “Create user”) or a verb derived from the HTTP method. When the operation has no JSON request body, the generator falls back to its parameters.

After generating

The output is already validated, but as soon as you edit a generated form — renaming a field, adding a state, tweaking a validator — run validate_form_definition again before handing it to the user.