Configuration Language

OpenFGA's Configuration Language builds a representation of a system's authorization model, which informs OpenFGA's API on the object types in the system and how they relate to each other. The Configuration Language describes the relations possible for an object of a given type and lists the conditions under which one is related to that object.

The Configuration Language can be presented in DSL or JSON syntax. The JSON syntax is accepted by the API and closely tracks the language in the Zanzibar paper. The DSL adds syntactic sugar on top of JSON for ease of use, but compiles down to JSON before being sent to OpenFGA's API. JSON syntax is used to call API directly or through the SDKs, while DSL is used to interact with OpenFGA in the Playground, the CLI, and the IDE extensions for Visual Studio Code and IntelliJ. They can be switched between throughout this documentation.

Please familiarize yourself with basic OpenFGA Concepts and How to get started on modeling before starting this guide.

What Does The Configuration Language Look Like?

Below is a sample authorization model. The next sections discuss the basics of the OpenFGA configuration language.

DSL

model
  schema 1.1

type user

type domain
  relations
    define member: [user]

type folder
  relations
    define can_share: writer
    define owner: [user, domain#member] or owner from parent_folder
    define parent_folder: [folder]
    define viewer: [user, domain#member] or writer or viewer from parent_folder
    define writer: [user, domain#member] or owner or writer from parent_folder

type document
  relations
    define can_share: writer
    define owner: [user, domain#member] or owner from parent_folder
    define parent_folder: [folder]
    define viewer: [user, domain#member] or writer or viewer from parent_folder
    define writer: [user, domain#member] or owner or writer from parent_folder

JSON

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "domain",
      "relations": {
        "member": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "member": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          }
        }
      }
    },
    {
      "type": "folder",
      "relations": {
        "can_share": {
          "computedUserset": {
            "object": "",
            "relation": "writer"
          }
        },
        "owner": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "tupleToUserset": {
                  "tupleset": {
                    "object": "",
                    "relation": "parent_folder"
                  },
                  "computedUserset": {
                    "object": "",
                    "relation": "owner"
                  }
                }
              }
            ]
          }
        },
        "parent_folder": {
          "this": {}
        },
        "viewer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "object": "",
                  "relation": "writer"
                }
              },
              {
                "tupleToUserset": {
                  "tupleset": {
                    "object": "",
                    "relation": "parent_folder"
                  },
                  "computedUserset": {
                    "object": "",
                    "relation": "viewer"
                  }
                }
              }
            ]
          }
        },
        "writer": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "computedUserset": {
                  "object": "",
                  "relation": "owner"
                }
              },
              {
                "tupleToUserset": {
                  "tupleset": {
                    "object": "",
                    "relation": "parent_folder"
                  },
                  "computedUserset": {
                    "object": "",
                    "relation": "writer"
                  }
                }
              }
            ]
          }
        }
      },
      "metadata": {
        "relations": {
          "owner": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          },
          "parent_folder": {
            "directly_related_user_types": [
              {
                "type": "folder"
              }
            ]
          },
          "viewer": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          },
          "writer": {
            "directly_related_user_types": [
              {
                "type": "user"
              },
              {
                "type": "domain",
                "relation": "member"
              }
            ]
          }
        }
      }
    },
    {
      "type": "document",
      "relations": {
        "can_share": {
          "computedUserset": {
            "object": "",
            "relation": "writer"
          }
        },
        "owner": {
          "union": {
            "child": [
              {
                "this": {}
              },
              {
                "tupleToUserset": {
                  "tupleset": {
                    "object": "",
                    "relation": "parent_folder"
                  },
                  "computedUserset": {
                    "object": "",
                    "relation": "owner"