RFD for timestamp update and documentation

rfds/0000-timestamp-offset-and-docs.md

@@ -0,0 +1,163 @@
+# Enforcing Strict Validation of Timezone Offsets and Multiple Timestamp Schema Documentation Updates
+
+| Field            | Value  |
+|:-----------------|:-------|
+| RFD Submitter    | Chris Coffin |
+| RFD Pull Request | TBD [RFD #0000](https://github.com/CVEProject/cve-schema/pull/1234) |
+
+## Summary
+[summary]: #summary
+
+As part of the timestamp CVE Record Date/Time Formatting Normalization 
+efforts by the AWG, the QWG should make a few changes to the CVE Record 
+Format JSON schema to support and complement the efforts. First, the CVE 
+Record Format JSON schema should restrict timezone offsets when provided 
+to the range -12:00 through 14:00. Second, the CVE Record Format JSON 
+schema documentation should be updated to remove reference to ISO 8601 and 
+GMT and should also note the acceptable timezone offset range.
+
+Note that these changes are part of a larger efforts to use and enforce a 
+single consistent format to timestamps within CVE Records. The agreed upon 
+format is based on RFC 3339. Note that RFC 3339 is a strict subset of the 
+broader ISO 8601.  
+
+## Problem Statement
+[problem-statement]: #problem-statement
+
+The CVE Record Format includes multiple JSON properties that use a timestamp 
+value. The values for the various timestamp values have not always used a 
+consistant format, and this can cause confusion for consumers of the CVE 
+Records.
+
+The current version of the schema (5.2.0) restricts and validates timestamp 
+values using a regular expression within the timestamp definition. All 
+timestamp properties reference and use this timestamp definition. There are 
+two primary issues. First, it allows a timezone offset beyond what is 
+currently possible (i.e., it allows offsets outside of -12:00 through 14:00). 
+Second, the schema documentation currently mentions ISO 8601 and GMT, and 
+these should be removed to avoid confusion by CVE consumers. The time 
+property within the timeline array also includes a similar description and 
+would require the same updates as the timestamp definition. 
+
+## Proposed Solution
+[proposed-solution]: #proposed-solution
+
+Update the CVE Record Format JSON schema timestamp definition regular 
+expression to enforce and validate that a timezone offset, when provided, 
+is a valid timezone offset. This will require the timestamp definition 
+regular expression be updated to check the timezone offset portion of the 
+timestamp. Note that at this time we do not require a timezone offset to be 
+included by CVE producers. If a timezone offset is not provided, we assume 
+UTC. This solution would enforce that when specified, a timezone offset be 
+syntactically correct and that it should be valid according to the list of 
+possible values (-12:00 through 14:00).
+
+The other solution is to update all schema definitions that relates to 
+timestamps so that they properly state the use of RFC 3339 and UTC. We 
+should also mention the acceptable range of timezone offset values.
+
+## Examples
+[examples]: #examples
+
+The agreed upon timezone format for timestamp fields in CVE Record Format:
+- yyyy-MM-ddTHH:mm:ss.sssZ
+- yyyy-MM-ddTHH:mm:ss.sss+HH:mm
+- yyyy-MM-ddTHH:mm:ss.sss-HH:mm
+
+Note that a CVE producer can provide a timestamp in the form 
+yyyy-MM-ddTHH:mm:ss.sss without a timezone offset being specified. This will 
+be converted to UTC on submission to CVE Services. Also note that a CVE 
+producer can provide a timestamp without milliseconds, and this will be 
+converted to include a milliseconds value with all zeros (e.g., 
+yyyy-MM-ddTHH:mm:ss will be converted to yyyy-MM-ddTHH:mm:ss.sssZ).
+
+Examples:
+- 2026-02-05T00:53:09.778Z
+- 2026-02-05T00:53:09.778+06:00
+- 2026-02-05T00:53:09.778-12:00
+
+Current regular expression:
+- ^(((2000|2400|2800|(19|2[0-9](0[48]|[2468][048]|[13579][26])))-02-29)|(((19|2[0-9])[0-9]{2})-02-(0[1-9]|1[0-9]|2[0-8]))|(((19|2[0-9])[0-9]{2})-(0[13578]|10|12)-(0[1-9]|[12][0-9]|3[01]))|(((19|2[0-9])[0-9]{2})-(0[469]|11)-(0[1-9]|[12][0-9]|30)))T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]+)?(Z|[+-][0-9]{2}:[0-9]{2})?$
+
+Regular expression update: 
+TBD
+
+Current timestamp defintion schema description:
+Date/time format based on RFC3339 and ISO ISO8601, with an optional timezone 
+in the format 'yyyy-MM-ddTHH:mm:ss[+-]ZH:ZM'. If timezone offset is not 
+given, GMT (+00:00) is assumed.
+
+Timestamp definition schema description update:
+Date/time format based on RFC3339, with an optional timezone in the format 
+'yyyy-MM-ddTHH:mm:sss[+-]ZH:ZM'. If a timezone offset is not provided, UTC 
+(0000) is assumed. If provided. timezone offsets must be specified in the 
+range -12:00 through 14:00, else validation will fail.
+
+## Impact Assessment
+[impact-assessment]: #impact-assessment
+
+There should be minimal to zero negative impact for CVE consumers since this 
+change is meant to make the schema more consitent with regard to timestamps.
+It could cause some confusion intially since timestamp values may look 
+different than expected in some cases. 
+
+## Compatibility and Migration
+[compatibility-and-migration]: #compatibility-and-migration
+
+If any older CVE Records have timezone offsets outside of the specified range, 
+this could cause them to fail validation. 
+
+## Success Metrics
+[success-metrics]: #success-metrics
+
+Success would include updating the schema to include a new regular expression 
+that enforces valid timezone offsets. It would also include updates to the 
+schema documentation that more accurately describes how timestamps should be 
+formatted and used. 
+
+## Supporting Data or Research
+[supporting-data-or-research]: #supporting-data-or-research
+
+There are multiple cve-schema repository open issues regarding timestamps and 
+the quality of them.
+
+## Related Issues or Proposals
+[related-issues-or-proposals]: #related-issues-or-proposals
+
+In February 2026 there is an effort underway by the CVE AWG and CVE 
+infrastructure development team to normalize all CVE Record timestamps to the 
+format that is described in this RFD. Implementing the changes in this RFD will 
+complement that process going forward.
+
+## Recommended Priority
+[recommended-priority]: #recommended-priority
+
+Medium - This update should be considered a medium priority because as part of 
+the AWG data normalization efforts, a timezone offset that is out of range 
+(more than 23 hours) will currently pass schema validation but fail CVE 
+Services validation. The schema validation does not enforce acceptable values 
+for the timezone offset.
+
+## Unresolved Questions
+[unresolved-questions]: #unresolved-questions
+
+Can a regular expression be defined that properly limits the timezone offset to 
+the valid range of values? I believe the answer is yes, but have not tried yet.
+
+The current timestamp regular expression does not require milliseconds. 
+Should we require milliseconds as part of the schema validation.
+
+Should we consider requiring a timezone offset be provided for all timestamp 
+fields in the future? In other words, should validation fail without it? 
+
+Are there any CVE Records today that include a timestamp with an invalid 
+timezone offset (outside of the range -12:00 through 14:00)?
+
+## Future Possibilities
+[future-possibilities]: #future-possibilities
+
+
+TBD
+
+
+