Date Component

A component for date and time values. When you see "kind": "date" in a component, it represents a date input field that can include time, display as actual dates or calculated ages, and enforce date range or age restrictions.

Understanding Date Component Fields

When reading a date component in the schema, you'll see these fields:

Field	Type	Required	Description
id	string	Yes	Unique identifier for this date field
kind	string	Yes	Always "date" for date components
metadata	object	No	Component-specific metadata
metadata.withTime	boolean	No	If true, includes time input
metadata.displayAs	string	No	Display format: "date" or "age"
rules	object	No	Validation rules
rules.required	boolean	No	If true, the field must be provided
rules.minDate	string	No	Minimum allowed date (ISO 8601)
rules.maxDate	string	No	Maximum allowed date (ISO 8601)
rules.minAge	number	No	Minimum age in years
rules.maxAge	number	No	Maximum age in years

Reading Metadata

metadata.withTime

• What it means: When true, the date input should include time selection (hours, minutes, seconds). When false or missing, only the date is captured
• How to use: Render a date-time picker if true, date-only picker if false
• Default: false (date only)

metadata.displayAs

• What it means: Controls how the date is displayed to users
  • "date": Show the actual date (e.g., "1990-01-15")
  • "age": Show the calculated age from the date (e.g., "34 years old")
• How to use: Calculate and display age if "age", show date if "date" or missing
• Default: "date"

Understanding Validation Rules

rules.required

• What it means: If true, the user must provide a date. Validation fails if the field is empty or null
• How to use: Mark the field as required in your form UI

rules.minDate / rules.maxDate

• What it means: Defines the allowed date range. Dates must be in ISO 8601 format
• Format: YYYY-MM-DD (date only) or YYYY-MM-DDTHH:mm:ssZ (with time)
• How to use: Set minimum/maximum selectable dates in your date picker
• Note: Can be combined with age rules, but age rules are more common for birth dates

rules.minAge / rules.maxAge

• What it means: Defines the allowed age range in years. Age is calculated from the selected date to the current date
• How to use: Calculate age from the selected date and validate it's within the range
• Common use: Birth dates often use age rules instead of date rules for better UX
• Example: If minAge: 18, the person must be at least 18 years old

Date Format

All date values in the schema use ISO 8601 format:

• Date only: YYYY-MM-DD (e.g., "1990-01-15")
• Date with time: YYYY-MM-DDTHH:mm:ssZ (e.g., "1990-01-15T10:30:00Z")

When working with date components, ensure your date picker outputs and accepts dates in this format.

Example: Reading a Birth Date Component

{
  "id": "birthDate",
  "kind": "date",
  "metadata": {
    "displayAs": "age"
  },
  "rules": {
    "required": true,
    "minAge": 18,
    "maxAge": 80
  },
  "lockedAfterEdit": true
}

What this tells you:

• Field ID is "birthDate" - use this to reference the field
• Display as age (calculate and show "X years old" instead of the date)
• Date only (no time, since withTime is not set)
• Field is required
• User must be between 18 and 80 years old
• Field is locked after first edit

Example: Reading an Event Date Component

{
  "id": "eventDate",
  "kind": "date",
  "metadata": {
    "withTime": true,
    "displayAs": "date"
  },
  "rules": {
    "required": true,
    "minDate": "2025-01-01",
    "maxDate": "2025-12-31"
  }
}

What this tells you:

• Field ID is "eventDate"
• Include time selection (withTime: true)
• Display as actual date
• Field is required
• Date must be between January 1, 2025 and December 31, 2025