field_info.proto

syntax = "proto3";

package aep.api;

option cc_enable_arenas = true;
option java_multiple_files = true;
option java_outer_classname = "FieldInfoProto";
option java_package = "dev.aep.api";
option objc_class_prefix = "AEP";

import "google/protobuf/descriptor.proto";
import "google/protobuf/duration.proto";
import "aep/api/field_behavior.proto";

// A field option documenting the applicable lifetime of a field, e.g. an
// idempotency key.
extend google.protobuf.FieldOptions {
  FieldInfo field_info = 10520;
}

// Various options related to the behavior of a field.
//
// This is, conceptually, supplementary to `google.api.FieldInfo`.
message FieldInfo {
  // The minimum guaranteed duration for which the field value applies.
  //
  // For example, if an `idempotency_key` field has a lifetime of one hour, then
  // subsequent requests made after one hour should not assume any idempotency
  // guarantees from using the same idempotency key.
  //
  // This option only specifies a _minimum_ lifetime. APIs may honor fields for
  // longer than the minimum lifetime, and API consumers should not assume that
  // the minimum lifetime is a strict cutoff. For example, an API may honor an
  // idempotency key indefinitely, whatever the value of this field option.
  google.protobuf.Duration minimum_lifetime = 1;

  // The resource type that the annotated field references.
  //
  // Example:
  //
  //     message Subscription {
  //       string topic = 2 [(aep.api.field_info) = {
  //         resource_reference: "library.example.com/Topic"
  //           // multiple types are allowed.
  //         resource_reference: "library.example.com/OtherTopic"
  //       }];
  //     }
  //
  // Occasionally, a field may reference an arbitrary resource. In this case,
  // APIs use the special value * in their resource reference.
  //
  // Example:
  //
  //     message GetResourceRequest {
  //       string resource = 2 [(aep.api.field_info) = {
  //         resource_reference: "*"
  //       }];
  //     }
  repeated string resource_reference = 2;

  // The resource type that the child collection annotates.
  repeated string resource_reference_child_type = 4;

  // Describes the behavior of the field in requests and responses.
  repeated FieldBehavior field_behavior = 3;
}