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

1. Field Naming:

   • Use clear, descriptive names

   • Follow camelCase convention

   • Avoid special characters

   • Be consistent across similar fields

2. Descriptions:

   • Write clear, concise descriptions

   • Include any relevant constraints

   • Mention expected formats

   • Document any dependencies

3. Structure:

   • Group related fields in objects

   • Use arrays for collections

   • Keep nesting reasonable

   • Consider data access patterns

4. Validation:

   • Mark essential fields as required

   • Use enums for fixed options

   • Provide sensible defaults

   • Consider data integrity

5. 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.