veza/DATETIME_STANDARD.md

Date/Time Format Standardization

INT-008: Standardize date/time formats

Date: 2025-12-25
Status: Completed

Summary

All date and time values in Veza API responses now use ISO 8601 (RFC3339) format consistently.

Standard Date/Time Format

All dates and timestamps use ISO 8601 (RFC3339) format:

• Format: YYYY-MM-DDTHH:mm:ssZ or YYYY-MM-DDTHH:mm:ss.sssZ
• Example: 2025-12-25T10:30:00Z or 2025-12-25T10:30:00.123Z
• Timezone: Always UTC (indicated by Z suffix)

Implementation

Backend

All date/time formatting is now standardized through:

1. time.RFC3339 (Go standard library):

   • Used throughout the codebase for consistent formatting
   • Ensures ISO 8601 compliance
   • Always uses UTC timezone

2. utils.FormatISO8601 (internal/utils/datetime.go):

   • Helper function for formatting time.Time to ISO 8601
   • Automatically converts to UTC
   • Used for manual date formatting

3. utils.FormatISO8601Ptr (internal/utils/datetime.go):

   • Helper for nullable *time.Time fields
   • Returns empty string if nil

4. utils.ParseISO8601 (internal/utils/datetime.go):

   • Helper for parsing ISO 8601 strings
   • Used for date input validation

5. Model Updates:

   • UserResponse.FromUser: Uses time.RFC3339 instead of custom format
   • All time.Time fields in models are automatically serialized by Go's JSON encoder
   • GORM models use time.Time which serializes correctly

Frontend

The frontend already expects ISO 8601 format:

• JavaScript Date constructor parses ISO 8601 automatically
• All date parsing/formatting libraries support ISO 8601
• No frontend changes required

Changes Made

Backend Changes

1. internal/models/responses.go:

   • Updated FromUser to use time.RFC3339 instead of "2006-01-02T15:04:05Z"
   • Added time import
   • Ensures UTC timezone with .UTC()

2. internal/handlers/webhook_handlers.go:

   • Updated webhook test timestamp to use time.RFC3339
   • Ensures consistent format in webhook payloads

3. internal/utils/datetime.go (new file):

   • Created helper functions for date formatting
   • FormatISO8601: Formats time.Time to ISO 8601
   • FormatISO8601Ptr: Formats nullable *time.Time
   • ParseISO8601: Parses ISO 8601 strings

4. Error Responses:

   • Already using time.RFC3339 in error_response.go
   • No changes needed

Model Serialization

GORM models with time.Time fields are automatically serialized correctly:

• Go's JSON encoder uses RFC3339 format by default for time.Time
• All model fields like CreatedAt, UpdatedAt are correctly formatted
• No additional changes needed for models

Migration Notes

• All manual date formatting now uses time.RFC3339
• Custom format strings like "2006-01-02T15:04:05Z" replaced with time.RFC3339
• All timestamps are in UTC timezone
• Frontend automatically handles ISO 8601 format

Files Modified

• veza-backend-api/internal/models/responses.go
• veza-backend-api/internal/handlers/webhook_handlers.go
• Created: veza-backend-api/internal/utils/datetime.go
• Created: DATETIME_STANDARD.md (this document)

Next Steps

1. ✅ Standardize all date formatting to RFC3339
2. ✅ Create helper functions for date formatting
3. ✅ Update manual date formatting in responses
4. ✅ Verify model serialization
5. ⏳ Add integration tests for date format validation