syntax = "proto3";

package ory.keto.relation_tuples.v1alpha2;

option go_package = "github.com/ory/keto/proto/ory/keto/relation_tuples/v1alpha2;rts";
option csharp_namespace = "Ory.Keto.RelationTuples.v1alpha2";
option java_multiple_files = true;
option java_outer_classname = "RelationTuplesProto";
option java_package = "sh.ory.keto.relation_tuples.v1alpha2";
option php_namespace = "Ory\\Keto\\RelationTuples\\v1alpha2";

// RelationTuple defines a relation between an Object and a Subject.
message RelationTuple {
  // The namespace this relation tuple lives in.
  string namespace = 1;
  // The object related by this tuple.
  // It is an object in the namespace of the tuple.
  string object = 2;
  // The relation between an Object and a Subject.
  string relation = 3;
  // The subject related by this tuple.
  // A Subject either represents a concrete subject id or
  // a `SubjectSet` that expands to more Subjects.
  Subject subject = 4;
}

// The query for listing relationships.
// Clients can specify any optional field to
// partially filter for specific relationships.
//
// Example use cases (namespace is always required):
//  - object only: display a list of all permissions referring to a specific object
//  - relation only: get all groups that have members; get all directories that have content
//  - object & relation: display all subjects that have a specific permission relation
//  - subject & relation: display all groups a subject belongs to; display all objects a subject has access to
//  - object & relation & subject: check whether the relation tuple already exists
message RelationQuery {
  // The namespace this relation tuple lives in.
  optional string namespace = 1;
  // The object related by this tuple.
  // It is an object in the namespace of the tuple.
  optional string object = 2;
  // The relation between an Object and a Subject.
  optional string relation = 3;
  // The subject related by this tuple.
  // A Subject either represents a concrete subject id or
  // a `SubjectSet` that expands to more Subjects.
  optional Subject subject = 4;
}

// Subject is either a concrete subject id or
// a `SubjectSet` expanding to more Subjects.
message Subject {
  // The reference of this abstract subject.
  oneof ref {
    // A concrete id of the subject.
    string id = 1;
    // A subject set that expands to more Subjects.
    // More information are available under [concepts](../concepts/15_subjects.mdx).
    SubjectSet set = 2;
  }
}

// SubjectSet refers to all subjects who have
// the same `relation` on an `object`.
message SubjectSet {
  // The namespace of the object and relation
  // referenced in this subject set.
  string namespace = 1;
  // The object related by this subject set.
  string object = 2;
  // The relation between the object and the subjects.
  string relation = 3;
}
