feat: AIP-145 – Ranges (#23)

Author: Luke Sneeringer

aip/general/0145/aip.md

@@ -0,0 +1,73 @@
+# Ranges
+
+Services often need to represent ranges of discrete or continuous values. These
+have wide differences in meaning, and come in many types: integers, floats, and
+timestamps, just to name a few, and the expected meaning of a range can vary in
+subtle ways depending on the type of range being discussed.
+
+## Guidance
+
+A resource or message representing a range **should** ordinarily use two
+separate fields of the same type, with prefixes `start_` and `end_`:
+
+```typescript
+// A representation of a chapter in a book.
+interface Chapter {
+  title: string;
+
+  // The page where this chapter begins.
+  startPage: number;
+
+  // The page where the next chapter or section begins.
+  endPage: number;
+}
+```
+
+### Inclusive or exclusive ranges
+
+Fields representing ranges **should** use inclusive start values and exclusive
+end values (half-closed intervals) in most situations; in interval notation:
+`[start_xxx, end_xxx)`.
+
+Exclusive end values are preferable for the following reasons:
+
+- It conforms to user expectations, particularly for continuous values such as
+  timestamps, and avoids the need to express imprecise "limit values" (e.g.
+  `2012-04-20T23:59:59`).
+- It is consistent with most common programming languages, including C++, Java,
+  Python, and Go.
+- It is easier to reason about abutting ranges: `[0, x), [x, y), [y, z)`, where
+  values are chainable from one range to the next.
+
+### Exceptions
+
+In some cases, there is significant colloquial precedent for inclusive start
+and end values (closed intervals), to the point that using an exclusive end
+value would be confusing even for people accustomed to them.
+
+For example, when discussing dates (not to be confused with timestamps), most
+people use inclusive end: a conference with dates "April 21-23" is expected to
+run for three days: April 21, April 22, and April 23. This is also true for
+days of the week: a business that is open "Monday through Friday" is open, not
+closed, on Fridays.
+
+In this situation, the prefixes `first` and `last` **should** be used instead:
+
+```typescript
+// A representation of a chapter in a book.
+interface Chapter {
+  title: string;
+
+  // The first page of the chapter.
+  firstPage: number;
+
+  // The last page of the chapter.
+  lastPage: number;
+}
+```
+
+Fields representing ranges with significant colloquial precedent for inclusive
+start and end values **should** use inclusive end values with `first_` and
+`last_` prefixes for those ranges only. The service **should** still use
+exclusive end values for other ranges where this does not apply, and **must**
+clearly document each range as inclusive or exclusive.

aip/general/0145/aip.yaml

@@ -0,0 +1,7 @@
+---
+id: 145
+state: approved
+created: 2020-05-28
+placement:
+  category: fields
+  order: 60