Data Models & Schema Documentation

Table of Contents

• Core Models
• Activity Models
• Advocacy Models
• Bill Models
• Capitol Report Models
• Common Models
• Validation Rules
• Enumerations

Core Models

Bill

The primary bill entity containing legislative information.

interface Bill {
  id: number;                    // Unique bill identifier
  billNumber: string;             // Official bill number (e.g., "HB1234")
  title: string;                  // Bill title
  summary?: string;               // Bill summary/description
  stateId: number;                // State identifier
  sessionId: number;              // Legislative session ID
  chamberId: number;              // Chamber ID (House/Senate)
  status: string;                 // Current bill status
  introducedDate?: string;        // ISO 8601 date format
  lastActionDate?: string;        // ISO 8601 date format
  lastAction?: string;            // Description of last action
  sponsorId?: number;             // Primary sponsor ID
  committeeIds?: number[];        // Associated committee IDs
  trackingStatus?: TrackingStatus; // Client-specific tracking
  position?: BillPosition;        // Organization's position
  priority?: Priority;            // Priority level
  tags?: string[];                // Custom tags
  metadata?: object;              // Additional custom data
  createdAt: string;              // ISO 8601 timestamp
  updatedAt: string;              // ISO 8601 timestamp
}

State

State information for legislative tracking.

interface State {
  id: number;                     // State identifier
  name: string;                   // Full state name
  abbreviation: string;           // Two-letter abbreviation
  isActive: boolean;              // Whether state is active
  timezone?: string;              // State timezone
  legislatureType?: string;       // Type of legislature
  sessionSchedule?: string;       // Session schedule description
}

Session

Legislative session information.

interface Session {
  id: number;                     // Session identifier
  stateId: number;                // Associated state ID
  name: string;                   // Session name
  year: number;                   // Session year
  type: SessionType;              // Regular/Special/Extraordinary
  startDate: string;              // ISO 8601 date
  endDate?: string;               // ISO 8601 date
  isActive: boolean;              // Whether session is active
  isCurrent: boolean;             // Whether this is current session
}

Committee

Legislative committee information.

interface Committee {
  id: number;                     // Committee identifier
  name: string;                   // Committee name
  displayName?: string;           // Display name
  chamber: Chamber;               // House/Senate/Joint
  stateId: number;                // State identifier
  parentId?: number;              // Parent committee ID
  type?: string;                  // Committee type
  jurisdiction?: string;          // Committee jurisdiction
  meetingSchedule?: string;       // Regular meeting schedule
  room?: string;                  // Meeting room
  building?: string;              // Building location
  phone?: string;                 // Contact phone
  email?: string;                 // Contact email
  url?: string;                   // Committee website
  isActive: boolean;              // Whether committee is active
}

PublicOfficial

Legislator and public official information.

interface PublicOfficial {
  id: number;                     // Official identifier
  firstName: string;              // First name
  middleName?: string;            // Middle name
  lastName: string;               // Last name
  fullName: string;               // Computed full name
  title?: string;                 // Official title
  party?: string;                 // Political party
  chamber?: Chamber;              // House/Senate
  district?: string;              // District number
  districtName?: string;          // District name
  stateId: number;                // State identifier
  email?: string;                 // Contact email
  phone?: string;                 // Contact phone
  officeAddress?: Address;        // Office address
  profileImageUrl?: string;       // Profile image URL
  biography?: string;             // Biography text
  committees?: CommitteeAssignment[]; // Committee assignments
  socialMedia?: SocialMedia;      // Social media links
  votingRecord?: VotingRecord;    // Voting statistics
  isActive: boolean;              // Whether official is active
  termStart?: string;             // Term start date
  termEnd?: string;               // Term end date
}

Activity Models

ActivityLogModel

Activity logging for audit trails.

interface ActivityLogModel {
  id?: number;                    // Log entry ID
  userId: string;                 // User identifier
  userName?: string;              // User display name
  action: string;                 // Action performed
  entityType: string;             // Type of entity
  entityId: string;               // Entity identifier
  entityName?: string;            // Entity display name
  description?: string;           // Action description
  metadata?: object;              // Additional data
  ipAddress?: string;             // Client IP address
  userAgent?: string;             // Browser/client info
  timestamp: string;              // ISO 8601 timestamp
}

ActivityLogFilterModel

Filter criteria for activity log queries.

interface ActivityLogFilterModel {
  text?: string;                  // Search text
  userId?: string;                // Filter by user
  action?: string;                // Filter by action
  entityType?: string;            // Filter by entity type
  startDate?: string;             // Start date (ISO 8601)
  endDate?: string;               // End date (ISO 8601)
  pageNumber: number;             // Page number (1-based)
  pageSize: number;               // Items per page
  sortBy?: string;                // Sort field
  isAscending?: boolean;          // Sort direction
}

Advocacy Models

CampaignTemplatePostModel

Campaign template for advocacy efforts.

interface CampaignTemplatePostModel {
  id?: number;                    // Template ID (0 for new)
  name: string;                   // Template name
  description?: string;           // Template description
  category?: string;              // Template category
  targetAudience?: string;        // Target audience
  subject?: string;               // Email/message subject
  messageTemplate: string;        // Message template with placeholders
  callToAction?: string;          // Call to action text
  tags?: string[];                // Template tags
  isActive: boolean;              // Whether template is active
  metadata?: object;              // Additional configuration
}

TemplateListFilterModel

Filter for campaign template queries.

interface TemplateListFilterModel {
  text?: string;                  // Search text
  category?: string;              // Filter by category
  isActive?: boolean;             // Filter by active status
  tags?: string[];                // Filter by tags
  createdBy?: string;             // Filter by creator
  startDate?: string;             // Created after date
  endDate?: string;               // Created before date
  pageNumber: number;             // Page number
  pageSize: number;               // Items per page
}

Bill Models

BillCalendarFilterModel

Filter for bill calendar queries.

interface BillCalendarFilterModel {
  startDate: string;              // Start date (ISO 8601)
  endDate: string;                // End date (ISO 8601)
  stateIds?: number[];            // Filter by states
  sessionIds?: number[];          // Filter by sessions
  committeeIds?: number[];        // Filter by committees
  billIds?: number[];             // Filter by specific bills
  eventTypes?: string[];          // Filter by event types
  chambers?: Chamber[];           // Filter by chambers
  trackingStatus?: string[];      // Filter by tracking status
  priority?: Priority[];          // Filter by priority
  tags?: string[];                // Filter by tags
  includeArchived?: boolean;      // Include archived events
}

BillCalendarViewModel

Calendar event view model.

interface BillCalendarViewModel {
  id: number;                     // Event identifier
  billId: number;                 // Associated bill ID
  billNumber: string;             // Bill number
  billTitle: string;              // Bill title
  eventDate: string;              // Event date/time (ISO 8601)
  eventType: EventType;           // Type of event
  eventTitle?: string;            // Event title
  description?: string;           // Event description
  location?: string;              // Event location
  room?: string;                  // Room number
  committee?: string;             // Committee name
  committeeId?: number;           // Committee ID
  chamber?: Chamber;              // Chamber
  state: string;                  // State name
  stateId: number;                // State ID
  status: EventStatus;            // Event status
  agenda?: string;                // Agenda text/URL
  witnesses?: Witness[];          // Witness list
  streamUrl?: string;             // Live stream URL
  recordingUrl?: string;          // Recording URL
  documents?: Document[];         // Related documents
  notes?: string;                 // Internal notes
  trackingStatus?: TrackingStatus; // Tracking status
  position?: BillPosition;        // Organization position
  priority?: Priority;            // Priority level
}

CalendarUpdateModel

Model for updating calendar events.

interface CalendarUpdateModel {
  eventId: number;                // Event to update
  status?: EventStatus;           // New status
  notes?: string;                 // Update notes
  trackingStatus?: TrackingStatus; // New tracking status
  position?: BillPosition;        // New position
  priority?: Priority;            // New priority
  metadata?: object;              // Additional data
  updatedBy: string;              // User making update
  updateReason?: string;          // Reason for update
}

Capitol Report Models

CapitolReportPostModel

Model for creating capitol reports.

interface CapitolReportPostModel {
  id?: number;                    // Report ID (0 for new)
  title: string;                  // Report title
  stateId: number;                // State ID
  reportDate: string;             // Report date (ISO 8601)
  reportType: ReportType;         // Type of report
  legislationDayId?: number;      // Associated legislation day
  content?: string;               // Report content (HTML)
  summary?: string;               // Executive summary
  billIds?: number[];             // Associated bills
  committeeIds?: number[];        // Associated committees
  authorId?: string;              // Report author
  reviewerId?: string;            // Report reviewer
  status: ReportStatus;           // Draft/Review/Published
  publishDate?: string;           // Publish date
  expirationDate?: string;        // Expiration date
  distribution?: Distribution;     // Distribution settings
  attachments?: Attachment[];     // File attachments
  metadata?: object;              // Additional data
}

BillReportViewModel

View model for bill reports.

interface BillReportViewModel {
  id: number;                     // Report ID
  title: string;                  // Report title
  reportDate: string;             // Report date
  reportType: string;             // Report type
  author: string;                 // Author name
  authorImage?: string;           // Author profile image
  status: ReportStatus;           // Report status
  billCount: number;              // Number of bills
  lastModified: string;           // Last modified date
  publishedDate?: string;         // Published date
  viewCount?: number;             // View count
  downloadCount?: number;         // Download count
  htmlContent?: string;           // HTML content
  pdfUrl?: string;                // PDF download URL
  excelUrl?: string;              // Excel download URL
  shareUrl?: string;              // Shareable URL
}

LegislationDaysPostModel

Model for legislation day configuration.

interface LegislationDaysPostModel {
  date: string;                   // Date (ISO 8601)
  dayType: DayType;               // Type of day
  description?: string;           // Day description
  startTime?: string;             // Start time
  endTime?: string;               // End time
  isActive: boolean;              // Whether day is active
  metadata?: object;              // Additional data
}

Common Models

PagingModel

Standard pagination model.

interface PagingModel {
  pageNumber: number;             // Current page (1-based)
  pageSize: number;               // Items per page
  totalRecords: number;           // Total record count
  totalPages: number;             // Total page count
  hasPrevious: boolean;           // Has previous page
  hasNext: boolean;               // Has next page
}

Address

Physical address structure.

interface Address {
  street1: string;                // Street address line 1
  street2?: string;               // Street address line 2
  city: string;                   // City
  state: string;                  // State/Province
  postalCode: string;             // ZIP/Postal code
  country?: string;               // Country
}

FileModel

File attachment model.

interface FileModel {
  id?: number;                    // File ID
  name: string;                   // File name
  type: string;                   // MIME type
  size: number;                   // File size in bytes
  url?: string;                   // Download URL
  uploadDate?: string;            // Upload timestamp
  uploadedBy?: string;            // Uploader ID
}

LinkModel

External link model.

interface LinkModel {
  id?: number;                    // Link ID
  title: string;                  // Link title
  url: string;                    // Link URL
  type?: string;                  // Link type
  description?: string;           // Link description
}

Validation Rules

Required Fields

All POST/PUT requests validate required fields:

// Example validation for Bill
{
  billNumber: {
    required: true,
    maxLength: 50,
    pattern: /^[A-Z]{2,4}\d{1,5}$/
  },
  title: {
    required: true,
    maxLength: 500
  },
  stateId: {
    required: true,
    type: 'number',
    min: 1
  }
}

String Length Limits

Field Type	Maximum Length
Short Text	50 characters
Medium Text	255 characters
Long Text	500 characters
Description	2000 characters
HTML Content	50000 characters
URL	2048 characters

Date Format Validation

All dates must be in ISO 8601 format:

• Date only: YYYY-MM-DD
• Date and time: YYYY-MM-DDTHH:mm:ssZ
• With timezone: YYYY-MM-DDTHH:mm:ss±HH:mm

Email Validation

Email addresses must match RFC 5322 specification:

^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$

Phone Number Validation

Phone numbers support multiple formats:

• US Format: (xxx) xxx-xxxx
• International: +x xxx xxx xxxx
• Extensions: xxx-xxx-xxxx ext. xxxx

Enumerations

TrackingStatus

enum TrackingStatus {
  NOT_TRACKED = "NOT_TRACKED",
  TRACKING = "TRACKING",
  WATCHING = "WATCHING",
  PRIORITY = "PRIORITY",
  ARCHIVED = "ARCHIVED"
}

BillPosition

enum BillPosition {
  SUPPORT = "SUPPORT",
  OPPOSE = "OPPOSE",
  NEUTRAL = "NEUTRAL",
  MONITOR = "MONITOR",
  NO_POSITION = "NO_POSITION"
}

Priority

enum Priority {
  LOW = 1,
  MEDIUM = 2,
  HIGH = 3,
  CRITICAL = 4
}

Chamber

enum Chamber {
  HOUSE = "HOUSE",
  SENATE = "SENATE",
  JOINT = "JOINT",
  EXECUTIVE = "EXECUTIVE"
}

EventType

enum EventType {
  HEARING = "HEARING",
  VOTE = "VOTE",
  COMMITTEE_MEETING = "COMMITTEE_MEETING",
  FLOOR_SESSION = "FLOOR_SESSION",
  CONFERENCE = "CONFERENCE",
  WORK_SESSION = "WORK_SESSION",
  PUBLIC_TESTIMONY = "PUBLIC_TESTIMONY"
}

EventStatus

enum EventStatus {
  SCHEDULED = "SCHEDULED",
  IN_PROGRESS = "IN_PROGRESS",
  COMPLETED = "COMPLETED",
  CANCELLED = "CANCELLED",
  POSTPONED = "POSTPONED",
  RESCHEDULED = "RESCHEDULED"
}

ReportType

enum ReportType {
  SUMMARY = 1,
  DETAILED = 2,
  EXECUTIVE = 3,
  WEEKLY = 4,
  MONTHLY = 5,
  END_OF_SESSION = 6,
  CUSTOM = 99
}

ReportStatus

enum ReportStatus {
  DRAFT = "DRAFT",
  REVIEW = "REVIEW",
  APPROVED = "APPROVED",
  PUBLISHED = "PUBLISHED",
  ARCHIVED = "ARCHIVED"
}

SessionType

enum SessionType {
  REGULAR = "REGULAR",
  SPECIAL = "SPECIAL",
  EXTRAORDINARY = "EXTRAORDINARY",
  BUDGET = "BUDGET"
}

DayType

enum DayType {
  SESSION = "SESSION",
  COMMITTEE = "COMMITTEE",
  RECESS = "RECESS",
  HOLIDAY = "HOLIDAY",
  NO_SESSION = "NO_SESSION"
}

Custom Field Types

Metadata Object

The metadata field accepts arbitrary JSON objects for custom data:

{
  "customField1": "value",
  "customField2": 123,
  "customArray": ["item1", "item2"],
  "nestedObject": {
    "property": "value"
  }
}

Filter Arrays

Arrays in filter models support multiple selection:

{
  "stateIds": [1, 2, 3],
  "eventTypes": ["HEARING", "VOTE"],
  "tags": ["urgent", "environmental", "budget"]
}

Response Wrappers

Success Response

interface ApiResponse<T> {
  success: boolean;
  data: T;
  message?: string;
  timestamp: string;
}

Error Response

interface ApiError {
  error: string;
  message: string;
  details?: object;
  timestamp: string;
  path?: string;
  requestId?: string;
}

Paginated Response

interface PaginatedResponse<T> {
  collection: T[];
  pagingModel: PagingModel;
  aggregations?: object;
  facets?: object;
}

---

For API endpoint details, see API ReferenceFor error handling, see Error Handling