Question
Which mechanism in OAS 3.0 enforces regional time zone constraints for date-time formats?
Rey Lane
0 reputation · 20 Jun 2021, 07:48 UTC
71K views
Loading…
0 reputation · 20 Jun 2021, 07:48 UTC
The OpenAPI Specification (OAS) 3.0 utilizes the string type with a format: date-time modifier to represent timestamps. According to the specification, this format adheres to RFC 3339, which allows for the inclusion of a time zone offset.
While RFC 3339 supports offsets, the specification does not define a native way to mandate a specific regional time zone (e.g., UTC-5) for all incoming requests or outgoing responses. This leaves the enforcement of regional time zone consistency to the implementation layer of the API rather than the contract definition.
When designing a contract for a globally distributed system, it is unclear how to communicate a strict time zone requirement to clients without relying on non-standard extensions. Does OAS 3.0 provide a standard attribute to restrict the allowed offsets for a date-time field, or is the use of custom x- extensions the only documented approach for this requirement?
35775 reputation · 20 Jun 2021, 09:03 UTC
OpenAPI Specification (OAS) 3.0 does not provide a native mechanism to enforce regional time zone constraints or mandate a specific offset for format: date-time fields. The specification relies on RFC 3339, which allows any valid time zone offset; there is no standard attribute to restrict this to a specific region (e.g., UTC-5).
In OAS 3.0, the date-time format is a hint to the implementation that the string should follow RFC 3339. While RFC 3339 defines how offsets are represented, the OAS schema keywords do not include a way to validate the value of that offset. Consequently, any validator compliant with OAS 3.0 will accept any valid RFC 3339 string, regardless of the regional offset used.
Since there is no built-in constraint, developers typically use the following three methods to communicate or enforce time zone requirements:
swaggerpattern Keyword: You can apply a Regular Expression to the string to force a specific offset (e.g., requiring the string to end in Z for UTC or -05:00). However, this is fragile and can easily reject valid timestamps or allow syntactically correct but logically wrong offsets.description Field: This is the most common approach for human-readability. Explicitly stating "All timestamps must be provided in UTC" informs the client, but it provides no automated enforcement.x- Extensions: Using x-timezone: "America/New_York" allows custom tooling or internal SDK generators to handle the logic, but standard OAS validators will ignore these fields.type: string and format: date-time to maintain compatibility with standard tooling.description attribute of the property.400 Bad Request if the offset does not match the required regional constraint.Diagnostic Detail: Are you using a specific automated validation tool (e.g., Prism, Spectral) to enforce your contract? Knowing the tool would determine if a custom linting rule could replace the need for a native OAS attribute.
Use comments to ask for clarification. Post a solution as an answer.
6,300 reputation · 20 Jun 2021, 10:36 UTC
While OAS 3.0 uses format: date-time to adhere to RFC 3339, the specification lacks a native schema keyword to mandate a specific regional time zone (e.g., UTC-5). The format allows any valid offset or the 'Z' designator, but it cannot restrict these to a specific geographic region.
To communicate strict regional requirements, developers typically rely on:
pattern attribute to enforce a specific offset format (though this is lexical and doesn't account for daylight savings shifts).x- extensions, such as x-timezone, to provide metadata for client-side tools or generators.description or example fields to ensure client compliance.Ultimately, enforcement of regional time zone consistency must be handled at the implementation layer, as the contract itself only defines the structural shape of the timestamp.