Skip to Content
FlowsFlow Input & Form

Flow Input & Form

A Flow can prompt end users for data — inputs, checkboxes, and even file uploads — using a JSON Schema–based definition. When the user submits that input, it becomes accessible in your Flow under $.input.

Defining the Input Schema

Within your Flow JSON, you can include a top-level input object:

{
  "title": "Example Flow",
  "description": "Demonstrating user input",
  "input": {
    "type": "object",
    "required": ["userDatasetId"],
    "properties": {
      "prompt": {
        "type": "string",
        "title": "Enter a style or theme",
        "placeholder": "space opera with vibrant colors",
        "minLength": 4,
        "maxLength": 500
      },
      "userDatasetId": {
        "type": "string",
        "title": "Your photos",
        "description": "At least 4 images of you in different poses",
        "dataset": true,
        "min": 4,
        "max": 20
      }
    }
  },
  "steps": [...],
  ...
}

Key Points:

  • input.type: The root type MUST always be of type "object". Then you can nest it with any other type.
  • .properties: Each field is declared with typical JSON Schema rules (minLength, maxLength, etc.).
  • required: Ensures the user must fill out certain fields.
  • dataset: true: Special lensless field indicating a file-upload widget.

JSON Schema Validation

When a user runs a Flow:

  1. lensless checks the posted input against the schema:
  • Fails if required fields are missing or out of range.
  • For file fields (dataset), lensless ensures enough images are uploaded, etc.
  1. If valid, the input is stored in the Flow’s execution state as $.input.

File Uploads (Datasets)

If a property has "dataset": true, the front-end automatically presents a file uploader. For example:

{
  userDatasetId: {
    type: 'string',
    title: 'Your photos',
    dataset: true,
    description: 'At least 4 images of you in different poses',
    min: 4,
    max: 20,
  },
}
  • dataset fields MUST have "type": "string"
  • min and max: The required minimum/maximum number of images.
  • The user can see a file uploader and add images.
  • lensless uploads them as a new dataset, returning the dataset’s ID into this property.

You can then reference "$.input.userDatasetId" in later steps, like ModelGenerator.datasetId.

Using Input in Steps

When the user’s input is validated and stored under $.input, you can later reference them. E.g:

  • In ObjectGenerator, reference "$.input.prompt".
  • In ModelGenerator, reference "$.input.userDatasetId" as datasetId.
  • In ImageGenerator, reference "$.input.width" or any other numeric field to control generation dimensions, etc.

These property names (prompt, userDatasetId, etc) are just examples. You can use any name you want.

Example Flow with Input

{
  title: 'Generate Avatars',
  description: 'Upload your photos and pick a style to generate custom avatars',
  public: true,
  input: {
    type: 'object',
    required: ['photos', 'prompt'],
    properties: {
      photos: {
        type: 'string',
        dataset: true,
        title: 'Upload your photos',
        min: 6,
        max: 20,
      },
      prompt: {
        type: 'string',
        title: 'Desired prompt for image gineration',
        placeholder: 'Cartoon character of a person with a hoodie',
      },
    },
  },
  steps: [
    {
      id: 'training',
      type: 'ModelGenerator',
      parameters: {
        datasetId: '$.input.photos',
        settings: {
          baseModel: 'stable-diffusion-v1-5',
          epochs: 40,
        },
      },
    },
    {
      id: 'avatarGeneration',
      type: 'ImageGenerator',
      parameters: {
        trainingId: '$.results.training.id',
        images: [
          {
            prompt: '$.input.style',
          },
        ],
      },
    },
  ],
}
  • photos: A dataset field for uploading images.
  • prompt: A text field for the user’s desired style.
  • The Flow references those in the steps:
  • datasetId for model training.
  • prompt in image generation.

Front-End Form

When a user visits a public Flow page:

  1. lensless automatically renders a form based on the Flow’s input schema:
  • text/number/checkbox/radio/etc inputs for standard fields.
  • File uploaders for fields with "dataset": true.
  1. On submit, lensless:
  • Uploads any images to create a dataset (if needed).
  • Validates the JSON schema of the input against the input schema defined in the flow object.

Common Errors & Validation

  • The root of the input schema MUST be of type object.
  • “required” fields missing => The user is prevented from submitting the form.
  • Out-of-range for min/max => The form shows an error message (e.g. “At least 4 images”).
  • File uploads => If the user uploads fewer or more than allowed images, the submission is blocked or throws an error.
  • Schema Mismatch => If an advanced user tries to manipulate the form or send invalid data, lensless rejects the input.

Best Practices

  1. Keep it Simple: For a single field, you only need input: { type: "object", properties: { myField: {...} } }.
  2. Descriptive: Provide title, description, placeholder for user-friendly prompts.
  3. Dataset Fields: Use dataset: true only for images or file inputs. Always specify min and max.
  4. Validation: Rely on the built-in JSON schema validation to ensure correct data shapes.
  5. Private vs. Public: A private Flow’s form is typically not exposed publicly, but the same input schema logic applies if you run it through the dashboard or by calling it programmatically.
Last updated on