codekingpro/portable-devtools

1// Copyright 2026 Google LLC2//3// Licensed under the Apache License, Version 2.0 (the "License");4// you may not use this file except in compliance with the License.5// You may obtain a copy of the License at6//7//     http://www.apache.org/licenses/LICENSE-2.08//9// Unless required by applicable law or agreed to in writing, software10// distributed under the License is distributed on an "AS IS" BASIS,11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.12// See the License for the specific language governing permissions and13// limitations under the License.14 15syntax = "proto3";16 17package google.api;18 19import "google/protobuf/descriptor.proto";20 21option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations";22option java_multiple_files = true;23option java_outer_classname = "ResourceProto";24option java_package = "com.google.api";25option objc_class_prefix = "GAPI";26 27extend google.protobuf.FieldOptions {28  // An annotation that describes a resource reference, see29  // [ResourceReference][].30  google.api.ResourceReference resource_reference = 1055;31}32 33extend google.protobuf.FileOptions {34  // An annotation that describes a resource definition without a corresponding35  // message; see [ResourceDescriptor][].36  repeated google.api.ResourceDescriptor resource_definition = 1053;37}38 39extend google.protobuf.MessageOptions {40  // An annotation that describes a resource definition, see41  // [ResourceDescriptor][].42  google.api.ResourceDescriptor resource = 1053;43}44 45// A simple descriptor of a resource type.46//47// ResourceDescriptor annotates a resource message (either by means of a48// protobuf annotation or use in the service config), and associates the49// resource's schema, the resource type, and the pattern of the resource name.50//51// Example:52//53//     message Topic {54//       // Indicates this message defines a resource schema.55//       // Declares the resource type in the format of {service}/{kind}.56//       // For Kubernetes resources, the format is {api group}/{kind}.57//       option (google.api.resource) = {58//         type: "pubsub.googleapis.com/Topic"59//         pattern: "projects/{project}/topics/{topic}"60//       };61//     }62//63// The ResourceDescriptor Yaml config will look like:64//65//     resources:66//     - type: "pubsub.googleapis.com/Topic"67//       pattern: "projects/{project}/topics/{topic}"68//69// Sometimes, resources have multiple patterns, typically because they can70// live under multiple parents.71//72// Example:73//74//     message LogEntry {75//       option (google.api.resource) = {76//         type: "logging.googleapis.com/LogEntry"77//         pattern: "projects/{project}/logs/{log}"78//         pattern: "folders/{folder}/logs/{log}"79//         pattern: "organizations/{organization}/logs/{log}"80//         pattern: "billingAccounts/{billing_account}/logs/{log}"81//       };82//     }83//84// The ResourceDescriptor Yaml config will look like:85//86//     resources:87//     - type: 'logging.googleapis.com/LogEntry'88//       pattern: "projects/{project}/logs/{log}"89//       pattern: "folders/{folder}/logs/{log}"90//       pattern: "organizations/{organization}/logs/{log}"91//       pattern: "billingAccounts/{billing_account}/logs/{log}"92message ResourceDescriptor {93  // A description of the historical or future-looking state of the94  // resource pattern.95  enum History {96    // The "unset" value.97    HISTORY_UNSPECIFIED = 0;98 99    // The resource originally had one pattern and launched as such, and100    // additional patterns were added later.101    ORIGINALLY_SINGLE_PATTERN = 1;102 103    // The resource has one pattern, but the API owner expects to add more104    // later. (This is the inverse of ORIGINALLY_SINGLE_PATTERN, and prevents105    // that from being necessary once there are multiple patterns.)106    FUTURE_MULTI_PATTERN = 2;107  }108 109  // A flag representing a specific style that a resource claims to conform to.110  enum Style {111    // The unspecified value. Do not use.112    STYLE_UNSPECIFIED = 0;113 114    // This resource is intended to be "declarative-friendly".115    //116    // Declarative-friendly resources must be more strictly consistent, and117    // setting this to true communicates to tools that this resource should118    // adhere to declarative-friendly expectations.119    //120    // Note: This is used by the API linter (linter.aip.dev) to enable121    // additional checks.122    DECLARATIVE_FRIENDLY = 1;123  }124 125  // The resource type. It must be in the format of126  // {service_name}/{resource_type_kind}. The `resource_type_kind` must be127  // singular and must not include version numbers.128  //129  // Example: `storage.googleapis.com/Bucket`130  //131  // The value of the resource_type_kind must follow the regular expression132  // /[A-Za-z][a-zA-Z0-9]+/. It should start with an upper case character and133  // should use PascalCase (UpperCamelCase). The maximum number of134  // characters allowed for the `resource_type_kind` is 100.135  string type = 1;136 137  // Optional. The relative resource name pattern associated with this resource138  // type. The DNS prefix of the full resource name shouldn't be specified here.139  //140  // The path pattern must follow the syntax, which aligns with HTTP binding141  // syntax:142  //143  //     Template = Segment { "/" Segment } ;144  //     Segment = LITERAL | Variable ;145  //     Variable = "{" LITERAL "}" ;146  //147  // Examples:148  //149  //     - "projects/{project}/topics/{topic}"150  //     - "projects/{project}/knowledgeBases/{knowledge_base}"151  //152  // The components in braces correspond to the IDs for each resource in the153  // hierarchy. It is expected that, if multiple patterns are provided,154  // the same component name (e.g. "project") refers to IDs of the same155  // type of resource.156  repeated string pattern = 2;157 158  // Optional. The field on the resource that designates the resource name159  // field. If omitted, this is assumed to be "name".160  string name_field = 3;161 162  // Optional. The historical or future-looking state of the resource pattern.163  //164  // Example:165  //166  //     // The InspectTemplate message originally only supported resource167  //     // names with organization, and project was added later.168  //     message InspectTemplate {169  //       option (google.api.resource) = {170  //         type: "dlp.googleapis.com/InspectTemplate"171  //         pattern:172  //         "organizations/{organization}/inspectTemplates/{inspect_template}"173  //         pattern: "projects/{project}/inspectTemplates/{inspect_template}"174  //         history: ORIGINALLY_SINGLE_PATTERN175  //       };176  //     }177  History history = 4;178 179  // The plural name used in the resource name and permission names, such as180  // 'projects' for the resource name of 'projects/{project}' and the permission181  // name of 'cloudresourcemanager.googleapis.com/projects.get'. One exception182  // to this is for Nested Collections that have stuttering names, as defined183  // in [AIP-122](https://google.aip.dev/122#nested-collections), where the184  // collection ID in the resource name pattern does not necessarily directly185  // match the `plural` value.186  //187  // It is the same concept of the `plural` field in k8s CRD spec188  // https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/189  //190  // Note: The plural form is required even for singleton resources. See191  // https://aip.dev/156192  string plural = 5;193 194  // The same concept of the `singular` field in k8s CRD spec195  // https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/196  // Such as "project" for the `resourcemanager.googleapis.com/Project` type.197  string singular = 6;198 199  // Style flag(s) for this resource.200  // These indicate that a resource is expected to conform to a given201  // style. See the specific style flags for additional information.202  repeated Style style = 10;203}204 205// Defines a proto annotation that describes a string field that refers to206// an API resource.207message ResourceReference {208  // The resource type that the annotated field references.209  //210  // Example:211  //212  //     message Subscription {213  //       string topic = 2 [(google.api.resource_reference) = {214  //         type: "pubsub.googleapis.com/Topic"215  //       }];216  //     }217  //218  // Occasionally, a field may reference an arbitrary resource. In this case,219  // APIs use the special value * in their resource reference.220  //221  // Example:222  //223  //     message GetIamPolicyRequest {224  //       string resource = 2 [(google.api.resource_reference) = {225  //         type: "*"226  //       }];227  //     }228  string type = 1;229 230  // The resource type of a child collection that the annotated field231  // references. This is useful for annotating the `parent` field that232  // doesn't have a fixed resource type.233  //234  // Example:235  //236  //     message ListLogEntriesRequest {237  //       string parent = 1 [(google.api.resource_reference) = {238  //         child_type: "logging.googleapis.com/LogEntry"239  //       };240  //     }241  string child_type = 2;242}243