Merge pull request #24 from ethanbao/master

Add core protos of Google API service config as well as source_context proto

google/api/README.md

@@ -0,0 +1,5 @@
+This folder contains the schema of the configuration model for the API services
+platform.
+
+**Note**: Protos under this directory are in Alpha status, and therefore are
+subject to breaking changes.

google/api/auth.proto

@@ -0,0 +1,159 @@
+// Copyright 2016 Google Inc.
+//
+// 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
+//
+//     http://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";
+
+package google.api;
+
+import "google/api/annotations.proto";
+
+option java_multiple_files = true;
+option java_outer_classname = "AuthProto";
+option java_package = "com.google.api";
+
+
+// `Authentication` defines the authentication configuration for an API.
+//
+// Example for an API targeted for external use:
+//
+//     name: calendar.googleapis.com
+//     authentication:
+//       rules:
+//       - selector: "*"
+//         oauth:
+//           canonical_scopes: https://www.googleapis.com/auth/calendar
+//
+//       - selector: google.calendar.Delegate
+//         oauth:
+//           canonical_scopes: https://www.googleapis.com/auth/calendar.read
+message Authentication {
+  // Individual rules for authentication.
+  repeated AuthenticationRule rules = 3;
+
+  // Defines a set of authentication providers that a service supports.
+  repeated AuthProvider providers = 4;
+}
+
+// Authentication rules for the service.
+//
+// By default, if a method has any authentication requirements, every request
+// must include a valid credential matching one of the requirements.
+// It's an error to include more than one kind of credential in a single
+// request.
+//
+// If a method doesn't have any auth requirements, request credentials will be
+// ignored.
+//
+message AuthenticationRule {
+  // Selects the methods to which this rule applies.
+  //
+  // Refer to [selector][google.api.DocumentationRule.selector] for syntax details.
+  string selector = 1;
+
+  // The requirements for OAuth credentials.
+  OAuthRequirements oauth = 2;
+
+  // Whether to allow requests without a credential.  If quota is enabled, an
+  // API key is required for such request to pass the quota check.
+  //
+  bool allow_without_credential = 5;
+
+  // Requirements for additional authentication providers.
+  repeated AuthRequirement requirements = 7;
+}
+
+// Configuration for an anthentication provider, including support for
+// [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).
+message AuthProvider {
+  // The unique identifier of the auth provider. It will be referred to by
+  // `AuthRequirement.provider_id`.
+  //
+  // Example: "bookstore_auth".
+  string id = 1;
+
+  // Identifies the principal that issued the JWT. See
+  // https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32#section-4.1.1
+  // Usually a URL or an email address.
+  //
+  // Example: https://securetoken.google.com
+  // Example: 1234567-compute@developer.gserviceaccount.com
+  string issuer = 2;
+
+  // URL of the provider's public key set to validate signature of the JWT. See
+  // [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).
+  // Optional if the key set document:
+  //  - can be retrieved from
+  //    [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html
+  //    of the issuer.
+  //  - can be inferred from the email domain of the issuer (e.g. a Google service account).
+  //
+  // Example: https://www.googleapis.com/oauth2/v1/certs
+  string jwks_uri = 3;
+}
+
+// OAuth scopes are a way to define data and permissions on data. For example,
+// there are scopes defined for "Read-only access to Google Calendar" and
+// "Access to Cloud Platform". Users can consent to a scope for an application,
+// giving it permission to access that data on their behalf.
+//
+// OAuth scope specifications should be fairly coarse grained; a user will need
+// to see and understand the text description of what your scope means.
+//
+// In most cases: use one or at most two OAuth scopes for an entire family of
+// products. If your product has multiple APIs, you should probably be sharing
+// the OAuth scope across all of those APIs.
+//
+// When you need finer grained OAuth consent screens: talk with your product
+// management about how developers will use them in practice.
+//
+// Please note that even though each of the canonical scopes is enough for a
+// request to be accepted and passed to the backend, a request can still fail
+// due to the backend requiring additional scopes or permissions.
+//
+message OAuthRequirements {
+  // The list of publicly documented OAuth scopes that are allowed access. An
+  // OAuth token containing any of these scopes will be accepted.
+  //
+  // Example:
+  //
+  //      canonical_scopes: https://www.googleapis.com/auth/calendar,
+  //                        https://www.googleapis.com/auth/calendar.read
+  string canonical_scopes = 1;
+}
+
+// User-defined authentication requirements, including support for
+// [JSON Web Token (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32).
+message AuthRequirement {
+  // [id][google.api.AuthProvider.id] from authentication provider.
+  //
+  // Example:
+  //
+  //     provider_id: bookstore_auth
+  string provider_id = 1;
+
+  // 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".
+  //
+  // Example:
+  //
+  //     audiences: bookstore_android.apps.googleusercontent.com,
+  //                bookstore_web.apps.googleusercontent.com
+  string audiences = 2;
+}

google/api/backend.proto

@@ -0,0 +1,45 @@
+// Copyright 2016 Google Inc.
+//
+// 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
+//
+//     http://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";
+
+package google.api;
+
+option java_multiple_files = true;
+option java_outer_classname = "BackendProto";
+option java_package = "com.google.api";
+
+
+// `Backend` defines the backend configuration for a service.
+message Backend {
+  // A list of backend rules providing configuration for individual API
+  // elements.
+  repeated BackendRule rules = 1;
+}
+
+// A backend rule provides configuration for an individual API element.
+message BackendRule {
+  // Selects the methods to which this rule applies.
+  //
+  // Refer to [selector][google.api.DocumentationRule.selector] for syntax details.
+  string selector = 1;
+
+  // The address of the API backend.
+  //
+  string address = 2;
+
+  // The number of seconds to wait for a response from a request.  The
+  // default depends on the deployment context.
+  double deadline = 3;
+}

google/api/billing.proto

@@ -0,0 +1,97 @@
+// Copyright 2016 Google Inc.
+//
+// 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
+//
+//     http://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";
+
+package google.api;
+
+import "google/api/annotations.proto";
+import "google/api/metric.proto";
+
+option java_multiple_files = true;
+option java_outer_classname = "BillingProto";
+option java_package = "com.google.api";
+
+
+// Billing related configuration of the service.
+//
+// The following example shows how to configure metrics for billing:
+//
+//     metrics:
+//     - name: library.googleapis.com/read_calls
+//       metric_kind: DELTA
+//       value_type: INT64
+//     - name: library.googleapis.com/write_calls
+//       metric_kind: DELTA
+//       value_type: INT64
+//     billing:
+//       metrics:
+//       - library.googleapis.com/read_calls
+//       - library.googleapis.com/write_calls
+//
+// The next example shows how to enable billing status check and customize the
+// check behavior. It makes sure billing status check is included in the `Check`
+// method of [Service Control API](https://cloud.google.com/service-control/).
+// In the example, "google.storage.Get" method can be served when the billing
+// status is either `current` or `delinquent`, while "google.storage.Write"
+// method can only be served when the billing status is `current`:
+//
+//     billing:
+//       rules:
+//       - selector: google.storage.Get
+//         allowed_statuses:
+//         - current
+//         - delinquent
+//       - selector: google.storage.Write
+//         allowed_statuses: current
+//
+// Mostly services should only allow `current` status when serving requests.
+// In addition, services can choose to allow both `current` and `delinquent`
+// statuses when serving read-only requests to resources. If there's no
+// matching selector for operation, no billing status check will be performed.
+//
+message Billing {
+  // Names of the metrics to report to billing. Each name must
+  // be defined in [Service.metrics][google.api.Service.metrics] section.
+  repeated string metrics = 1;
+
+  // A list of billing status rules for configuring billing status check.
+  repeated BillingStatusRule rules = 5;
+}
+
+// Defines the billing status requirements for operations.
+//
+// When used with
+// [Service Control API](https://cloud.google.com/service-control/), the
+// following statuses are supported:
+//
+// - **current**: the associated billing account is up to date and capable of
+//                paying for resource usages.
+// - **delinquent**: the associated billing account has a correctable problem,
+//                   such as late payment.
+//
+// Mostly services should only allow `current` status when serving requests.
+// In addition, services can choose to allow both `current` and `delinquent`
+// statuses when serving read-only requests to resources. If the list of
+// allowed_statuses is empty, it means no billing requirement.
+//
+message BillingStatusRule {
+  // Selects the operation names to which this rule applies.
+  // Refer to [selector][google.api.DocumentationRule.selector] for syntax details.
+  string selector = 1;
+
+  // Allowed billing statuses. The billing status check passes if the actual
+  // billing status matches any of the provided values here.
+  repeated string allowed_statuses = 2;
+}

google/api/consumer.proto

@@ -0,0 +1,82 @@
+// Copyright 2016 Google Inc.
+//
+// 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
+//
+//     http://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";
+
+package google.api;
+
+option java_multiple_files = true;
+option java_outer_classname = "ConsumerProto";
+option java_package = "com.google.api";
+
+
+// A descriptor for defining project properties for a service. One service may
+// have many consumer projects, and the service may want to behave differently
+// depending on some properties on the project. For example, a project may be
+// associated with a school, or a business, or a government agency, a business
+// type property on the project may affect how a service responds to the client.
+// This descriptor defines which properties are allowed to be set on a project.
+//
+// Example:
+//
+//    project_properties:
+//      properties:
+//      - name: NO_WATERMARK
+//        type: BOOL
+//        description: Allows usage of the API without watermarks.
+//      - name: EXTENDED_TILE_CACHE_PERIOD
+//        type: INT64
+message ProjectProperties {
+  // List of per consumer project-specific properties.
+  repeated Property properties = 1;
+}
+
+// Defines project properties.
+//
+// API services can define properties that can be assigned to consumer projects
+// so that backends can perform response customization without having to make
+// additional calls or maintain additional storage. For example, Maps API
+// defines properties that controls map tile cache period, or whether to embed a
+// watermark in a result.
+//
+// These values can be set via API producer console. Only API providers can
+// define and set these properties.
+message Property {
+  // Supported data type of the property values
+  enum PropertyType {
+    // The type is unspecified, and will result in an error.
+    UNSPECIFIED = 0;
+
+    // The type is `int64`.
+    INT64 = 1;
+
+    // The type is `bool`.
+    BOOL = 2;
+
+    // The type is `string`.
+    STRING = 3;
+
+    // The type is 'double'.
+    DOUBLE = 4;
+  }
+
+  // The name of the property (a.k.a key).
+  string name = 1;
+
+  // The type of this property.
+  PropertyType type = 2;
+
+  // The description of the property
+  string description = 3;
+}

google/api/context.proto

@@ -0,0 +1,59 @@
+// Copyright 2016 Google Inc.
+//
+// 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
+//
+//     http://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";
+
+package google.api;
+
+option java_multiple_files = true;
+option java_outer_classname = "ContextProto";
+option java_package = "com.google.api";
+
+
+// `Context` defines which contexts an API requests.
+//
+// Example:
+//
+//     context:
+//       rules:
+//       - selector: "*"
+//         requested:
+//         - google.rpc.context.ProjectContext
+//         - google.rpc.context.OriginContext
+//
+// The above specifies that all methods in the API request
+// `google.rpc.context.ProjectContext` and
+// `google.rpc.context.OriginContext`.
+//
+// Available context types are defined in package
+// `google.rpc.context`.
+message Context {
+  // List of rules for context, applicable to methods.
+  repeated ContextRule rules = 1;
+}
+
+// A context rule provides information about the context for an individual API
+// element.
+message ContextRule {
+  // Selects the methods to which this rule applies.
+  //
+  // Refer to [selector][google.api.DocumentationRule.selector] for syntax details.
+  string selector = 1;
+
+  // A list of full type names of requested contexts.
+  repeated string requested = 2;
+
+  // A list of full type names of provided contexts.
+  repeated string provided = 3;
+}

google/api/control.proto

@@ -0,0 +1,32 @@
+// Copyright 2016 Google Inc.
+//
+// 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
+//
+//     http://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";
+
+package google.api;
+
+option java_multiple_files = true;
+option java_outer_classname = "ControlProto";
+option java_package = "com.google.api";
+
+
+// Selects and configures the service controller used by the service.  The
+// service controller handles features like abuse, quota, billing, logging,
+// monitoring, etc.
+//
+message Control {
+  // The service control environment to use. If empty, no control plane
+  // feature (like quota and billing) will be enabled.
+  string environment = 1;
+}

google/api/documentation.proto

@@ -0,0 +1,155 @@
+// Copyright 2016 Google Inc.
+//
+// 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
+//
+//     http://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";
+
+package google.api;
+
+option java_multiple_files = true;
+option java_outer_classname = "DocumentationProto";
+option java_package = "com.google.api";
+
+
+// `Documentation` provides the information for describing a service.
+//
+// Example:
+// <pre><code>documentation:
+//   summary: >
+//     The Google Calendar API gives access
+//     to most calendar features.
+//   pages:
+//   - name: Overview
+//     content: &#40;== include google/foo/overview.md ==&#41;
+//   - name: Tutorial
+//     content: &#40;== include google/foo/tutorial.md ==&#41;
+//     subpages;
+//     - name: Java
+//       content: &#40;== include google/foo/tutorial_java.md ==&#41;
+//   rules:
+//   - selector: google.calendar.Calendar.Get
+//     description: >
+//       ...
+//   - selector: google.calendar.Calendar.Put
+//     description: >
+//       ...
+// </code></pre>
+// Documentation is provided in markdown syntax. In addition to
+// standard markdown features, definition lists, tables and fenced
+// code blocks are supported. Section headers can be provided and are
+// interpreted relative to the section nesting of the context where
+// a documentation fragment is embedded.
+//
+// Documentation from the IDL is merged with documentation defined
+// via the config at normalization time, where documentation provided
+// by config rules overrides IDL provided.
+//
+// A number of constructs specific to the API platform are supported
+// in documentation text.
+//
+// In order to reference a proto element, the following
+// notation can be used:
+// <pre><code>&#91;fully.qualified.proto.name]&#91;]</code></pre>
+// To override the display text used for the link, this can be used:
+// <pre><code>&#91;display text]&#91;fully.qualified.proto.name]</code></pre>
+// Text can be excluded from doc using the following notation:
+// <pre><code>&#40;-- internal comment --&#41;</code></pre>
+// Comments can be made conditional using a visibility label. The below
+// text will be only rendered if the `BETA` label is available:
+// <pre><code>&#40;--BETA: comment for BETA users --&#41;</code></pre>
+// A few directives are available in documentation. Note that
+// directives must appear on a single line to be properly
+// identified. The `include` directive includes a markdown file from
+// an external source:
+// <pre><code>&#40;== include path/to/file ==&#41;</code></pre>
+// The `resource_for` directive marks a message to be the resource of
+// a collection in REST view. If it is not specified, tools attempt
+// to infer the resource from the operations in a collection:
+// <pre><code>&#40;== resource_for v1.shelves.books ==&#41;</code></pre>
+// The directive `suppress_warning` does not directly affect documentation
+// and is documented together with service config validation.
+message Documentation {
+  // A short summary of what the service does. Can only be provided by
+  // plain text.
+  string summary = 1;
+
+  // The top level pages for the documentation set.
+  repeated Page pages = 5;
+
+  // Documentation rules for individual elements of the service.
+  repeated DocumentationRule rules = 3;
+
+  // The URL to the root of documentation.
+  string documentation_root_url = 4;
+
+  // Declares a single overview page. For example:
+  // <pre><code>documentation:
+  //   summary: ...
+  //   overview: &#40;== include overview.md ==&#41;
+  // </code></pre>
+  // This is a shortcut for the following declaration (using pages style):
+  // <pre><code>documentation:
+  //   summary: ...
+  //   pages:
+  //   - name: Overview
+  //     content: &#40;== include overview.md ==&#41;
+  // </code></pre>
+  // Note: you cannot specify both `overview` field and `pages` field.
+  string overview = 2;
+}
+
+// A documentation rule provides information about individual API elements.
+message DocumentationRule {
+  // The selector is a comma-separated list of patterns. Each pattern is a
+  // qualified name of the element which may end in "*", indicating a wildcard.
+  // Wildcards are only allowed at the end and for a whole component of the
+  // qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To
+  // specify a default for all applicable elements, the whole pattern "*"
+  // is used.
+  string selector = 1;
+
+  // Description of the selected API(s).
+  string description = 2;
+
+  // Deprecation description of the selected element(s). It can be provided if an
+  // element is marked as `deprecated`.
+  string deprecation_description = 3;
+}
+
+// Represents a documentation page. A page can contain subpages to represent
+// nested documentation set structure.
+message Page {
+  // The name of the page. It will be used as an identity of the page to
+  // generate URI of the page, text of the link to this page in navigation,
+  // etc. The full page name (start from the root page name to this page
+  // concatenated with `.`) can be used as reference to the page in your
+  // documentation. For example:
+  // <pre><code>pages:
+  // - name: Tutorial
+  //   content: &#40;== include tutorial.md ==&#41;
+  //   subpages:
+  //   - name: Java
+  //     content: &#40;== include tutorial_java.md ==&#41;
+  // </code></pre>
+  // You can reference `Java` page using Markdown reference link syntax:
+  // `[Java][Tutorial.Java]`.
+  string name = 1;
+
+  // The Markdown content of the page. You can use <code>&#40;== include {path} ==&#41;</code>
+  // to include content from a Markdown file.
+  string content = 2;
+
+  // Subpages of this page. The order of subpages specified here will be
+  // honored in the generated docset.
+  repeated Page subpages = 3;
+}

google/api/log.proto

@@ -0,0 +1,53 @@
+// Copyright 2016 Google Inc.
+//
+// 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
+//
+//     http://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";
+
+package google.api;
+
+import "google/api/label.proto";
+
+option java_multiple_files = true;
+option java_outer_classname = "LogProto";
+option java_package = "com.google.api";
+
+
+// A description of a log type. Example in YAML format:
+//
+//     - name: library.googleapis.com/activity_history
+//       description: The history of borrowing and returning library items.
+//       display_name: Activity
+//       labels:
+//       - key: /customer_id
+//         description: Identifier of a library customer
+message LogDescriptor {
+  // The name of the log. It must be less than 512 characters long and can
+  // include the following characters: upper- and lower-case alphanumeric
+  // characters [A-Za-z0-9], and punctuation characters including
+  // slash, underscore, hyphen, period [/_-.].
+  string name = 1;
+
+  // The set of labels that are available to describe a specific log entry.
+  // Runtime requests that contain labels not specified here are
+  // considered invalid.
+  repeated LabelDescriptor labels = 2;
+
+  // A human-readable description of this log. This information appears in
+  // the documentation and can contain details.
+  string description = 3;
+
+  // The human-readable name for this log. This information appears on
+  // the user interface and should be concise.
+  string display_name = 4;
+}

google/api/logging.proto

@@ -0,0 +1,82 @@
+// Copyright 2016 Google Inc.
+//
+// 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
+//
+//     http://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";
+
+package google.api;
+
+import "google/api/annotations.proto";
+
+option java_multiple_files = true;
+option java_outer_classname = "LoggingProto";
+option java_package = "com.google.api";
+
+
+// Logging configuration of the service.
+//
+// The following example shows how to configure logs to be sent to the
+// producer and consumer projects. In the example,
+// the `library.googleapis.com/activity_history` log is
+// sent to both the producer and consumer projects, whereas
+// the `library.googleapis.com/purchase_history` log is only sent to the
+// producer project:
+//
+//     monitored_resources:
+//     - type: library.googleapis.com/branch
+//       labels:
+//       - key: /city
+//         description: The city where the library branch is located in.
+//       - key: /name
+//         description: The name of the branch.
+//     logs:
+//     - name: library.googleapis.com/activity_history
+//       labels:
+//       - key: /customer_id
+//     - name: library.googleapis.com/purchase_history
+//     logging:
+//       producer_destinations:
+//       - monitored_resource: library.googleapis.com/branch
+//         logs:
+//         - library.googleapis.com/activity_history
+//         - library.googleapis.com/purchase_history
+//       consumer_destinations:
+//       - monitored_resource: library.googleapis.com/branch
+//         logs:
+//         - library.googleapis.com/activity_history
+//
+message Logging {
+  // Configuration of a specific logging destination (the producer project
+  // or the consumer project).
+  message LoggingDestination {
+    // The monitored resource type. The type must be defined in
+    // [Service.monitored_resources][google.api.Service.monitored_resources] section.
+    string monitored_resource = 3;
+
+    // Names of the logs to be sent to this destination. Each name must
+    // be defined in the [Service.logs][google.api.Service.logs] section.
+    repeated string logs = 1;
+  }
+
+  // Logging configurations for sending logs to the producer project.
+  // There can be multiple producer destinations, each one must have a
+  // different monitored resource type. A log can be used in at most
+  // one producer destination.
+  repeated LoggingDestination producer_destinations = 1;
+
+  // Logging configurations for sending logs to the consumer project.
+  // There can be multiple consumer destinations, each one must have a
+  // different monitored resource type. A log can be used in at most
+  // one consumer destination.
+  repeated LoggingDestination consumer_destinations = 2;
+}

google/api/metric.proto

@@ -0,0 +1,189 @@
+// Copyright 2016 Google Inc.
+//
+// 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
+//
+//     http://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";
+
+package google.api;
+
+import "google/api/label.proto";
+
+option java_multiple_files = true;
+option java_outer_classname = "MetricProto";
+option java_package = "com.google.api";
+
+
+// Defines a metric type and its schema.
+message MetricDescriptor {
+  // The kind of measurement. It describes how the data is reported.
+  enum MetricKind {
+    // Do not use this default value.
+    METRIC_KIND_UNSPECIFIED = 0;
+
+    // Instantaneous measurements of a varying quantity.
+    GAUGE = 1;
+
+    // Changes over non-overlapping time intervals.
+    DELTA = 2;
+
+    // Cumulative value over time intervals that can overlap.
+    // The overlapping intervals must have the same start time.
+    CUMULATIVE = 3;
+  }
+
+  // The value type of a metric.
+  enum ValueType {
+    // Do not use this default value.
+    VALUE_TYPE_UNSPECIFIED = 0;
+
+    // The value is a boolean.
+    // This value type can be used only if the metric kind is `GAUGE`.
+    BOOL = 1;
+
+    // The value is a signed 64-bit integer.
+    INT64 = 2;
+
+    // The value is a double precision floating point number.
+    DOUBLE = 3;
+
+    // The value is a text string.
+    // This value type can be used only if the metric kind is `GAUGE`.
+    STRING = 4;
+
+    // The value is a [`Distribution`][google.api.Distribution].
+    DISTRIBUTION = 5;
+
+    // The value is money.
+    MONEY = 6;
+  }
+
+  // Resource name. The format of the name may vary between different
+  // implementations. For examples:
+  //
+  //     projects/{project_id}/metricDescriptors/{type=**}
+  //     metricDescriptors/{type=**}
+  string name = 1;
+
+  // The metric type including a DNS name prefix, for example
+  // `"compute.googleapis.com/instance/cpu/utilization"`. Metric types
+  // should use a natural hierarchical grouping such as the following:
+  //
+  //     compute.googleapis.com/instance/cpu/utilization
+  //     compute.googleapis.com/instance/disk/read_ops_count
+  //     compute.googleapis.com/instance/network/received_bytes_count
+  //
+  // Note that if the metric type changes, the monitoring data will be
+  // discontinued, and anything depends on it will break, such as monitoring
+  // dashboards, alerting rules and quota limits. Therefore, once a metric has
+  // been published, its type should be immutable.
+  string type = 8;
+
+  // The set of labels that can be used to describe a specific instance of this
+  // metric type. For example, the
+  // `compute.googleapis.com/instance/network/received_bytes_count` metric type
+  // has a label, `loadbalanced`, that specifies whether the traffic was
+  // received through a load balanced IP address.
+  repeated LabelDescriptor labels = 2;
+
+  // Whether the metric records instantaneous values, changes to a value, etc.
+  MetricKind metric_kind = 3;
+
+  // Whether the measurement is an integer, a floating-point number, etc.
+  ValueType value_type = 4;
+
+  // The unit in which the metric value is reported. It is only applicable
+  // if the `value_type` is `INT64`, `DOUBLE`, or `DISTRIBUTION`. The
+  // supported units are a subset of [The Unified Code for Units of
+  // Measure](http://unitsofmeasure.org/ucum.html) standard:
+  //
+  // **Basic units (UNIT)**
+  //
+  // * `bit`   bit
+  // * `By`    byte
+  // * `s`     second
+  // * `min`   minute
+  // * `h`     hour
+  // * `d`     day
+  //
+  // **Prefixes (PREFIX)**
+  //
+  // * `k`     kilo    (10**3)
+  // * `M`     mega    (10**6)
+  // * `G`     giga    (10**9)
+  // * `T`     tera    (10**12)
+  // * `P`     peta    (10**15)
+  // * `E`     exa     (10**18)
+  // * `Z`     zetta   (10**21)
+  // * `Y`     yotta   (10**24)
+  // * `m`     milli   (10**-3)
+  // * `u`     micro   (10**-6)
+  // * `n`     nano    (10**-9)
+  // * `p`     pico    (10**-12)
+  // * `f`     femto   (10**-15)
+  // * `a`     atto    (10**-18)
+  // * `z`     zepto   (10**-21)
+  // * `y`     yocto   (10**-24)
+  // * `Ki`    kibi    (2**10)
+  // * `Mi`    mebi    (2**20)
+  // * `Gi`    gibi    (2**30)
+  // * `Ti`    tebi    (2**40)
+  //
+  // **Grammar**
+  //
+  // The grammar includes the dimensionless unit `1`, such as `1/s`.
+  //
+  // The grammar also includes these connectors:
+  //
+  // * `/`    division (as an infix operator, e.g. `1/s`).
+  // * `.`    multiplication (as an infix operator, e.g. `GBy.d`)
+  //
+  // The grammar for a unit is as follows:
+  //
+  //     Expression = Component { "." Component } { "/" Component } ;
+  //
+  //     Component = [ PREFIX ] UNIT [ Annotation ]
+  //               | Annotation
+  //               | "1"
+  //               ;
+  //
+  //     Annotation = "{" NAME "}" ;
+  //
+  // Notes:
+  //
+  // * `Annotation` is just a comment if it follows a `UNIT` and is
+  //    equivalent to `1` if it is used alone. For examples,
+  //    `{requests}/s == 1/s`, `By{transmitted}/s == By/s`.
+  // * `NAME` is a sequence of non-blank printable ASCII characters not
+  //    containing '{' or '}'.
+  string unit = 5;
+
+  // A detailed description of the metric, which can be used in documentation.
+  string description = 6;
+
+  // A concise name for the metric, which can be displayed in user interfaces.
+  // Use sentence case without an ending period, for example "Request count".
+  string display_name = 7;
+}
+
+// A specific metric identified by specifying values for all of the
+// labels of a [`MetricDescriptor`][google.api.MetricDescriptor].
+message Metric {
+  // An existing metric type, see [google.api.MetricDescriptor][google.api.MetricDescriptor].
+  // For example, `compute.googleapis.com/instance/cpu/usage_time`.
+  string type = 3;
+
+  // The set of labels that uniquely identify a metric. To specify a
+  // metric, all labels enumerated in the `MetricDescriptor` must be
+  // assigned values.
+  map<string, string> labels = 2;
+}

google/api/monitoring.proto

@@ -0,0 +1,88 @@
+// Copyright 2016 Google Inc.
+//
+// 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
+//
+//     http://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";
+
+package google.api;
+
+import "google/api/annotations.proto";
+
+option java_multiple_files = true;
+option java_outer_classname = "MonitoringProto";
+option java_package = "com.google.api";
+
+
+// Monitoring configuration of the service.
+//
+// The example below shows how to configure monitored resources and metrics
+// for monitoring. In the example, a monitored resource and two metrics are
+// defined. The `library.googleapis.com/book/returned_count` metric is sent
+// to both producer and consumer projects, whereas the
+// `library.googleapis.com/book/overdue_count` metric is only sent to the
+// consumer project.
+//
+//     monitored_resources:
+//     - type: library.googleapis.com/branch
+//       labels:
+//       - key: /city
+//         description: The city where the library branch is located in.
+//       - key: /name
+//         description: The name of the branch.
+//     metrics:
+//     - name: library.googleapis.com/book/returned_count
+//       metric_kind: DELTA
+//       value_type: INT64
+//       labels:
+//       - key: /customer_id
+//     - name: library.googleapis.com/book/overdue_count
+//       metric_kind: GAUGE
+//       value_type: INT64
+//       labels:
+//       - key: /customer_id
+//     monitoring:
+//       producer_destinations:
+//       - monitored_resource: library.googleapis.com/branch
+//         metrics:
+//         - library.googleapis.com/book/returned_count
+//       consumer_destinations:
+//       - monitored_resource: library.googleapis.com/branch
+//         metrics:
+//         - library.googleapis.com/book/returned_count
+//         - library.googleapis.com/book/overdue_count
+//
+message Monitoring {
+  // Configuration of a specific monitoring destination (the producer project
+  // or the consumer project).
+  message MonitoringDestination {
+    // The monitored resource type. The type must be defined in
+    // [Service.monitored_resources][google.api.Service.monitored_resources] section.
+    string monitored_resource = 1;
+
+    // Names of the metrics to report to this monitoring destination.
+    // Each name must be defined in [Service.metrics][google.api.Service.metrics] section.
+    repeated string metrics = 2;
+  }
+
+  // Monitoring configurations for sending metrics to the producer project.
+  // There can be multiple producer destinations, each one must have a
+  // different monitored resource type. A metric can be used in at most
+  // one producer destination.
+  repeated MonitoringDestination producer_destinations = 1;
+
+  // Monitoring configurations for sending metrics to the consumer project.
+  // There can be multiple consumer destinations, each one must have a
+  // different monitored resource type. A metric can be used in at most
+  // one consumer destination.
+  repeated MonitoringDestination consumer_destinations = 2;
+}

google/api/service.proto

@@ -0,0 +1,159 @@
+// Copyright 2016 Google Inc.
+//
+// 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
+//
+//     http://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";
+
+package google.api;
+
+import "google/api/annotations.proto";
+import "google/api/auth.proto";
+import "google/api/backend.proto";
+import "google/api/billing.proto";
+import "google/api/consumer.proto";
+import "google/api/context.proto";
+import "google/api/control.proto";
+import "google/api/documentation.proto";
+import "google/api/http.proto";
+import "google/api/label.proto";
+import "google/api/log.proto";
+import "google/api/logging.proto";
+import "google/api/metric.proto";
+import "google/api/monitored_resource.proto";
+import "google/api/monitoring.proto";
+import "google/api/system_parameter.proto";
+import "google/api/usage.proto";
+import "google/protobuf/any.proto";
+import "google/protobuf/api.proto";
+import "google/protobuf/type.proto";
+import "google/protobuf/wrappers.proto";
+
+option java_multiple_files = true;
+option java_outer_classname = "ServiceProto";
+option java_package = "com.google.api";
+
+
+// `Service` is the root object of the configuration schema. It
+// describes basic information like the name of the service and the
+// exposed API interfaces, and delegates other aspects to configuration
+// sub-sections.
+//
+// Example:
+//
+//     type: google.api.Service
+//     config_version: 1
+//     name: calendar.googleapis.com
+//     title: Google Calendar API
+//     apis:
+//     - name: google.calendar.Calendar
+//     backend:
+//       rules:
+//       - selector: "*"
+//         address: calendar.example.com
+message Service {
+  // The version of the service configuration. The config version may
+  // influence interpretation of the configuration, for example, to
+  // determine defaults. This is documented together with applicable
+  // options. The current default for the config version itself is `3`.
+  google.protobuf.UInt32Value config_version = 20;
+
+  // The DNS address at which this service is available,
+  // e.g. `calendar.googleapis.com`.
+  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.
+  string id = 33;
+
+  // The product title associated with this service.
+  string title = 2;
+
+  // The id of the Google developer project that owns the service.
+  // Members of this project can manage the service configuration,
+  // manage consumption of the service, etc.
+  string producer_project_id = 22;
+
+  // A list of API interfaces exported by this service. Only the `name` field
+  // of the [google.protobuf.Api][google.protobuf.Api] needs to be provided by the configuration
+  // author, as the remaining fields will be derived from the IDL during the
+  // normalization process. It is an error to specify an API interface here
+  // which cannot be resolved against the associated IDL files.
+  repeated google.protobuf.Api apis = 3;
+
+  // A list of all proto message types included in this API service.
+  // Types referenced directly or indirectly by the `apis` are
+  // automatically included.  Messages which are not referenced but
+  // shall be included, such as types used by the `google.protobuf.Any` type,
+  // should be listed here by name. Example:
+  //
+  //     types:
+  //     - name: google.protobuf.Int32
+  repeated google.protobuf.Type types = 4;
+
+  // A list of all enum types included in this API service.  Enums
+  // referenced directly or indirectly by the `apis` are automatically
+  // included.  Enums which are not referenced but shall be included
+  // should be listed here by name. Example:
+  //
+  //     enums:
+  //     - name: google.someapi.v1.SomeEnum
+  repeated google.protobuf.Enum enums = 5;
+
+  // Additional API documentation.
+  Documentation documentation = 6;
+
+  // API backend configuration.
+  Backend backend = 8;
+
+  // HTTP configuration.
+  Http http = 9;
+
+  // Auth configuration.
+  Authentication authentication = 11;
+
+  // Context configuration.
+  Context context = 12;
+
+  // Configuration controlling usage of this service.
+  Usage usage = 15;
+
+  // Configuration of per-consumer project properties.
+  ProjectProperties project_properties = 17;
+
+  // Configuration for the service control plane.
+  Control control = 21;
+
+  // Defines the logs used by this service.
+  repeated LogDescriptor logs = 23;
+
+  // Defines the metrics used by this service.
+  repeated MetricDescriptor metrics = 24;
+
+  // Defines the monitored resources used by this service. This is required
+  // by the [Service.monitoring][google.api.Service.monitoring] and [Service.logging][google.api.Service.logging] configurations.
+  //
+  repeated MonitoredResourceDescriptor monitored_resources = 25;
+
+  // Billing configuration of the service.
+  Billing billing = 26;
+
+  // Logging configuration of the service.
+  Logging logging = 27;
+
+  // Monitoring configuration of the service.
+  Monitoring monitoring = 28;
+
+  // Configuration for system parameters.
+  SystemParameters system_parameters = 29;
+}

google/api/system_parameter.proto

@@ -0,0 +1,94 @@
+// Copyright 2016 Google Inc.
+//
+// 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
+//
+//     http://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";
+
+package google.api;
+
+option java_multiple_files = true;
+option java_outer_classname = "SystemParameterProto";
+option java_package = "com.google.api";
+
+
+// ### System parameter configuration
+//
+// A system parameter is a special kind of parameter defined by the API
+// system, not by an individual API. It is typically mapped to an HTTP header
+// and/or a URL query parameter. This configuration specifies which methods
+// change the names of the system parameters.
+message SystemParameters {
+  // Define system parameters.
+  //
+  // The parameters defined here will override the default parameters
+  // implemented by the system. If this field is missing from the service
+  // config, default system parameters will be used. Default system parameters
+  // and names is implementation-dependent.
+  //
+  // Example: define api key and alt name for all methods
+  //
+  // SystemParameters
+  //   rules:
+  //     - selector: "*"
+  //       parameters:
+  //         - name: api_key
+  //           url_query_parameter: api_key
+  //         - name: alt
+  //           http_header: Response-Content-Type
+  //
+  // Example: define 2 api key names for a specific method.
+  //
+  // SystemParameters
+  //   rules:
+  //     - selector: "/ListShelves"
+  //       parameters:
+  //         - name: api_key
+  //           http_header: Api-Key1
+  //         - name: api_key
+  //           http_header: Api-Key2
+  repeated SystemParameterRule rules = 1;
+}
+
+// Define a system parameter rule mapping system parameter definitions to
+// methods.
+message SystemParameterRule {
+  // Selects the methods to which this rule applies. Use '*' to indicate all
+  // methods in all APIs.
+  //
+  // Refer to [selector][google.api.DocumentationRule.selector] for syntax details.
+  string selector = 1;
+
+  // Define parameters. Multiple names may be defined for a parameter.
+  // For a given method call, only one of them should be used. If multiple
+  // names are used the behavior is implementation-dependent.
+  // If none of the specified names are present the behavior is
+  // parameter-dependent.
+  repeated SystemParameter parameters = 2;
+}
+
+// Define a parameter's name and location. The parameter may be passed as either
+// an HTTP header or a URL query parameter, and if both are passed the behavior
+// is implementation-dependent.
+message SystemParameter {
+  // Define the name of the parameter, such as "api_key", "alt", "callback",
+  // and etc. It is case sensitive.
+  string name = 1;
+
+  // Define the HTTP header name to use for the parameter. It is case
+  // insensitive.
+  string http_header = 2;
+
+  // Define the URL query parameter name to use for the parameter. It is case
+  // sensitive.
+  string url_query_parameter = 3;
+}

google/api/usage.proto

@@ -0,0 +1,131 @@
+// Copyright 2016 Google Inc.
+//
+// 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
+//
+//     http://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";
+
+package google.api;
+
+option java_multiple_files = true;
+option java_outer_classname = "UsageProto";
+option java_package = "com.google.api";
+
+
+// Configuration controlling usage of a service.
+message Usage {
+  // Service access types.
+  //
+  // Access to restricted API features is always controlled by
+  // [visibility][google.api.Visibility], independent of the ServiceAccess type.
+  //
+  enum ServiceAccess {
+    // The service can only be seen/used by users identified in the service's
+    // access control policy.
+    //
+    // If the service has not been whitelisted by your domain administrator
+    // for out-of-org publishing, then this mode will be treated like
+    // ORG_RESTRICTED.
+    RESTRICTED = 0;
+
+    // The service can be seen/used by anyone.
+    //
+    // If the service has not been whitelisted by your domain administrator
+    // for out-of-org publishing, then this mode will be treated like
+    // ORG_PUBLIC.
+    //
+    // The discovery document for the service will also be public and allow
+    // unregistered access.
+    PUBLIC = 1;
+
+    // The service can be seen/used by users identified in the service's
+    // access control policy and they are within the organization that owns the
+    // service.
+    //
+    // Access is further constrained to the group
+    // controlled by the administrator of the project/org that owns the
+    // service.
+    ORG_RESTRICTED = 2;
+
+    // The service can be seen/used by the group of users controlled by the
+    // administrator of the project/org that owns the service.
+    ORG_PUBLIC = 3;
+  }
+
+  // Controls which users can see or activate the service.
+  ServiceAccess service_access = 4;
+
+  // Requirements that must be satisfied before a consumer project can use the
+  // service. Each requirement is of the form <service.name>/<requirement-id>;
+  // for example 'serviceusage.googleapis.com/billing-enabled'.
+  repeated string requirements = 1;
+
+  // Services that must be activated in order for this service to be used.
+  // The set of services activated as a result of these relations are all
+  // activated in parallel with no guaranteed order of activation.
+  // Each string is a service name, e.g. `calendar.googleapis.com`.
+  repeated string depends_on_services = 2;
+
+  // Services that must be contacted before a consumer can begin using the
+  // service. Each service will be contacted in sequence, and, if any activation
+  // call fails, the entire activation will fail. Each hook is of the form
+  // <service.name>/<hook-id>, where <hook-id> is optional; for example:
+  // 'robotservice.googleapis.com/default'.
+  repeated string activation_hooks = 3;
+
+  // Services that must be contacted before a consumer can deactivate a
+  // service. Each service will be contacted in sequence, and, if any
+  // deactivation call fails, the entire deactivation will fail. Each hook is
+  // of the form <service.name>/<hook-id>, where <hook-id> is optional; for
+  // example:
+  // 'compute.googleapis.com/'.
+  repeated string deactivation_hooks = 5;
+
+  // Individual rules for configuring usage on selected methods.
+  repeated UsageRule rules = 6;
+}
+
+// Usage configuration rules for the service.
+//
+// NOTE: Under development.
+//
+//
+// Use this rule to configure unregistered calls for the service. Unregistered
+// calls are calls that do not contain consumer project identity.
+// (Example: calls that do not contain an API key).
+// By default, API methods do not allow unregistered calls, and each method call
+// must be identified by a consumer project identity. Use this rule to
+// allow/disallow unregistered calls.
+//
+// Example of an API that wants to allow unregistered calls for entire service.
+//
+//     usage:
+//       rules:
+//       - selector: "*"
+//         allow_unregistered_calls: true
+//
+// Example of a method that wants to allow unregistered calls.
+//
+//     usage:
+//       rules:
+//       - selector: "google.example.library.v1.LibraryService.CreateBook"
+//         allow_unregistered_calls: true
+message UsageRule {
+  // Selects the methods to which this rule applies. Use '*' to indicate all
+  // methods in all APIs.
+  //
+  // Refer to [selector][google.api.DocumentationRule.selector] for syntax details.
+  string selector = 1;
+
+  // True, if the method allows unregistered calls; false otherwise.
+  bool allow_unregistered_calls = 2;
+}

google/devtools/source/v1/source_context.proto

@@ -0,0 +1,179 @@
+// Copyright (c) 2016, Google Inc.
+//
+// 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
+//
+//     http://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";
+
+package google.devtools.source.v1;
+
+import "google/api/annotations.proto";
+
+option java_multiple_files = true;
+option java_outer_classname = "SourceContextProto";
+option java_package = "com.google.devtools.source.v1";
+
+
+// A SourceContext is a reference to a tree of files. A SourceContext together
+// with a path point to a unique revision of a single file or directory.
+message SourceContext {
+  // A SourceContext can refer any one of the following types of repositories.
+  oneof context {
+    // A SourceContext referring to a revision in a cloud repo.
+    CloudRepoSourceContext cloud_repo = 1;
+
+    // A SourceContext referring to a snapshot in a cloud workspace.
+    CloudWorkspaceSourceContext cloud_workspace = 2;
+
+    // A SourceContext referring to a Gerrit project.
+    GerritSourceContext gerrit = 3;
+
+    // A SourceContext referring to any third party Git repo (e.g. GitHub).
+    GitSourceContext git = 6;
+  }
+}
+
+// An ExtendedSourceContext is a SourceContext combined with additional
+// details describing the context.
+message ExtendedSourceContext {
+  // Any source context.
+  SourceContext context = 1;
+
+  // Labels with user defined metadata.
+  map<string, string> labels = 2;
+}
+
+// An alias to a repo revision.
+message AliasContext {
+  // The type of an Alias.
+  enum Kind {
+    // Do not use.
+    ANY = 0;
+
+    // Git tag
+    FIXED = 1;
+
+    // Git branch
+    MOVABLE = 2;
+
+    // OTHER is used to specify non-standard aliases, those not of the kinds
+    // above. For example, if a Git repo has a ref named "refs/foo/bar", it
+    // is considered to be of kind OTHER.
+    OTHER = 4;
+  }
+
+  // The alias kind.
+  Kind kind = 1;
+
+  // The alias name.
+  string name = 2;
+}
+
+// A CloudRepoSourceContext denotes a particular revision in a cloud
+// repo (a repo hosted by the Google Cloud Platform).
+message CloudRepoSourceContext {
+  // The ID of the repo.
+  RepoId repo_id = 1;
+
+  // A revision in a cloud repository can be identified by either its revision
+  // ID or its Alias.
+  oneof revision {
+    // A revision ID.
+    string revision_id = 2;
+
+    // The name of an alias (branch, tag, etc.).
+    string alias_name = 3;
+
+    // An alias, which may be a branch or tag.
+    AliasContext alias_context = 4;
+  }
+}
+
+// A CloudWorkspaceSourceContext denotes a workspace at a particular snapshot.
+message CloudWorkspaceSourceContext {
+  // The ID of the workspace.
+  CloudWorkspaceId workspace_id = 1;
+
+  // The ID of the snapshot.
+  // An empty snapshot_id refers to the most recent snapshot.
+  string snapshot_id = 2;
+}
+
+// A SourceContext referring to a Gerrit project.
+message GerritSourceContext {
+  // The URI of a running Gerrit instance.
+  string host_uri = 1;
+
+  // The full project name within the host. Projects may be nested, so
+  // "project/subproject" is a valid project name.
+  // The "repo name" is hostURI/project.
+  string gerrit_project = 2;
+
+  // A revision in a Gerrit project can be identified by either its revision ID
+  // or its alias.
+  oneof revision {
+    // A revision (commit) ID.
+    string revision_id = 3;
+
+    // The name of an alias (branch, tag, etc.).
+    string alias_name = 4;
+
+    // An alias, which may be a branch or tag.
+    AliasContext alias_context = 5;
+  }
+}
+
+// A GitSourceContext denotes a particular revision in a third party Git
+// repository (e.g. GitHub).
+message GitSourceContext {
+  // Git repository URL.
+  string url = 1;
+
+  // Git commit hash.
+  // required.
+  string revision_id = 2;
+}
+
+// A unique identifier for a cloud repo.
+message RepoId {
+  // A cloud repository can be identified by either its project ID and
+  // repository name combination, or its globally unique identifier.
+  oneof id {
+    // A combination of a project ID and a repo name.
+    ProjectRepoId project_repo_id = 1;
+
+    // A server-assigned, globally unique identifier.
+    string uid = 2;
+  }
+}
+
+// Selects a repo using a Google Cloud Platform project ID
+// (e.g. winged-cargo-31) and a repo name within that project.
+message ProjectRepoId {
+  // The ID of the project.
+  string project_id = 1;
+
+  // The name of the repo. Leave empty for the default repo.
+  string repo_name = 2;
+}
+
+// A CloudWorkspaceId is a unique identifier for a cloud workspace.
+// A cloud workspace is a place associated with a repo where modified files
+// can be stored before they are committed.
+message CloudWorkspaceId {
+  // The ID of the repo containing the workspace.
+  RepoId repo_id = 1;
+
+  // The unique name of the workspace within the repo.  This is the name
+  // chosen by the client in the Source API's CreateWorkspace method.
+  string name = 2;
+}