Schema Guide
Custom Types Schema - Comprehensive Guide
Core Concepts
The custom types system allows you to define complex data structures with validation, type safety, and nested relationships. Each custom type serves as a template for data that follows a specific structure.
Detailed Schema Structure
Base Schema
interface CustomTypeSchema {
name: string; // Name of the custom type
description: string; // Description of what this type represents
properties: Record<string, CustomJsonPropertyType>; // Field definitions
}Field Types In-Depth
1. String Fields
Used for text-based data.
{
"userName": {
"type": "string",
"description": "The user's display name in the system",
"required": true,
"title": "Username", // Optional display name
"default": "" // Optional default value
}
}Use Cases:
User names
Descriptions
Email addresses
Any text-based input
IDs or reference numbers
2. Number Fields
Used for numeric values, including both integers and decimals.
{
"temperature": {
"type": "number",
"description": "Temperature reading in Celsius",
"required": true,
"default": 0,
"title": "Temperature (°C)"
}
}Use Cases:
Measurements
Quantities
Scores or ratings
Financial values
Calculations
3. Object Fields
Used for grouping related fields together in a nested structure.
{
"address": {
"type": "object",
"description": "Physical address information",
"title": "Address Details",
"required": true,
"properties": {
"street": {
"type": "string",
"description": "Street address including number",
"required": true
},
"city": {
"type": "string",
"description": "City name",
"required": true
},
"postalCode": {
"type": "string",
"description": "Postal or ZIP code",
"required": true
},
"coordinates": {
"type": "location",
"description": "Geographic coordinates of the address"
}
}
}
}Use Cases:
Complex data structures
Grouped information
Nested data
Form sections
Related data points
4. Array Fields
Used for lists or collections of items.
{
"contactNumbers": {
"type": "array",
"description": "List of contact phone numbers",
"array_type": "string",
"title": "Contact Numbers"
},
"documents": {
"type": "array",
"description": "Collection of related documents",
"array_type": "file",
"fileType": "application/pdf",
"title": "Supporting Documents"
},
"addresses": {
"type": "array",
"description": "Multiple address entries",
"array_type": "object",
"properties": {
"type": {
"type": "string",
"description": "Type of address",
"enum": ["home", "work", "other"]
},
"address": {
"type": "object",
"description": "Address details",
"properties": {
"street": {
"type": "string",
"description": "Street address"
},
"city": {
"type": "string",
"description": "City name"
}
}
}
}
}
}Use Cases:
Multiple entries of the same type
Lists of items
Collections of documents
Multiple contact methods
Repeated data structures
5. Enum Fields
Used for fields with a fixed set of possible values.
{
"status": {
"type": "string",
"description": "Current status of the item",
"enum": ["draft", "review", "approved", "rejected"],
"default": "draft",
"title": "Status"
},
"priority": {
"type": "number",
"description": "Priority level",
"enum": [1, 2, 3, 4, 5],
"default": 3,
"title": "Priority Level"
}
}Use Cases:
Status indicators
Categories
Priority levels
Predefined options
State management
6. OneOf Fields
Used for fields that can have multiple different structures.
{
"notification": {
"type": "object",
"description": "Notification configuration",
"title": "Notification Settings",
"oneOf": [
{
"title": "Email Notification",
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Type of notification",
"default": "email"
},
"emailAddress": {
"type": "string",
"description": "Email address for notifications"
},
"frequency": {
"type": "string",
"description": "Notification frequency",
"enum": ["instant", "daily", "weekly"]
}
}
},
{
"title": "SMS Notification",
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Type of notification",
"default": "sms"
},
"phoneNumber": {
"type": "string",
"description": "Phone number for SMS"
},
"countryCode": {
"type": "string",
"description": "Country code for phone number"
}
}
}
]
}
}Use Cases:
Multiple possible configurations
Different types of the same concept
Conditional data structures
Variant handling
Flexible data models
7. File Fields
Used for file attachments and uploads.
{
"profilePicture": {
"type": "file",
"description": "User's profile picture",
"fileType": "image/jpeg",
"title": "Profile Picture"
},
"documentation": {
"type": "file",
"description": "Project documentation",
"fileType": "application/pdf",
"title": "Documentation"
}
}Use Cases:
Document uploads
Image attachments
File references
Media content
Data uploads
8. Location Fields
Used for geographic location data.
{
"projectSite": {
"type": "location",
"description": "Project site location",
"title": "Project Location",
"required": true
}
}Use Cases:
Geographic coordinates
Site locations
Address verification
Map integration
Location tracking
Validation and Requirements
Required Fields
Fields can be marked as required to ensure data completeness:
{
"fieldName": {
"type": "string",
"description": "Important field",
"required": true
}
}Description Requirements
Every field must have a description that explains:
Purpose of the field
Expected data
Any constraints or requirements
Usage context
Best Practices
Field Naming:
Use clear, descriptive names
Follow camelCase convention
Avoid special characters
Be consistent across similar fields
Descriptions:
Write clear, concise descriptions
Include any relevant constraints
Mention expected formats
Document any dependencies
Structure:
Group related fields in objects
Use arrays for collections
Keep nesting reasonable
Consider data access patterns
Validation:
Mark essential fields as required
Use enums for fixed options
Provide sensible defaults
Consider data integrity
Maintainability:
Document complex structures
Use consistent patterns
Consider future extensions
Keep it as simple as possible
This comprehensive guide should help in understanding and implementing custom types effectively in your system.
Last updated