Field patterns

Welcome to the fourth edition of the AIP newsletter, which is designed to keep you up to date about the AIP program, and particular proposals making their way through the system.

This month, we have two new AIPs, both around patterns for specific kinds of fields.

As always, the AIP newsletter kicks off what is effectively a "public comment" period: the AIP editors are happy with these proposals, but we want to ensure that you are too. Assuming feedback is sufficiently positive, we intend to formally approve these proposals on Friday, June 26, 2020.

AIPs under review

AIP-145: 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.

Ranges are fields that represent a range of discrete or continuous values. These are often integers or floats, but can be other values where ranges make sense, such as dates.

The primary challenge for ranges is whether their values (particularly their end values) should be inclusive or exclusive. Most developers are used to exclusive end values, but with some notable and precise exceptions (example: dates are an exception, but not timestamps), and the AIP attempts to encode this using the idea of "colloquial precedent".

Summary: AIP-145 provides patterns for ranges of values: two fields that represent a start and end value.

We are aiming to approve AIP-145 on June 26. If you have feedback, please leave a comment.

AIP-146: Generic fields

Occasionally it is appropriate to have a generic or polymorphic field of some kind that can conform to multiple schemata, or even be entirely free-form.

Generic fields discusses the various ways to approach a polymorphic or entirely generic field in the API. These provide implementation flexibility, but the tradeoff is a less clear API contract. There are several ways to provide a generic field, and the AIP enumerates them and discussed the tradeoffs.

Summary: AIP-146 offers four patterns for generic fields, and describes the tradeoffs of each.

We are aiming to approve AIP-146 on June 26. If you have feedback, please leave a comment.

Recent updates

In addition to the new AIPs under review, we have added the following guidance to existing AIPs:

  • AIP-122: Corrected a mistaken piece of guidance about capitalization (#513)
  • AIP-132: Removed mandate to document default ordering (#512)
  • AIP-140: Add guidance for URI fields (#519)
  • AIP-143: Change guidance for countries to region_code (#507)
  • AIP-203: Clarified behavior for updating immutable fields (#516)