jorisvandenbossche commented on a change in pull request #10629:
URL: https://github.com/apache/arrow/pull/10629#discussion_r664130256
##########
File path: format/Schema.fbs
##########
@@ -218,8 +218,33 @@ table Time {
/// leap seconds, as a 64-bit integer. Note that UNIX time does not include
/// leap seconds.
///
-/// The Timestamp metadata supports both "time zone naive" and "time zone
-/// aware" timestamps. Read about the timezone attribute for more detail
+/// Date & time libraries often have multiple different data types for temporal
+/// data. In order to ease interoperability between different implementations
the
+/// Arrow project has some recommendations for encoding these types into a
Timestamp
+/// column.
+///
+/// An "Instant" represents a single moment in time that has no meaningful
time zone
+/// or the time zone is unknown. A column of Instants can also contain values
from
+/// multiple time zones. To encode an instant set the timezone string to
"UTC".
+///
+/// A "ZonedDateTime" represents a single moment in time that has a meaningful
Review comment:
I would personally not use CamelClass names for those concepts. That
way, it seems to indicate this is a specific Arrow type or class (since this is
the Arrow specification), rather than a general description of concepts, which
could cause confusion (and it are not generally used names, AFAIK only Java
uses exactly those names).
Describing things in a "neutral" way is hard of course (since everybody
comes to this with their own background with specific terminology), but so to
avoid bike-shedding on the terms, I would suggest to just not use CameCase. So
for example, alternatively could use "zoned date-time" (with a space, so it
doesn't mimic a class name).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
