107 lines
3.4 KiB
Markdown
107 lines
3.4 KiB
Markdown
|
# 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
|
||
|
|
|