From ca1372c6d7bcb199638ebfdb40d2b2660bab7b88 Mon Sep 17 00:00:00 2001 From: Google APIs Date: Tue, 9 Jun 2020 13:27:00 -0700 Subject: [PATCH] Regular update of Google API service config with clarification of documentations. BREAKING CHANGE: `features` field is no longer used. It has been removed from the API runtime for awhile. PiperOrigin-RevId: 315548189 --- google/api/auth.proto | 14 ++++--- google/api/backend.proto | 3 +- google/api/billing.proto | 28 +++++++++----- google/api/client.proto | 3 +- google/api/config_change.proto | 3 +- google/api/context.proto | 3 +- google/api/control.proto | 3 +- google/api/distribution.proto | 3 +- google/api/documentation.proto | 9 ++++- google/api/endpoint.proto | 6 +-- google/api/field_behavior.proto | 3 +- google/api/http.proto | 3 +- google/api/httpbody.proto | 3 +- google/api/label.proto | 3 +- google/api/launch_stage.proto | 9 ++++- google/api/log.proto | 3 +- google/api/logging.proto | 3 +- google/api/metric.proto | 59 ++++++++++++++++++++++++----- google/api/monitored_resource.proto | 38 ++++++++++++++----- google/api/monitoring.proto | 3 +- google/api/quota.proto | 8 +--- google/api/resource.proto | 24 +++++++++--- google/api/service.proto | 9 +++-- google/api/source_info.proto | 3 +- google/api/system_parameter.proto | 3 +- google/api/usage.proto | 3 +- 26 files changed, 162 insertions(+), 90 deletions(-) diff --git a/google/api/auth.proto b/google/api/auth.proto index 1b187cb4..b1f7d501 100644 --- a/google/api/auth.proto +++ b/google/api/auth.proto @@ -127,11 +127,15 @@ message AuthProvider { // The list of JWT // [audiences](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.3). // that are allowed to access. A JWT containing any of these audiences will - // be accepted. When this setting is absent, only JWTs with audience - // "https://[Service_name][google.api.Service.name]/[API_name][google.protobuf.Api.name]" - // will be accepted. For example, if no audiences are in the setting, - // LibraryService API will only accept JWTs with the following audience - // "https://library-example.googleapis.com/google.example.library.v1.LibraryService". + // be accepted. When this setting is absent, JWTs with audiences: + // - "https://[service.name]/[google.protobuf.Api.name]" + // - "https://[service.name]/" + // will be accepted. + // For example, if no audiences are in the setting, LibraryService API will + // accept JWTs with the following audiences: + // - + // https://library-example.googleapis.com/google.example.library.v1.LibraryService + // - https://library-example.googleapis.com/ // // Example: // diff --git a/google/api/backend.proto b/google/api/backend.proto index 2dbaa30a..729bccdb 100644 --- a/google/api/backend.proto +++ b/google/api/backend.proto @@ -1,4 +1,4 @@ -// Copyright 2019 Google LLC. +// 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. @@ -11,7 +11,6 @@ // 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"; diff --git a/google/api/billing.proto b/google/api/billing.proto index 87c11e7f..8e70388c 100644 --- a/google/api/billing.proto +++ b/google/api/billing.proto @@ -1,4 +1,4 @@ -// Copyright 2019 Google LLC. +// 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. @@ -11,7 +11,6 @@ // 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"; @@ -28,22 +27,33 @@ option objc_class_prefix = "GAPI"; // Billing related configuration of the service. // // The following example shows how to configure monitored resources and metrics -// for billing: +// for billing, `consumer_destinations` is the only supported destination and +// the monitored resources need at least one label key +// `cloud.googleapis.com/location` to indicate the location of the billing +// usage, using different monitored resources between monitoring and billing is +// recommended so they can be evolved independently: +// // // monitored_resources: -// - type: library.googleapis.com/branch +// - type: library.googleapis.com/billing_branch // labels: -// - key: /city -// description: The city where the library branch is located in. -// - key: /name -// description: The name of the branch. +// - key: cloud.googleapis.com/location +// description: | +// Predefined label to support billing location restriction. +// - key: city +// description: | +// Custom label to define the city where the library branch is located +// in. +// - key: name +// description: Custom label to define the name of the library branch. // metrics: // - name: library.googleapis.com/book/borrowed_count // metric_kind: DELTA // value_type: INT64 +// unit: "1" // billing: // consumer_destinations: -// - monitored_resource: library.googleapis.com/branch +// - monitored_resource: library.googleapis.com/billing_branch // metrics: // - library.googleapis.com/book/borrowed_count message Billing { diff --git a/google/api/client.proto b/google/api/client.proto index 56f8664a..2102623d 100644 --- a/google/api/client.proto +++ b/google/api/client.proto @@ -1,4 +1,4 @@ -// Copyright 2019 Google LLC. +// 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. @@ -11,7 +11,6 @@ // 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"; diff --git a/google/api/config_change.proto b/google/api/config_change.proto index c36764a5..953bb131 100644 --- a/google/api/config_change.proto +++ b/google/api/config_change.proto @@ -1,4 +1,4 @@ -// Copyright 2019 Google LLC. +// 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. @@ -11,7 +11,6 @@ // 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"; diff --git a/google/api/context.proto b/google/api/context.proto index 2d330f6f..f05e2389 100644 --- a/google/api/context.proto +++ b/google/api/context.proto @@ -1,4 +1,4 @@ -// Copyright 2019 Google LLC. +// 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. @@ -11,7 +11,6 @@ // 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"; diff --git a/google/api/control.proto b/google/api/control.proto index e769f978..9fdc8815 100644 --- a/google/api/control.proto +++ b/google/api/control.proto @@ -1,4 +1,4 @@ -// Copyright 2019 Google LLC. +// 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. @@ -11,7 +11,6 @@ // 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"; diff --git a/google/api/distribution.proto b/google/api/distribution.proto index ee45d9dc..4f0dec88 100644 --- a/google/api/distribution.proto +++ b/google/api/distribution.proto @@ -1,4 +1,4 @@ -// Copyright 2019 Google LLC. +// 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. @@ -11,7 +11,6 @@ // 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"; diff --git a/google/api/documentation.proto b/google/api/documentation.proto index 74cbf67e..2334b525 100644 --- a/google/api/documentation.proto +++ b/google/api/documentation.proto @@ -1,4 +1,4 @@ -// Copyright 2019 Google LLC. +// 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. @@ -11,7 +11,6 @@ // 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"; @@ -94,6 +93,12 @@ message Documentation { // The URL to the root of documentation. string documentation_root_url = 4; + // Specifies the service root url if the default one (the service name + // from the yaml file) is not suitable. This can be seen in any fully + // specified service urls as well as sections that show a base that other + // urls are relative to. + string service_root_url = 6; + // Declares a single overview page. For example: // 
documentation:
   //   summary: ...
diff --git a/google/api/endpoint.proto b/google/api/endpoint.proto
index 2077334d..6843a887 100644
--- a/google/api/endpoint.proto
+++ b/google/api/endpoint.proto
@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// 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.
@@ -11,7 +11,6 @@
 // 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";
 
@@ -50,9 +49,6 @@ message Endpoint {
   // Additional names that this endpoint will be hosted on.
   repeated string aliases = 2 [deprecated = true];
 
-  // The list of features enabled on this endpoint.
-  repeated string features = 4;
-
   // The specification of an Internet routable address of API frontend that will
   // handle requests to this [API
   // Endpoint](https://cloud.google.com/apis/design/glossary). It should be
diff --git a/google/api/field_behavior.proto b/google/api/field_behavior.proto
index eb7f78ef..aa7127bf 100644
--- a/google/api/field_behavior.proto
+++ b/google/api/field_behavior.proto
@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// 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.
@@ -11,7 +11,6 @@
 // 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";
 
diff --git a/google/api/http.proto b/google/api/http.proto
index b2977f51..69460cf7 100644
--- a/google/api/http.proto
+++ b/google/api/http.proto
@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// 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.
@@ -11,7 +11,6 @@
 // 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";
 
diff --git a/google/api/httpbody.proto b/google/api/httpbody.proto
index 45c1e76b..1a5bb78b 100644
--- a/google/api/httpbody.proto
+++ b/google/api/httpbody.proto
@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// 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.
@@ -11,7 +11,6 @@
 // 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";
 
diff --git a/google/api/label.proto b/google/api/label.proto
index 668efd1c..62f6cfa2 100644
--- a/google/api/label.proto
+++ b/google/api/label.proto
@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// 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.
@@ -11,7 +11,6 @@
 // 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";
 
diff --git a/google/api/launch_stage.proto b/google/api/launch_stage.proto
index 55fd9142..7d33eaa5 100644
--- a/google/api/launch_stage.proto
+++ b/google/api/launch_stage.proto
@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// 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.
@@ -11,7 +11,6 @@
 // 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";
 
@@ -29,6 +28,12 @@ enum LaunchStage {
   // Do not use this default value.
   LAUNCH_STAGE_UNSPECIFIED = 0;
 
+  // The feature is not yet implemented. Users can not use it.
+  UNIMPLEMENTED = 6;
+
+  // Prelaunch features are hidden from users and are only visible internally.
+  PRELAUNCH = 7;
+
   // Early Access features are limited to a closed group of testers. To use
   // these features, you must sign up in advance and sign a Trusted Tester
   // agreement (which includes confidentiality provisions). These features may
diff --git a/google/api/log.proto b/google/api/log.proto
index 1125e1fe..12e8c1cb 100644
--- a/google/api/log.proto
+++ b/google/api/log.proto
@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// 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.
@@ -11,7 +11,6 @@
 // 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";
 
diff --git a/google/api/logging.proto b/google/api/logging.proto
index 9090b2a1..e9ae9bf8 100644
--- a/google/api/logging.proto
+++ b/google/api/logging.proto
@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// 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.
@@ -11,7 +11,6 @@
 // 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";
 
diff --git a/google/api/metric.proto b/google/api/metric.proto
index a200d48b..b0397968 100644
--- a/google/api/metric.proto
+++ b/google/api/metric.proto
@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// 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.
@@ -11,7 +11,6 @@
 // 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";
 
@@ -30,11 +29,22 @@ option objc_class_prefix = "GAPI";
 // Defines a metric type and its schema. Once a metric descriptor is created,
 // deleting or altering it stops data collection and makes the metric type's
 // existing data unusable.
+//
+// The following are specific rules for service defined Monitoring metric
+// descriptors:
+//
+// * `type`, `metric_kind`, `value_type`, `description`, `display_name`,
+//   `launch_stage` fields are all required. The `unit` field must be specified
+//   if the `value_type` is any of DOUBLE, INT64, DISTRIBUTION.
+// * Maximum of default 500 metric descriptors per service is allowed.
+// * Maximum of default 10 labels per metric descriptor is allowed.
+//
+// The default maximum limit can be overridden. Please follow
+// https://cloud.google.com/monitoring/quotas
 message MetricDescriptor {
   // Additional annotations that can be used to guide the usage of a metric.
   message MetricDescriptorMetadata {
-    // Deprecated. Please use the MetricDescriptor.launch_stage instead.
-    // The launch stage of the metric definition.
+    // Deprecated. Must use the [MetricDescriptor.launch_stage][google.api.MetricDescriptor.launch_stage] instead.
     LaunchStage launch_stage = 1 [deprecated = true];
 
     // The sampling period of metric data points. For metrics which are written
@@ -98,9 +108,23 @@ message MetricDescriptor {
   string name = 1;
 
   // The metric type, including its DNS name prefix. The type is not
-  // URL-encoded.  All user-defined metric types have the DNS name
-  // `custom.googleapis.com` or `external.googleapis.com`.  Metric types should
-  // use a natural hierarchical grouping. For example:
+  // URL-encoded.
+  //
+  // All service defined metrics must be prefixed with the service name, in the
+  // format of `{service name}/{relative metric name}`, such as
+  // `cloudsql.googleapis.com/database/cpu/utilization`. The relative metric
+  // name must follow:
+  //
+  // * Only upper and lower-case letters, digits, '/' and underscores '_' are
+  //   allowed.
+  // * The maximum number of characters allowed for the relative_metric_name is
+  //   100.
+  //
+  // All user-defined metric types have the DNS name
+  // `custom.googleapis.com`, `external.googleapis.com`, or
+  // `logging.googleapis.com/user/`.
+  //
+  // Metric types should use a natural hierarchical grouping. For example:
   //
   //     "custom.googleapis.com/invoice/paid/amount"
   //     "external.googleapis.com/prometheus/up"
@@ -108,7 +132,16 @@ message MetricDescriptor {
   string type = 8;
 
   // The set of labels that can be used to describe a specific
-  // instance of this metric type. For example, the
+  // instance of this metric type.
+  //
+  // The label key name must follow:
+  //
+  // * Only upper and lower-case letters, digits and underscores (_) are
+  //   allowed.
+  // * Label name must start with a letter or digit.
+  // * The maximum length of a label name is 100 characters.
+  //
+  // For example, the
   // `appengine.googleapis.com/http/server/response_latencies` metric
   // type has a label for the HTTP response code, `response_code`, so
   // you can look at latencies for successful responses or just
@@ -138,7 +171,7 @@ message MetricDescriptor {
   // `s{CPU}` (or equivalently `1s{CPU}` or just `s`). If the job uses 12,005
   // CPU-seconds, then the value is written as `12005`.
   //
-  // Alternatively, if you want a custome metric to record data in a more
+  // Alternatively, if you want a custom metric to record data in a more
   // granular way, you can create a `DOUBLE CUMULATIVE` metric whose `unit` is
   // `ks{CPU}`, and then write the value `12.005` (which is `12005/1000`),
   // or use `Kis{CPU}` and write `11.723` (which is `12005/1024`).
@@ -224,7 +257,6 @@ message MetricDescriptor {
   // * `10^2.%` indicates a metric contains a ratio, typically in the range
   //    0..1, that will be multiplied by 100 and displayed as a percentage
   //    (so a metric value `0.03` means "3 percent").
-  //
   string unit = 5;
 
   // A detailed description of the metric, which can be used in documentation.
@@ -241,6 +273,13 @@ message MetricDescriptor {
 
   // Optional. The launch stage of the metric definition.
   LaunchStage launch_stage = 12;
+
+  // Read-only. If present, then a [time
+  // series][google.monitoring.v3.TimeSeries], which is identified partially by
+  // a metric type and a [MonitoredResourceDescriptor][google.api.MonitoredResourceDescriptor], that is associated
+  // with this metric type can only be associated with one of the monitored
+  // resource types listed here.
+  repeated string monitored_resource_types = 13;
 }
 
 // A specific metric, identified by specifying values for all of the
diff --git a/google/api/monitored_resource.proto b/google/api/monitored_resource.proto
index 2c94902a..537becdf 100644
--- a/google/api/monitored_resource.proto
+++ b/google/api/monitored_resource.proto
@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// 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.
@@ -11,7 +11,6 @@
 // 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";
 
@@ -34,9 +33,22 @@ option objc_class_prefix = "GAPI";
 // `"gce_instance"` and specifies the use of the labels `"instance_id"` and
 // `"zone"` to identify particular VM instances.
 //
-// Different APIs can support different monitored resource types. APIs generally
-// provide a `list` method that returns the monitored resource descriptors used
-// by the API.
+// Different services can support different monitored resource types.
+//
+// The following are specific rules to service defined monitored resources for
+// Monitoring and Logging:
+//
+// * The `type`, `display_name`, `description`, `labels` and `launch_stage`
+//   fields are all required.
+// * The first label of the monitored resource descriptor must be
+//   `resource_container`. There are legacy monitored resource descritptors
+//   start with `project_id`.
+// * It must include a `location` label. * Maximum of default 5 service defined monitored resource descriptors
+//   is allowed per service.
+// * Maximum of default 10 labels per monitored resource is allowed.
+//
+// The default maximum limit can be overridden. Please follow
+// https://cloud.google.com/monitoring/quotas
 message MonitoredResourceDescriptor {
   // Optional. The resource name of the monitored resource descriptor:
   // `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where
@@ -46,9 +58,7 @@ message MonitoredResourceDescriptor {
   // resource name format `"monitoredResourceDescriptors/{type}"`.
   string name = 5;
 
-  // Required. The monitored resource type. For example, the type
-  // `"cloudsql_database"` represents databases in Google Cloud SQL.
-  // The maximum length of this value is 256 characters.
+  // Note there are legacy service monitored resources not following this rule.
   string type = 1;
 
   // Optional. A concise name for the monitored resource type that might be
@@ -62,8 +72,16 @@ message MonitoredResourceDescriptor {
   string description = 3;
 
   // Required. A set of labels used to describe instances of this monitored
-  // resource type. For example, an individual Google Cloud SQL database is
-  // identified by values for the labels `"database_id"` and `"zone"`.
+  // resource type.
+  // The label key name must follow:
+  //
+  // * Only upper and lower-case letters, digits and underscores (_) are
+  //   allowed.
+  // * Label name must start with a letter or digit.
+  // * The maximum length of a label name is 100 characters.
+  //
+  // For example, an individual Google Cloud SQL database is
+  // identified by values for the labels `database_id` and `location`.
   repeated LabelDescriptor labels = 4;
 
   // Optional. The launch stage of the monitored resource definition.
diff --git a/google/api/monitoring.proto b/google/api/monitoring.proto
index 07e962d1..76f153bc 100644
--- a/google/api/monitoring.proto
+++ b/google/api/monitoring.proto
@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// 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.
@@ -11,7 +11,6 @@
 // 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";
 
diff --git a/google/api/quota.proto b/google/api/quota.proto
index 2e6e52b6..c9c78990 100644
--- a/google/api/quota.proto
+++ b/google/api/quota.proto
@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// 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.
@@ -11,7 +11,6 @@
 // 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";
 
@@ -150,10 +149,7 @@ message QuotaLimit {
   // Used by group-based quotas only.
   int64 free_tier = 7;
 
-  // Duration of this limit in textual notation. Example: "100s", "24h", "1d".
-  // For duration longer than a day, only multiple of days is supported. We
-  // support only "100s" and "1d" for now. Additional support will be added in
-  // the future. "0" indicates indefinite duration.
+  // Duration of this limit in textual notation. Must be "100s" or "1d".
   //
   // Used by group-based quotas only.
   string duration = 5;
diff --git a/google/api/resource.proto b/google/api/resource.proto
index 2a52e61a..22611d24 100644
--- a/google/api/resource.proto
+++ b/google/api/resource.proto
@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// 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.
@@ -11,7 +11,6 @@
 // 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";
 
@@ -223,10 +222,14 @@ message ResourceDescriptor {
   //     }
   History history = 4;
 
-  // The plural name used in the resource name, such as 'projects' for
-  // the name of 'projects/{project}'. It is the same concept of the `plural`
-  // field in k8s CRD spec
+  // The plural name used in the resource name and permission names, such as
+  // 'projects' for the resource name of 'projects/{project}' and the permission
+  // name of 'cloudresourcemanager.googleapis.com/projects.get'. It is the same
+  // concept of the `plural` field in k8s CRD spec
   // https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/
+  //
+  // Note: The plural form is required even for singleton resources. See
+  // https://aip.dev/156
   string plural = 5;
 
   // The same concept of the `singular` field in k8s CRD spec
@@ -247,6 +250,17 @@ message ResourceReference {
   //         type: "pubsub.googleapis.com/Topic"
   //       }];
   //     }
+  //
+  // Occasionally, a field may reference an arbitrary resource. In this case,
+  // APIs use the special value * in their resource reference.
+  //
+  // Example:
+  //
+  //     message GetIamPolicyRequest {
+  //       string resource = 2 [(google.api.resource_reference) = {
+  //         type: "*"
+  //       }];
+  //     }
   string type = 1;
 
   // The resource type of a child collection that the annotated field
diff --git a/google/api/service.proto b/google/api/service.proto
index c29eb5c8..ee65d99a 100644
--- a/google/api/service.proto
+++ b/google/api/service.proto
@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// 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.
@@ -11,7 +11,6 @@
 // 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";
 
@@ -74,6 +73,7 @@ message Service {
   // The semantic version of the service configuration. The config version
   // affects the interpretation of the service configuration. For example,
   // certain features are enabled by default for certain config versions.
+  //
   // The latest config version is `3`.
   google.protobuf.UInt32Value config_version = 20;
 
@@ -84,8 +84,9 @@ message Service {
   string name = 1;
 
   // A unique ID for a specific instance of this message, typically assigned
-  // by the client for tracking purpose. If empty, the server may choose to
-  // generate one instead. Must be no longer than 60 characters.
+  // by the client for tracking purpose. Must be no longer than 63 characters
+  // and only lower case letters, digits, '.', '_' and '-' are allowed. If
+  // empty, the server may choose to generate one instead.
   string id = 33;
 
   // The product title for this service.
diff --git a/google/api/source_info.proto b/google/api/source_info.proto
index 5954143d..3174209b 100644
--- a/google/api/source_info.proto
+++ b/google/api/source_info.proto
@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// 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.
@@ -11,7 +11,6 @@
 // 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";
 
diff --git a/google/api/system_parameter.proto b/google/api/system_parameter.proto
index 740a5538..50d428d6 100644
--- a/google/api/system_parameter.proto
+++ b/google/api/system_parameter.proto
@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// 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.
@@ -11,7 +11,6 @@
 // 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";
 
diff --git a/google/api/usage.proto b/google/api/usage.proto
index 6ab4e408..14d34c44 100644
--- a/google/api/usage.proto
+++ b/google/api/usage.proto
@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// 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.
@@ -11,7 +11,6 @@
 // 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";