# 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