Data Models & Schema Documentation

Table of Contents

• Overview
• Core Models
• Request Models
• Response Models
• Enum Values
• Validation Rules
• Model Relationships
• JSON Schema Definitions

Overview

This document provides comprehensive documentation of all data models, DTOs (Data Transfer Objects), and schemas used in the Engagifii Training & Accreditation API. Understanding these models is crucial for successful API integration.

Data Type Conventions

Type	Format	Example	Description
guid	UUID v4	3fa85f64-5717-4562-b3fc-2c963f66afa6	Unique identifier
datetime	ISO 8601	2024-01-15T10:30:00Z	UTC timestamp
date	ISO 8601	2024-01-15	Date without time
decimal	Number	99.99	Monetary values
integer	Number	100	Whole numbers
boolean	Boolean	true / false	True/false values
string	Text	"Example text"	Text values
array	Array	["item1", "item2"]	List of items

Core Models

Award Model

Represents a certification, credential, or professional achievement.

interface Award {
  id: string;                    // GUID - Unique identifier
  name: string;                   // Required, max 200 chars
  description?: string;           // Optional, max 2000 chars
  levelTypeId?: string;           // GUID - Reference to level type
  levelType?: string;             // Display name of level
  objectTypeId?: string;          // GUID - Reference to object type
  objectType?: string;            // Display name of object type
  requirements?: string;          // Entry requirements, max 1000 chars
  price?: number;                 // Decimal(10,2), min: 0
  duration?: string;              // Duration description
  isActive: boolean;              // Default: true
  allowSelfRegistration: boolean; // Default: false
  requiresApproval: boolean;      // Default: true
  validityPeriod?: {
    years?: number;               // 0-99
    months?: number;              // 0-11
    days?: number;                // 0-365
  };
  tags?: string[];                // Array of tag names
  skills?: string[];              // Array of skill names
  iconUrl?: string;               // URL to icon image
  hexNameColor?: string;          // Hex color code (e.g., "#FF5733")
  createdDate: string;            // ISO 8601 datetime
  createdBy?: string;             // GUID - User who created
  modifiedDate?: string;          // ISO 8601 datetime
  modifiedBy?: string;            // GUID - User who modified
  tenantCode: string;             // Tenant identifier
}

Class Model

Represents a scheduled training session or educational event.

interface Class {
  id: string;                     // GUID - Unique identifier
  name: string;                   // Required, max 200 chars
  description?: string;           // Optional, max 2000 chars
  courseId: string;               // GUID - Parent course
  courseName?: string;            // Display name of course
  startDate: string;              // ISO 8601 datetime, required
  endDate: string;                // ISO 8601 datetime, required
  locationId?: string;            // GUID - Physical location
  locationName?: string;          // Display name of location
  locationType: LocationType;     // Enum: InPerson, Virtual, Hybrid
  virtualMeetingUrl?: string;     // URL for virtual sessions
  instructorId?: string;          // GUID - Primary instructor
  instructorName?: string;        // Display name of instructor
  capacity: number;               // Maximum attendees, min: 1
  enrolled: number;               // Current enrollment count
  availableSeats: number;         // Calculated: capacity - enrolled
  waitlistCapacity?: number;      // Max waitlist size
  waitlistCount?: number;         // Current waitlist count
  status: ClassStatus;            // Enum: Draft, Published, InProgress, Completed, Cancelled
  price?: number;                 // Decimal(10,2), min: 0
  registrationStartDate?: string; // ISO 8601 datetime
  registrationEndDate?: string;   // ISO 8601 datetime
  allowWaitlist: boolean;         // Default: false
  requiresApproval: boolean;      // Default: false
  sessions?: ClassSession[];      // Array of session details
  materials?: CourseMaterial[];   // Array of class materials
  isActive: boolean;              // Default: true
  createdDate: string;            // ISO 8601 datetime
  modifiedDate?: string;          // ISO 8601 datetime
  tenantCode: string;             // Tenant identifier
}

Course Model

Represents an educational program or training curriculum.

interface Course {
  id: string;                     // GUID - Unique identifier
  name: string;                   // Required, max 200 chars
  code?: string;                  // Course code, max 50 chars
  description?: string;           // Short description, max 500 chars
  detailedDescription?: string;   // Full description, max 5000 chars
  objectives?: string[];          // Learning objectives
  curriculum?: CurriculumModule[];// Structured curriculum
  category?: string;              // Course category
  subcategory?: string;           // Course subcategory
  duration?: string;              // Duration description
  durationHours?: number;         // Duration in hours
  credits?: number;               // Credit value, decimal(5,2)
  creditTypeId?: string;          // GUID - Type of credit
  level?: CourseLevel;            // Enum: Beginner, Intermediate, Advanced, Expert
  prerequisites?: string[];       // List of prerequisites
  targetAudience?: string;        // Target audience description
  instructors?: string[];         // List of instructor names
  materials?: string[];           // List of required materials
  assessmentMethod?: string;      // Assessment description
  passingScore?: number;          // Minimum passing score (0-100)
  certificateOffered: boolean;    // Default: false
  price?: number;                 // Decimal(10,2), min: 0
  tags?: string[];                // Array of tags
  skills?: string[];              // Skills developed
  isActive: boolean;              // Default: true
  createdDate: string;            // ISO 8601 datetime
  modifiedDate?: string;          // ISO 8601 datetime
  tenantCode: string;             // Tenant identifier
}

Person/Member Model

Represents a user or member in the system.

interface Person {
  id: string;                     // GUID - Unique identifier
  firstName: string;              // Required, max 100 chars
  middleName?: string;            // Optional, max 100 chars
  lastName: string;               // Required, max 100 chars
  displayName?: string;           // Computed or custom display name
  email: string;                  // Required, valid email format
  secondaryEmail?: string;        // Optional secondary email
  phone?: string;                 // Phone number
  mobile?: string;                // Mobile number
  title?: string;                 // Job title, max 200 chars
  department?: string;            // Department name
  employeeId?: string;            // Employee identifier
  organizationId?: string;        // GUID - Primary organization
  organizationName?: string;      // Display name of organization
  managerI

d?: string;            // GUID - Manager reference
  managerName?: string;           // Display name of manager
  address?: Address;              // Address object
  dateOfBirth?: string;           // ISO 8601 date
  gender?: Gender;                // Enum: Male, Female, Other, PreferNotToSay
  ethnicity?: string;             // Ethnicity information
  bio?: string;                   // Biography, max 2000 chars
  profileImageUrl?: string;       // URL to profile image
  isActive: boolean;              // Default: true
  joinDate?: string;              // ISO 8601 date
  terminationDate?: string;       // ISO 8601 date
  customFields?: Record<string, any>; // Dynamic custom fields
  tags?: string[];                // Array of tags
  createdDate: string;            // ISO 8601 datetime
  modifiedDate?: string;          // ISO 8601 datetime
  tenantCode: string;             // Tenant identifier
}

Organization Model

Represents an organization or company.

interface Organization {
  id: string;                     // GUID - Unique identifier
  name: string;                   // Required, max 200 chars
  code?: string;                  // Organization code
  type?: OrganizationType;        // Enum: Corporate, Educational, Government, NonProfit, Other
  parentOrganizationId?: string;  // GUID - Parent org for hierarchy
  parentOrganizationName?: string;// Display name of parent
  description?: string;           // Organization description
  website?: string;               // Organization website URL
  address?: Address;              // Primary address
  phone?: string;                 // Main phone number
  email?: string;                 // Main contact email
  taxId?: string;                 // Tax identification number
  registrationNumber?: string;    // Business registration
  industryType?: string;          // Industry classification
  size?: OrganizationSize;        // Enum: Small, Medium, Large, Enterprise
  employeeCount?: number;         // Number of employees
  foundedDate?: string;           // ISO 8601 date
  logoUrl?: string;               // URL to logo image
  primaryContactId?: string;      // GUID - Primary contact person
  billingAddress?: Address;       // Billing address
  isActive: boolean;              // Default: true
  customFields?: Record<string, any>; // Dynamic custom fields
  createdDate: string;            // ISO 8601 datetime
  modifiedDate?: string;          // ISO 8601 datetime
  tenantCode: string;             // Tenant identifier
}

Request Models

Registration Request

Used for class or award registration.

interface RegistrationRequest {
  objectId: string;               // GUID - Class or Award ID
  objectType: 'Class' | 'Award';  // Type of registration
  memberId: string;               // GUID - Member being registered
  registrationType: RegistrationType; // Enum: Self, Manager, Admin
  justification?: string;         // Reason for registration
  managerApproval?: boolean;      // Pre-approved by manager
  skipApproval?: boolean;         // Admin override
  paymentMethod?: PaymentMethod;  // Enum: CreditCard, PurchaseOrder, Invoice, Free
  purchaseOrderNumber?: string;   // PO number if applicable
  billingContactId?: string;      // GUID - Billing contact
  specialRequirements?: string;   // Special needs/requirements
  dietaryRestrictions?: string;   // For in-person events
  accessibilityNeeds?: string;    // Accessibility requirements
  notes?: string;                 // Additional notes
  customFields?: Record<string, any>; // Custom registration fields
}

Credit Request

Used to request external training credits.

interface CreditRequest {
  memberId: string;               // GUID - Member requesting credits
  creditTypeId: string;           // GUID - Type of credit
  creditsRequested: number;       // Number of credits, decimal(5,2)
  activityName: string;           // Required, max 200 chars
  activityDate: string;           // ISO 8601 date
  provider: string;               // Training provider name
  providerType?: ProviderType;    // Enum: Internal, External, Online, Conference
  description?: string;           // Activity description
  location?: string;              // Where activity took place
  certificateNumber?: string;     // External certificate number
  expirationDate?: string;        // ISO 8601 date
  supportingDocuments?: Document[]; // Array of supporting docs
  managerApproval?: boolean;      // Manager pre-approval
  autoApprove?: boolean;          // Auto-approve if criteria met
  notes?: string;                 // Additional notes
}

Approval Request

Used for approval workflow operations.

interface ApprovalRequest {
  requestId: string;              // GUID - Request being approved
  requestType: RequestType;       // Enum: Registration, Credit, Award
  action: ApprovalAction;         // Enum: Approve, Reject, RequestInfo
  approverId: string;             // GUID - Person approving
  comments?: string;              // Approval comments
  conditions?: string[];          // Conditional approval terms
  delegatedFrom?: string;         // GUID - If delegated approval
  expirationDate?: string;        // Approval expiration
  attachments?: Document[];       // Supporting documents
}

Filter Request

Used for paginated list queries.

interface FilterRequest<T> {
  page?: number;                  // Page number (1-based), default: 1
  pageSize?: number;              // Items per page, default: 50, max: 200
  sortBy?: keyof T;               // Field to sort by
  sortDirection?: 'asc' | 'desc'; // Sort direction, default: 'asc'
  filters?: FilterCriteria[];     // Array of filter conditions
  searchTerm?: string;            // Global search term
  includeInactive?: boolean;      // Include inactive records
  dateRange?: {
    startDate?: string;           // ISO 8601 datetime
    endDate?: string;             // ISO 8601 datetime
  };
  tags?: string[];                // Filter by tags
  customFilters?: Record<string, any>; // Custom filter fields
}

interface FilterCriteria {
  field: string;                  // Field name to filter
  operator: FilterOperator;       // Comparison operator
  value: any;                     // Value to compare
  dataType?: 'string' | 'number' | 'date' | 'boolean';
}

type FilterOperator = 
  | 'equals' 
  | 'notEquals' 
  | 'contains' 
  | 'startsWith' 
  | 'endsWith'
  | 'greaterThan' 
  | 'lessThan' 
  | 'greaterThanOrEqual' 
  | 'lessThanOrEqual'
  | 'between' 
  | 'in' 
  | 'notIn' 
  | 'isNull' 
  | 'isNotNull';

Response Models

Paginated Response

Standard response for paginated lists.

interface PaginatedResponse<T> {
  items: T[];                     // Array of items
  totalCount: number;             // Total items available
  page: number;                   // Current page number
  pageSize: number;               // Items per page
  pageCount: number;              // Total pages
  hasNextPage: boolean;           // More pages available
  hasPreviousPage: boolean;       // Previous pages available
  sortBy?: string;                // Sort field used
  sortDirection?: string;         // Sort direction used
  filters?: FilterCriteria[];     // Active filters
}

Operation Response

Standard response for operations.

interface OperationResponse {
  success: boolean;               // Operation success status
  message?: string;               // User-friendly message
  data?: any;                     // Operation result data
  errors?: ValidationError[];     // Validation errors if any
  warnings?: string[];            // Warning messages
  reference?: string;             // Reference number/ID
  timestamp: string;              // ISO 8601 datetime
}

Validation Error

Detailed validation error information.

interface ValidationError {
  field: string;                  // Field that failed validation
  code: string;                   // Error code
  message: string;                // Error message
  value?: any;                    // Submitted value
  constraints?: {
    [key: string]: any;           // Validation constraints
  };
}

Statistics Response

Response for statistical queries.

interface StatisticsResponse {
  periodStart: string;            // ISO 8601 datetime
  periodEnd: string;              // ISO 8601 datetime
  metrics: {
    [key: string]: number;        // Metric name and value
  };
  breakdown?: {
    byCategory?: Record<string, number>;
    byStatus?: Record<string, number>;
    byOrganization?: Record<string, number>;
    byTime?: TimeSeriesData[];
  };
  comparisons?: {
    previousPeriod?: number;       // % change from previous
    yearOverYear?: number;         // % change from last year
  };
}

Enum Values

Registration Status

enum RegistrationStatus {
  Draft = "Draft",
  Submitted = "Submitted",
  PendingApproval = "PendingApproval",
  Approved = "Approved",
  Rejected = "Rejected",
  Registered = "Registered",
  Waitlisted = "Waitlisted",
  Cancelled = "Cancelled",
  Completed = "Completed",
  NoShow = "NoShow",
  Withdrawn = "Withdrawn"
}

Class Status

enum ClassStatus {
  Draft = "Draft",
  Published = "Published",
  RegistrationOpen = "RegistrationOpen",
  RegistrationClosed = "RegistrationClosed",
  InProgress = "InProgress",
  Completed = "Completed",
  Cancelled = "Cancelled",
  Postponed = "Postponed"
}

Location Type

enum LocationType {
  InPerson = "InPerson",
  Virtual = "Virtual",
  Hybrid = "Hybrid",
  OnDemand = "OnDemand",
  SelfPaced = "SelfPaced"
}

Course Level

enum CourseLevel {
  Beginner = "Beginner",
  Intermediate = "Intermediate",
  Advanced = "Advanced",
  Expert = "Expert",
  AllLevels = "AllLevels"
}

Payment Method

enum PaymentMethod {
  CreditCard = "CreditCard",
  DebitCard = "DebitCard",
  PurchaseOrder = "PurchaseOrder",
  Invoice = "Invoice",
  Check = "Check",
  WireTransfer = "WireTransfer",
  Free = "Free",
  Scholarship = "Scholarship",
  CompanyPaid = "CompanyPaid"
}

Approval Action

enum ApprovalAction {
  Approve = "Approve",
  Reject = "Reject",
  RequestInformation = "RequestInformation",
  Delegate = "Delegate",
  Escalate = "Escalate",
  Hold = "Hold",
  Cancel = "Cancel"
}

Credit Type

enum CreditType {
  CPE = "CPE",        // Continuing Professional Education
  CEU = "CEU",        // Continuing Education Unit
  PDH = "PDH",        // Professional Development Hour
  CLE = "CLE",        // Continuing Legal Education
  CME = "CME",        // Continuing Medical Education
  CE = "CE",          // Continuing Education
  Custom = "Custom"   // Organization-specific
}

Validation Rules

Common Validation Rules

Field Type	Rule	Description
Email	RFC 5322	Valid email format
Phone	E.164 or local	Valid phone format
URL	RFC 3986	Valid URL format
Date	ISO 8601	YYYY-MM-DD format
DateTime	ISO 8601	YYYY-MM-DDTHH:mm:ssZ
GUID	UUID v4	Valid GUID format
Currency	Decimal(10,2)	Max 10 digits, 2 decimal places

Field-Specific Rules

Name Fields

• Required: Yes (firstName, lastName)
• Min Length: 1 character
• Max Length: 100 characters
• Pattern: Letters, spaces, hyphens, apostrophes
• Example: "John", "O'Brien", "Smith-Johnson"

Description Fields

• Required: Varies by context
• Max Length: 2000-5000 characters
• HTML: Stripped or sanitized
• Line Breaks: Preserved

Numeric Fields

• Credits: 0-999.99
• Capacity: 1-9999
• Price: 0-999999.99
• Percentage: 0-100
• Score: 0-100

Date Validations

• Future Dates: Required for registration end dates
• Past Dates: Required for historical records
• Date Ranges: End date must be after start date
• Business Days: Some operations only on weekdays

Model Relationships

Entity Relationship Diagram

┌─────────────┐        ┌─────────────┐        ┌─────────────┐
│   Person    │────────│Registration │────────│    Class    │
└─────────────┘        └─────────────┘        └─────────────┘
       │                      │                       │
       │                      │                       │
       ▼                      ▼                       ▼
┌─────────────┐        ┌─────────────┐        ┌─────────────┐
│Organization │        │   Approval  │        │   Course    │
└─────────────┘        └─────────────┘        └─────────────┘
       │                                             │
       │                                             │
       ▼                                             ▼
┌─────────────┐                              ┌─────────────┐
│   Awards    │──────────────────────────────│   Credits   │
└─────────────┘                              └─────────────┘

Relationship Descriptions

1. Person → Organization: Many-to-One

   • A person belongs to one primary organization
   • Organizations can have multiple people

2. Person → Registration: One-to-Many

   • A person can have multiple registrations
   • Each registration belongs to one person

3. Registration → Class/Award: Many-to-One

   • Multiple registrations per class/award
   • Each registration is for one class or award

4. Class → Course: Many-to-One

   • Multiple classes can be scheduled for a course
   • Each class is based on one course

5. Award → Credits: One-to-Many

   • Awards can grant multiple credit types
   • Credits are associated with specific awards

6. Registration → Approval: One-to-Many

   • Registrations may require multiple approvals
   • Each approval is for one registration

JSON Schema Definitions

Award Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.engagifii.com/schemas/award.json",
  "type": "object",
  "title": "Award",
  "required": ["name", "tenantCode"],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "readOnly": true
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "description": {
      "type": "string",
      "maxLength": 2000
    },
    "levelTypeId": {
      "type": "string",
      "format": "uuid"
    },
    "price": {
      "type": "number",
      "minimum": 0,
      "maximum": 999999.99,
      "multipleOf": 0.01
    },
    "isActive": {
      "type": "boolean",
      "default": true
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 50
      },
      "maxItems": 20
    },
    "validityPeriod": {
      "type": "object",
      "properties": {
        "years": {
          "type": "integer",
          "minimum": 0,
          "maximum": 99
        },
        "months": {
          "type": "integer",
          "minimum": 0,
          "maximum": 11
        },
        "days": {
          "type": "integer",
          "minimum": 0,
          "maximum": 365
        }
      }
    },
    "createdDate": {
      "type": "string",
      "format": "date-time",
      "readOnly": true
    },
    "tenantCode": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    }
  },
  "additionalProperties": false
}

Registration Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.engagifii.com/schemas/registration.json",
  "type": "object",
  "title": "Registration",
  "required": ["objectId", "objectType", "memberId"],
  "properties": {
    "objectId": {
      "type": "string",
      "format": "uuid"
    },
    "objectType": {
      "type": "string",
      "enum": ["Class", "Award"]
    },
    "memberId": {
      "type": "string",
      "format": "uuid"
    },
    "registrationType": {
      "type": "string",
      "enum": ["Self", "Manager", "Admin"],
      "default": "Self"
    },
    "justification": {
      "type": "string",
      "maxLength": 1000
    },
    "paymentMethod": {
      "type": "string",
      "enum": [
        "CreditCard",
        "PurchaseOrder",
        "Invoice",
        "Free"
      ]
    },
    "specialRequirements": {
      "type": "string",
      "maxLength": 500
    },
    "customFields": {
      "type": "object",
      "additionalProperties": true
    }
  }
}

Data Validation Examples

Valid Award Creation Request

{
  "name": "Advanced Project Management Certification",
  "description": "Comprehensive certification for experienced project managers",
  "levelTypeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "objectTypeId": "7ba85f64-5717-4562-b3fc-2c963f66afa8",
  "price": 599.99,
  "duration": "6 months",
  "isActive": true,
  "allowSelfRegistration": true,
  "requiresApproval": true,
  "validityPeriod": {
    "years": 2,
    "months": 0,
    "days": 0
  },
  "tags": ["project-management", "advanced", "certification"],
  "skills": ["leadership", "risk-management", "budgeting", "scheduling"]
}

Invalid Award Creation Request

{
  "name": "",  // ❌ Empty name
  "description": "...", // String with 3000+ characters ❌ Exceeds max length
  "price": -100,  // ❌ Negative price
  "validityPeriod": {
    "years": 150,  // ❌ Exceeds maximum (99)
    "months": 15,  // ❌ Exceeds maximum (11)
    "days": 400    // ❌ Exceeds maximum (365)
  },
  "tags": [
    // Array with 25+ items ❌ Exceeds maximum (20)
  ],
  "tenantCode": null  // ❌ Required field missing
}

Validation Error Response

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "name",
      "code": "REQUIRED",
      "message": "Name is required",
      "value": ""
    },
    {
      "field": "description",
      "code": "MAX_LENGTH",
      "message": "Description must not exceed 2000 characters",
      "value": "...",
      "constraints": {
        "maxLength": 2000,
        "actualLength": 3000
      }
    },
    {
      "field": "price",
      "code": "MIN_VALUE",
      "message": "Price must be greater than or equal to 0",
      "value": -100,
      "constraints": {
        "minimum": 0
      }
    }
  ]
}

Custom Fields

The API supports dynamic custom fields for extensibility.

Custom Field Definition

interface CustomField {
  key: string;                    // Field identifier
  label: string;                  // Display label
  type: CustomFieldType;          // Data type
  required: boolean;              // Is required
  defaultValue?: any;             // Default value
  validation?: {
    pattern?: string;             // Regex pattern
    min?: number;                 // Minimum value/length
    max?: number;                 // Maximum value/length
    options?: any[];              // Valid options for select
  };
  visibility?: {
    roles?: string[];             // Visible to roles
    conditions?: any;             // Conditional visibility
  };
}

enum CustomFieldType {
  Text = "text",
  Number = "number",
  Date = "date",
  Boolean = "boolean",
  Select = "select",
  MultiSelect = "multiselect",
  File = "file",
  Url = "url",
  Email = "email",
  Phone = "phone"
}

Custom Field Usage Example

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "customFields": {
    "employeeLevel": "Senior",
    "certificationNumber": "CERT-2024-001",
    "specialization": ["Cloud", "Security"],
    "emergencyContact": {
      "name": "Jane Doe",
      "phone": "+1-555-0100",
      "relationship": "Spouse"
    }
  }
}

Best Practices

1. Always Validate Input

• Validate data client-side before sending
• Handle server validation errors gracefully
• Display user-friendly error messages

2. Use Appropriate Data Types

• Use GUIDs for identifiers
• Use ISO 8601 for dates/times
• Use proper decimal precision for money

3. Handle Optional Fields

• Check for null/undefined values
• Provide sensible defaults
• Document required vs optional clearly

4. Version Your Models

• Plan for backward compatibility
• Use versioning for breaking changes
• Maintain deprecated fields temporarily

5. Consistent Naming

• Use camelCase for JSON properties
• Use PascalCase for enum values
• Keep naming consistent across models

---

For implementation examples and integration patterns, see the API Reference documentation.