Concepts

Schema

A combination of one or more Namespaces. This is used to define a permission model of a system. Here's an example of part of a schema:

name: Files
namespaces:
  - name: org
    relationDefinitions:
      - name: parent
      - name: member
        complexDefinition:
          nType: union
          children:
            - nType: child
              expression:
                neType: self
            - nType: child
              expression:
                neType: relationLeft
                relationDefinition: parent
                relationDefinitionNamespace: org
                targetRelationDefinition: member
                targetRelationDefinitionNamespace: org
  - name: folder
    relationDefinitions:
      - name: parent
      - name: owner
        complexDefinition:
          nType: union
          children:
            - nType: child
              expression:
                neType: self
            - nType: child
              expression:
                neType: relationRight
                relationDefinition: parent
                relationDefinitionNamespace: folder
                targetRelationDefinition: owner
                targetRelationDefinitionNamespace: folder

The schema, together with Relations, allows determination of whether a relationship exists between a user and a resource. The schema can be loaded from a JSON/YAML file or programmatically implemented.

Namespaces

Defines a class of objects with similar characteristics and holds Relation Definitions. Examples include:

• Document
• Folder
• User
• Organization

Relation Definition

Defines all the possible relations a user or other object can have to a Namespace. An example looks like:

- name: doc
  relationDefinitions:
    - name: parent
    - name: owner
      complexDefinition:
        nType: union
        children:
          - nType: child
            expression:
              neType: self
          - nType: child
            expression:
              neType: relationRight
              relationDefinition: parent
              relationDefinitionNamespace: doc
              targetRelationDefinition: owner
              targetRelationDefinitionNamespace: folder

Resource

Represents an entity in the system. It is simply an identifier, not necessarily tied to a Namespace:

• fb83c013-3060-41f4-9590-d3233a67938f
• descope/java-sdk
• org_ajUc9kJ
• new-roadmap

Targets, Relation Definitions, and Resources are the building blocks for Relations.

Target or Target Set

A Target is a unique identifier, not necessarily tied to a Namespace. A Target Set is a group or set of users/entities related by a unique identifier, a Namespace, and a Relation Definition.

Like a Resource, a Target looks as follows:

• any identifier: e.g. lisa or 4179af14-f0c0-135-88fd-5570c7bf6f59
• any object: e.g. fb83c013-3060-41f4-9590-d3233a67938f, descope/java-sdk or ajUc9kJ

The Target Set:

• a group or a set of users (also called a userset): e.g. organization:org_ajUc9kJ#members, which represents the set of users related to the object organization:org_ajUc9kJ as member

Relation

An tuple consisting of a Target or Target Set, Relation Definition, and Resource stored in Descope&aposs FGA service.

A Relation consists of a:

• Target or Target Set, e.g. anne, 3f7768e0-4fa7-4e93-8417-4da68ce1846c, descope or folder:planning#editor
• Relation Definition, e.g. editor, member or parent_workspace
• Resource, e.g repo:descope/java_sdk, domain:descope.com or channel:marketing

An authorization Schema together with Relations, allow the determination of whether a relationship exists between a Target and a Resource.

Throughout the documentation, you will encounter Relations represented as:

Relation("Internal", "viewer", "folder", null, "Descope", "member", "org", null)

Direct and Implied Relations

A direct relationship between user X and object Y means the Relation (target=X, relation definition=R, resource=Y) exists, and the Descope FGA authorization model for that relation allows this direct relationship.

An implied (or computed) relationship exists between target X and resource Y if target X is related to a resource Z that is in a direct or implied relationship with resource Y, and the Descope FGA authorization model allows it.

Complex Relation Definition Types

Self

Defines a direct relation between the namespace and relation definition.

Relation Left

Defines a relation between a Target and the Resource that the node is being added to. Direction of tree traversal for permissions is from Resource to Target (eg. user is member of org which is ).

Relation Right

Defines a relation between a Target and the Resource that the node is being added to. Direction of tree traversal for permissions is from Target to Resource (eg. owner is parent of parent folder).

Target Set

Defines a relation saying the Resource has the relation you are defining if it is also a target.