Flow Input & Form

A Flow can prompt end users for data — text, numbers, checkboxes, and even file uploads — using a JSON Schema-based definition. When the user submits, their input becomes accessible throughout your Flow under $.input.

Defining the input schema

Within your Flow JSON, 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 "object". You can then nest any other types inside it.
• .properties: Each field uses standard JSON Schema rules (minLength, maxLength, minimum, maximum, etc.).
• required: Ensures the user must fill out certain fields before submitting.
• dataset: true: A special lensless field that turns the property into a file-upload widget.

JSON Schema validation

When a user runs a Flow:

1. lensless checks the posted input against the schema — it fails if required fields are missing or values are out of range.
2. For file fields (dataset), lensless ensures enough images are uploaded.
3. 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:

{
  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 set the required minimum/maximum number of images.
• lensless uploads the files as a new dataset and returns the dataset’s ID into this property.

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

Using input in steps

Once the user’s input is validated and stored under $.input, you can reference it anywhere in your step parameters:

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

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 generation',
        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.prompt',
          },
        ],
      },
    },
  ],
}

• 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 and prompt for 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 inputs, number fields, checkboxes, and file uploaders for dataset: true fields.
2. On submit, lensless uploads any images to create a dataset (if needed) and validates the JSON against the input schema.

Common errors and validation

• The root of the input schema must be of type object.
• Missing required fields prevent the user from submitting.
• Out-of-range min/max values show an error message (e.g., “At least 4 images”).
• Schema mismatches (invalid data shapes) are rejected by lensless.

Best practices

• Keep it simple — for a single field, you only need input: { type: "object", properties: { myField: {...} } }.
• Be descriptive — provide title, description, and placeholder for user-friendly prompts.
• Dataset fields — use dataset: true only for image/file inputs. Always specify min and max.
• Rely on built-in validation — JSON Schema validation ensures correct data shapes automatically.
• Private vs. public — the same input schema logic applies whether the Flow is public or run through the dashboard.