docs: explain and demonstrate Conditions across the API

openfga/v1/authzmodel.proto

@@ -31,6 +31,9 @@ message AuthorizationModel {
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {example: "[{\"type\": \"user\"}, {\"type\":\"document\",\"relations\":{\"reader\":{\"union\":{\"child\":[{\"this\":{}},{\"computedUserset\":{\"object\":\"\",\"relation\":\"writer\"}}]}},\"writer\":{\"this\":{}}},\"metadata\":{\"relations\":{\"reader\":{\"directly_related_user_types\":[{\"type\":\"user\"}]},\"writer\":{\"directly_related_user_types\":[{\"type\":\"user\"}]}}}}]"}
   ];
 
+  // The set of conditions available to this model, keyed by condition name. A relation's type
+  // restriction can reference a condition by name (e.g. `[user with non_expired_grant]`); the
+  // referenced condition must be defined here. See the `Condition` message for details.
   map<string, Condition> conditions = 4 [
     json_name = "conditions",
     (validate.rules).map.max_pairs = 25,
@@ -199,6 +202,20 @@ message TupleToUserset {
   ];
 }
 
+// A Condition is a named, reusable boolean expression that can be attached to a relationship
+// tuple via `RelationshipCondition` to make the relationship conditional. Conditions are
+// defined once per authorization model (see `AuthorizationModel.conditions`) and referenced by
+// name from a relation's type restriction, e.g. `define viewer: [user with non_expired_grant]`.
+//
+// Example: a condition that only holds while a time-limited grant is still active.
+// ```
+// condition non_expired_grant(current_time: timestamp, grant_time: timestamp, grant_duration: duration) {
+//   current_time < grant_time + grant_duration
+// }
+// ```
+// A tuple referencing this condition supplies `grant_time`/`grant_duration` (typically fixed at
+// write time); `current_time` is then supplied as request `context` when the relationship is
+// evaluated by Check, ListObjects, or ListUsers.
 message Condition {
   // A unique name for the condition
   string name = 1 [
@@ -227,6 +244,8 @@ message Condition {
   ConditionMetadata metadata = 4;
 }
 
+// Metadata about where a Condition was defined, populated when the model was constructed from a
+// modular model (e.g. the module name and the `.fga` source file the condition came from).
 message ConditionMetadata {
   string module = 1 [(validate.rules).string = {
     pattern: "^[^:#@\\s]{1,50}$"
@@ -236,6 +255,9 @@ message ConditionMetadata {
   SourceInfo source_info = 2 [json_name = "source_info"];
 }
 
+// The type of a single named parameter accepted by a `Condition`'s CEL expression (e.g. `int`,
+// `timestamp`, `duration`, `ipaddress`). The corresponding value is supplied via `context` on a
+// `RelationshipCondition` or on a Check/ListObjects/ListUsers request.
 message ConditionParamTypeRef {
   enum TypeName {
     TYPE_NAME_UNSPECIFIED = 0;

openfga/v1/openfga.proto

@@ -85,6 +85,17 @@ message UsersetUser {
   ];
 }
 
+// RelationshipCondition attaches a condition to a relationship tuple, making the
+// relationship it's attached to conditional: the relationship only holds when the named
+// `Condition`'s CEL expression evaluates to true.
+//
+// `context` on this message is optional and is typically used to pin parameter values that are
+// fixed for the lifetime of the tuple (e.g. `grant_time`/`grant_duration` for a time-limited
+// grant), as opposed to parameters that vary per request (e.g. `current_time`), which are instead
+// supplied via the top-level `context` on Check/ListObjects/ListUsers requests.
+//
+// When a relationship is evaluated, this tuple-level `context` is merged with any request-level
+// `context`; if the same key is present in both, the value from this tuple's `context` wins.
 message RelationshipCondition {
   // A reference (by name) of the relationship condition defined in the authorization model.
   string name = 1 [
@@ -102,9 +113,13 @@ message RelationshipCondition {
   // Additional context/data to persist along with the condition.
   // The keys must match the parameters defined by the condition, and the value types must
   // match the parameter type definitions.
-  google.protobuf.Struct context = 2;
+  google.protobuf.Struct context = 2 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {example: "{\"grant_time\": \"2021-10-11T09:00:00Z\", \"grant_duration\": \"1h\"}"}];
 }
 
+// TupleKeyWithoutCondition identifies a relationship tuple by its user/relation/object triplet
+// only, with no `RelationshipCondition`. It's used where a condition would be meaningless or
+// ignored: deleting a tuple (`WriteRequestDeletes.tuple_keys`) only needs the triplet to find the
+// matching row, and any `condition` on the delete request itself is ignored by the Write API.
 message TupleKeyWithoutCondition {
   string user = 1 [
     (google.api.field_behavior) = REQUIRED,
@@ -158,6 +173,11 @@ message TypedWildcard {
   ];
 }
 
+// TupleKey identifies a relationship tuple by its user/relation/object triplet, optionally with a
+// `condition` that makes the relationship it describes conditional. This is the shape used
+// when writing tuples and when specifying `contextual_tuples`; a stored tuple returned by the Read
+// or ReadChanges APIs is wrapped in a `Tuple`, which pairs a `TupleKey` (including its `condition`,
+// if any) with the tuple's write timestamp.
 message TupleKey {
   string user = 1 [
     (google.api.field_behavior) = REQUIRED,
@@ -198,6 +218,9 @@ message TupleKey {
   RelationshipCondition condition = 4;
 }
 
+// Tuple pairs a stored relationship (`TupleKey`, including its `condition` if it was written with
+// one) with the timestamp it was written at. This is the shape returned by the Read API; note that
+// Read returns the tuple's condition verbatim without evaluating it.
 message Tuple {
   TupleKey key = 1 [
     (google.api.field_behavior) = REQUIRED,