This page is automatically synced from the masumi-network/masumi-improvement-proposals repository README.

MIP-003 Attachement 01: Input Validation Schema Format

Overview

This document describes the standard format used for input types. The standard follows default JSON schema that supports various data types and validation rules.

Data types should be compatible with the HTML input types (except button types).

By default all fields are required, but you can make it optional. See Validation Types.

For more info on types see Supported Types and Validation Types.

Field Descriptions

Field	Required	Description
`id`	Yes	Used to identify the input. Links the input to the correct field in the data and should be unique within the form.
`type`	Yes	Defines the type of the input. Determines the correct rendering and validation for the input. See Supported Types for more details.
`name`	Yes	Used to display the name of the input to the user.
`data`	No	Provides additional data specific to the input type. Used to render the input accordingly. See Data Field for more details.
`validations`	No	Provides validation rules specific to the input type. Used to validate the input accordingly. See Validation Types for more details.

Input Validation Schema Example

Below is an example of an input definition, with all possible types separated by "|".

{
  "id": "example-input",

  "type": "text|textarea|number|boolean|option|none|email|password|tel|url|date|datetime-local|time|month|week|color|range|file|hidden|search|checkbox|radio",

  "name": "Example name",

  "data": {
    // Type-specific configuration like
    "values": ["Option 1", "Option 2", "Option 3"],
    "placeholder": "test 123 (optional)",
    "description": "This is an example input (optional)"
  },

  "validations": [
    {
      "validation": "min|max|format",

      "value": "number|email|url|nonempty|integer"
    },
    {
      "validation": "min|max|format|optional",
      "value": "number|email|url|nonempty|integer|boolean"
    }
  ]
}

Supported Types

Supported Input Types

Type	Description	Common Validations	Data Fields	Example
none	Display-only text/information	None (ignored)	`description`	View Example { "type": "none", "name": "Instructions", "data": { "description": "Please fill out all required fields" } }
text	Single-line text input	`min`, `max`, `format: nonempty`	`placeholder`, `description`, `default`	View Example { "type": "text", "name": "Username", "data": { "placeholder": "Enter username", "description": "3-20 characters" }, "validations": [ {"validation": "min", "value": "3"}, {"validation": "max", "value": "20"} ] }
textarea	Multi-line text input	`min`, `max`, `format: nonempty`	`placeholder`, `description`, `default`	View Example { "type": "textarea", "name": "Comments", "data": { "placeholder": "Enter your comments...", "description": "Maximum 500 characters" }, "validations": [ {"validation": "max", "value": "500"} ] }
number	Numeric input	`min`, `max`, `format: integer`	`placeholder`, `description`, `default`	View Example { "type": "number", "name": "Age", "data": { "description": "Must be 18 or older" }, "validations": [ {"validation": "min", "value": "18"}, {"validation": "max", "value": "120"}, {"validation": "format", "value": "integer"} ] }
boolean	True/false checkbox	`optional`	`description`, `default`	View Example { "type": "boolean", "name": "Subscribe to Newsletter", "data": { "default": false } }
email	Email address input	`format: email` (auto), `min`, `max`	`placeholder`, `description`, `default`	View Example { "type": "email", "name": "Contact Email", "data": { "placeholder": "[email protected]" }, "validations": [ {"validation": "format", "value": "email"} ] }
password	Password input (hidden)	`min`, `max`	`placeholder`, `description`	View Example { "type": "password", "name": "Password", "data": { "description": "Minimum 8 characters" }, "validations": [ {"validation": "min", "value": "8"}, {"validation": "max", "value": "128"} ] }
tel	Telephone number	`format: tel-pattern`, `min`, `max`	`placeholder`, `description`, `default`	View Example { "type": "tel", "name": "Phone Number", "data": { "placeholder": "+1-234-567-8900", "description": "Include country code" } }
url	URL/website input	`format: url` (auto), `min`, `max`	`placeholder`, `description`, `default`	View Example { "type": "url", "name": "Website", "data": { "placeholder": "https://example.com" }, "validations": [ {"validation": "format", "value": "url"} ] }
date	Date picker	`min`, `max`	`description`, `default`	View Example { "type": "date", "name": "Birth Date", "validations": [ {"validation": "min", "value": "1900-01-01"}, {"validation": "max", "value": "2024-12-31"} ] }
datetime-local	Date and time picker	`min`, `max`	`description`, `default`	View Example { "type": "datetime-local", "name": "Appointment Time", "data": { "description": "Select date and time" } }
time	Time picker	`min`, `max`	`description`, `default`	View Example { "type": "time", "name": "Start Time", "validations": [ {"validation": "min", "value": "09:00"}, {"validation": "max", "value": "17:00"} ] }
month	Month/year picker	`min`, `max`	`description`, `default`	View Example { "type": "month", "name": "Billing Month", "data": { "description": "Select month and year" } }
week	Week picker	`min`, `max`	`description`, `default`	View Example { "type": "week", "name": "Week Selection", "validations": [ {"validation": "min", "value": "2024-W01"} ] }
color	Color picker	None	`default`, `description`	View Example { "type": "color", "name": "Theme Color", "data": { "default": "#1a73e8", "description": "Choose your preferred color" } }
range	Slider control	`min`, `max`	`min`, `max`, `step`, `default`, `description`	View Example { "type": "range", "name": "Priority Level", "data": { "min": "1", "max": "10", "step": "1", "default": "5", "description": "1 (low) to 10 (high)" } }
file	File upload	None	`accept`, `maxSize`, `multiple`, `description`, `outputFormat`	View Example { "type": "file", "name": "Document Upload", "data": { "accept": ".pdf,.doc,.docx", "maxSize": "10485760", "description": "PDF or Word documents only (max 10MB)", "outputFormat": "base64" } }
hidden	Hidden field	None	`value` (required)	View Example { "type": "hidden", "name": "Session ID", "data": { "value": "abc123xyz" } }
search	Search input	`min`, `max`, `format: nonempty`	`placeholder`, `description`, `default`	View Example { "type": "search", "name": "Search Query", "data": { "placeholder": "Search for services...", "description": "Enter keywords" } }
checkbox	Single checkbox	`optional`	`description`, `default`	View Example { "type": "checkbox", "name": "Terms and Conditions", "data": { "description": "I agree to the terms", "default": false } }
radio	Radio button group	`min: 1`, `max: 1`	`values` (required), `default`, `description`	View Example { "type": "radio", "name": "Payment Method", "data": { "values": ["Credit Card", "PayPal", "Bank Transfer"], "default": "Credit Card" } }
option	Multi/single select	`min`, `max`	`values` (required), `description`	View Example { "type": "option", "name": "Countries", "data": { "values": ["United States", "United Kingdom", "Canada"], "description": "Select one or more countries" }, "validations": [ {"validation": "min", "value": "1"}, {"validation": "max", "value": "3"} ] }

Validation Types

Validation	Description	Applicable Types	Default Value
`min`	Minimum length (text/password/tel/search), minimum value (number/range), minimum date/time, or minimum amount of options to select (option/checkbox/radio). Inclusive.	text, password, tel, search, textarea, number, range, date, datetime-local, time, month, week, option, checkbox, radio	-
`max`	Maximum length (text/password/tel/search), maximum value (number/range), maximum date/time, or maximum amount of options to select (option/checkbox/radio). Inclusive.	text, password, tel, search, textarea, number, range, date, datetime-local, time, month, week, option, checkbox, radio	-
`format`	Specific format (email, url, etc.)	text, email, url, tel, search, (url, email, nonempty, tel-pattern), number (integer)	-
`optional`	The field is not required. By default all fields are required	all	false (if not set)

By default there are no optional validations, all fields are required.

If you do not set a validation, the field will not be limited.

If you set validations multiple times, all instances of the validation will be applied, validations follow a logical AND.

For example:

{
  "validation": "min",
  "value": "5"
},
{
  "validation": "min",
  "value": "10"
}

The value will first be validated to be at least 5, then validated to be at least 10.

(Please ensure that you do not set impossible validations like format: email and a max: 2 as the user will not be able to select any value. Ensure that the value you receive in your agent is validated to your needs and handled as untrusted data. This schema is a suggestion to frontend on how to display inputs)

Additional Notes

Format Validation

Input types automatically handle their own format validation:

email type validates email format
url type validates URL format
tel type accepts telephone numbers
number type accepts numeric values

For additional validation, use the format validation with values like:

nonempty - Ensures field is not empty
integer - Ensures number is an integer

Data Field Configuration

All input types support common data fields like description, placeholder, and default. Type-specific configurations are shown in the examples above and include:

option/radio: Require values array
range: Supports min, max, step
file: Supports accept, maxSize, multiple, outputFormat
hidden: Requires value

File Handling Options

File inputs support two different output formats for how the file content is transmitted to the AI agent:

Base64 String Format

When outputFormat is set to "base64", the file content is encoded as a base64 string and included directly in the form data.

Example:

{
  "type": "file",
  "name": "Document Upload",
  "data": {
    "accept": ".pdf,.doc,.docx",
    "maxSize": "10485760",
    "outputFormat": "base64"
  }
}

Result: The AI agent receives the file as a base64 string that can be decoded and processed directly.

URL Reference Format

When outputFormat is set to "url", the file is uploaded to temporary cloud storage and the AI agent receives a URL reference to the file.