Merge branch 'main' into aip-143

Author: Luke Sneeringer

.github/workflows/publish.yaml

@@ -3,7 +3,7 @@ name: publish
 on:
   push:
     branches:
-      - master
+      - main
 jobs:
   github-pages:
     runs-on: ubuntu-latest

.github/workflows/test.yaml

@@ -3,7 +3,7 @@ name: test
 on:
   pull_request:
     branches:
-      - master
+      - main
 jobs:
   build:
     runs-on: ubuntu-latest

aip/general/0126/aip.md.j2

@@ -0,0 +1,138 @@
+# Enumerations
+
+It is common for a field to only accept or provide a discrete and limited set
+of values. In these cases, it can be useful to use enumerations (generally
+abbreviated "enums") in order to clearly communicate what the set of allowed
+values are.
+
+## Guidance
+
+APIs **may** expose enum objects for sets of values that are expected to change
+infrequently:
+
+```typescript
+// Possible formats in which a book may be published.
+enum Format {
+  // The printed format, in hardback.
+  Hardback = 'HARDBACK',
+
+  // The printed format, in paperback.
+  Paperback = 'PAPERBACK',
+
+  // An electronic book format.
+  Ebook = 'EBOOK',
+
+  // An audio recording.
+  Audiobook = 'AUDIOBOOK',
+}
+```
+
+- All enum values **should** use a consistent case format across an
+  organization. In many cases, this is dictated by the IDL the organization
+  uses.
+- Enums **should** document whether the enum is frozen or they expect to add
+  values in the future.
+
+### When to use enums
+
+Enums can be more accessible and readable than strings or booleans in many
+cases, but they do add overhead when they change. Therefore, enums **should**
+receive new values infrequently. While the definition of "infrequently" may
+change based on individual use cases, a good rule of thumb is no more than once
+a year. For enums that change frequently, the API **should** use a string and
+document the format.
+
+**Note:** If an enumerated value needs to be shared across APIs, an enum
+**may** be used, but the assignment between enum values and their wire
+representation **must** match.
+
+### Alternatives
+
+Enums **should not** be used when there is a competing, widely-adopted standard
+representation (such as with [language codes][bcp-47] or [media types][]).
+Instead, that standard representation **should** be used. This is true even if
+only a small subset of values are permitted, because using enums in this
+situation often leads to frustrating lookup tables when trying to use multiple
+APIs together.
+
+For enumerated values where the set of allowed values changes frequently, APIs
+**should** use a `string` field instead, and **must** document the allowed
+values. String fields with enumerated values **should** use a uniform case
+system (`snake_case`, `kebab-case`, etc.) throughout an organization.
+
+Boolean fields **may** be used in situations where it is clear that no further
+flexibility will be needed. The default value **must** be `false`.
+
+### Compatibility
+
+Adding values to an enum has the potential to be disruptive to existing
+clients. Consider code written against the `Format` enum in an earlier version
+where only the first two options were available:
+
+```typescript
+switch (book.format) {
+  case Format.Hardback:
+    // Do something...
+    break;
+  case Format.Paperback:
+    // Do something...
+    break;
+  default:
+    // When new enum values are introduced, pre-existing client code may
+    // throw errors or act in unexpected ways.
+    throw new Error('Unrecognized value.');
+}
+```
+
+Services **may** add new values to existing enums; however, they **should** add
+enums carefully; think about what will happen if a client system does not know
+about a new value.
+
+Additionally, in IDLs where enum values are presented in a specific order,
+services **should** only add new values to the end. An exception to this rule
+is if the enum conforms to an external standard (for example, an enum
+representing HTTP status codes would add a new 3xx value alongside the others,
+not at the end).
+
+## Interface Definitions
+
+{% tab proto %}
+
+{% sample 'enum.proto', 'enum Format' %}
+
+- The zero value of the enum **should** be the name of the enum itself followed
+  by the suffix `_UNSPECIFIED`. The service **may** either allow or prohibit
+  use of this value.
+- Enums which will only be used in a single message **should** be nested within
+  that message. In this case, the enum **should** be declared immediately
+  before it is used.
+- If multiple enums are in the same namespace, they **must not** share any
+  values. (This is because enums do not provide their own namespace for their
+  values in some languages.)
+- If an enumerated value needs to be shared across APIs, an enum **may** be
+  used, but the assignment between the value names and the tag numbers **must**
+  match.
+
+**Note:** When using protocol buffers, it is impossible to distinguish between
+`false` and unset. If this is a requirement, an enum **may** be a better design
+choice (although `google.protobuf.BoolValue` is also available).
+
+{% tab oas %}
+
+{% sample 'enum.oas.yaml', 'format' %}
+
+- Enumerated fields **should** be strings.
+- If the enum is optional, The `null` value **should** be used as the empty
+  value, and **should** be the first value specified.
+
+**Note:** If `null` is a valid value, OpenAPI 3.0 also requires that
+`nullable: true` is specified for the field.
+
+{% endtabs %}
+
+## Further reading
+
+- For states, a special type of enum, see AIP-216.
+
+[bcp-47]: https://en.wikipedia.org/wiki/IETF_language_tag
+[media types]: https://en.wikipedia.org/wiki/Media_type

aip/general/0126/aip.yaml

@@ -0,0 +1,7 @@
+---
+id: 126
+state: approved
+created: 2019-07-24
+placement:
+  category: resource-design
+  order: 60

aip/general/0126/enum.oas.yaml

@@ -0,0 +1,40 @@
+---
+openapi: 3.0.3
+info:
+  title: Library
+  version: 1.0.0
+components:
+  schema:
+    Book:
+      description: A representation of a single book.
+      properties:
+        name:
+          type: string
+          description: |
+            The name of the book.
+            Format: publishers/{publisher}/books/{book}
+        isbn:
+          type: string
+          description: |
+            The ISBN (International Standard Book Number) for this book.
+        title:
+          type: string
+          description: The title of the book.
+        authors:
+          type: array
+          items:
+            type: string
+          description: The author or authors of the book.
+        rating:
+          type: float
+          description: The rating assigned to the book.
+        format:
+          type: string
+          description: The format of the book.
+          nullable: true
+          enum:
+            - null
+            - HARDCOVER
+            - PAPERBACK
+            - EBOOK
+            - AUDIOBOOK

aip/general/0126/enum.proto

@@ -0,0 +1,62 @@
+// Copyright 2020 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+import "google/api/resource.proto";
+
+// A representation of a book.
+message Book {
+  option (google.api.resource) = {
+    type: "library.googleapis.com/Book"
+    pattern: "publishers/{publisher}/books/{book}"
+  };
+
+  // The name of the book.
+  // Format: publishers/{publisher}/books/{book}
+  string name = 1;
+
+  // The ISBN (International Standard Book Number) for this book.
+  string isbn = 2;
+
+  // The title of the book.
+  string title = 3;
+
+  // The author or authors of the book.
+  repeated string authors = 4;
+
+  // The rating assigned to the book.
+  float rating = 5;
+
+  // Possible formats in which the book may be published.
+  enum Format {
+    // Default value. This value is unused.
+    FORMAT_UNSPECIFIED = 0;
+
+    // The printed format, in hardback.
+    HARDBACK = 1;
+
+    // The printed format, in paperback.
+    PAPERBACK = 2;
+
+    // An electronic book format.
+    EBOOK = 3;
+
+    // An audio recording.
+    AUDIOBOOK = 4;
+  }
+
+  // The format of the book.
+  Format format = 6;
+}

aip/general/0141/aip.md

@@ -0,0 +1,79 @@
+# Quantities
+
+Many services need to represent a discrete quantity of items (number of bytes,
+number of miles, number of nodes, etc.).
+
+## Guidance
+
+Quantities with a clear unit of measurement (such as bytes, miles, and so on)
+**must** include the unit of measurement as the suffix. When appropriate and
+unambiguous, units **should** use generally accepted abbreviations (for
+example, `distance_km` rather than `distance_kilometers`).
+
+```typescript
+// A representation of a non-stop air route.
+interface Route {
+  // The airport where the route begins.
+  origin: string;
+
+  // The destination airport.
+  destination: string;
+
+  // The distance between the origin and destination airports.
+  // This value is also used to determine the credited frequent flyer miles.
+  distance_miles: number;
+}
+```
+
+If the quantity is a number of items (for example, the number of nodes in a
+cluster), then the field **should** use the suffix `_count` (**not** the prefix
+`num_`):
+
+```typescript
+// A cluster of individual nodes.
+interface Cluster {
+  // The number of nodes in the cluster.
+  node_count: number;
+}
+```
+
+**Note:** Fields **must not** use unsigned integer types, because many
+programming languages and systems do not support them well.
+
+### Specialized messages
+
+It is sometimes useful to create a message that represents a particular
+quantity. This is particularly valuable in two situations.
+
+- Grouping two or more individual quantities together.
+- Representing a common concept where the unit of measurement may itself vary.
+
+Consider the example of money, which could need to do both of these:
+
+```typescript
+// A representation of an amount of money, in an arbitrary currency.
+interface Money {
+  // The 3-letter currency code defined in ISO 4217.
+  currency_code: string;
+
+  // The whole units of the amount.
+  // For example if `currency_code` is "USD", then 1 unit is one US dollar.
+  units: bigint;
+
+  // Number of nano (10^-9) units of the amount.
+  // The value must be between -999,999,999 and +999,999,999 inclusive.
+  // If `units` is positive, `nanos` must be positive or zero.
+  // If `units` is zero, `nanos` can be positive, zero, or negative.
+  // If `units` is negative, `nanos` must be negative or zero.
+  // For example $-1.75 is represented as `units`=-1 and `nanos`=-750,000,000.
+  nanos: number;
+}
+```
+
+APIs **may** create structs to represent quantities when appropriate. When
+using these structs as fields, APIs **should** use the name of the struct as
+the suffix for the field name if it makes intuitive sense to do so.
+
+## Changelog
+
+- **2019-09-13**: Added the prohibition on unsigned types.

aip/general/0141/aip.yaml

@@ -0,0 +1,7 @@
+---
+id: 141
+state: approved
+created: 2019-07-18
+placement:
+  category: fields
+  order: 20