diff --git a/rfds/0000-timestamp-offset-and-docs.md b/rfds/0000-timestamp-offset-and-docs.md new file mode 100644 index 0000000000..949adb624a --- /dev/null +++ b/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 + + +