An example test that would need to work:

For now, we'll keep the following as reserved:

and
or
from
relations
define

as reserved, but allow

model
schema
type
relation
condition

# dsl-syntax-validation-cases.yaml
- name: a valid model with type names doesn't conflict with built-in keywords
  dsl: |
    model
      schema 1.1
    type user
    type model
      relations
        define model: [user]
        define schema: [user]
        define type: [user]
        define relation: [user]
        define condition: [user] or model or schema or type or relation
    type schema
      relations
        define model: [user]
        define schema: [user]
        define type: [user]
        define relation: [user]
        define condition: [user] or model or schema or type or relation
    type type
      relations
        define model: [user]
        define schema: [user]
        define type: [user]
        define relation: [user]
        define condition: [user] or model or schema or type or relation
    type relation
      relations
        define model: [user]
        define schema: [user]
        define type: [user]
        define relation: [user]
        define condition: [user] or model or schema or type or relation
    type condition
      relations
        define model: [user]
        define schema: [user]
        define type: [user]
        define relation: [user]
        define condition: [user] or model or schema or type or relation

Example

model
  schema 1.1
type group
  relations
    define customer: [customer]

Exception generated here

The following are the known issues for the current WIP support for conditions in language:

Validation in JS

(Note language does not yet do validations in Go)

• Condition CEL Expression is not validated
• Condition Parameters are not validated to be used and usable in the expression
• Condition CEL Expression is not validated to be not using undefined parameters

Parsing

• Some valid CEL expressions are not parsed properly
• } cannot occur in the expression
• Relation, parameter or type names that conflict with parameter type keywords (map, list, string, etc..) are parsed incorrectly

The frontend-utils package currently imports all errors via the dist folder. We don't really want that as we shouldn't encourage importing through dist.

Instead make this exported fully and also ensure that the types are fully up to date (e.g. typeName and relation here)

model
  schema 1.1
type user
type org
  relations
    define owner: [user]
    define member: [user]
    define can_add_member: owner
type team
  relations
    define parent: [org]
    define member: [user]
    define can_add_member: can_add_member from parent
type group
  relations
    define parent: [team]
    define org: parent from parent
    define member: [user]
    define can_add_member: can_add_member from org

The language server shows an unhelpful ModelValidationError:

`can_add_member` is an impossible relation for `group` (no entrypoint).

The actual error should inform the user the because group -> org has a rewrite (in this case tuple to userset, but computed usersets or a type restriction with a userset should also fail), it cannot be used as the source of a from (cannot be used as a tupleset).

The actual error message should be discussed.

The API shows a much more helpful message in similar situations:

the 'group#org' relation is referenced in at least one tupleset and thus must be a direct relation

On the CLI, we want to allow an output such as:

# Model ID: 01H6BP03XGV3CMJ9VZQBG4NS1C
# Created At: 2023-07-27 12:43:22 +0000 UTC
model
  schema 1.1

type report
  relations
    define approver: can_manage from submitter
    define submitter: [employee]

type employee
  relations
    define can_manage: manager or can_manage from manager
    define manager: [employee]

Right now passing it back to the transformer fails because the grammar does not allow comments to come first

We currently have bindings to support JS and Golang, with the following features supported in each.

In order to progress in our support for a Jetbrains Plugin, we will need to add Java bindings that handle the same features.

The Java bindings should run against the same set of checks as the other implementations (JS tests, Test Definitions)

The exposed methods should match the ones for JS and Go

• transformer
  • transformJSONToDSL
  • transformDSLToJSON
• validator
  • validateDSL
  • validateJSON

Example:

model
  schema 1.1
type user
type group
  relations
    define member: [user]
type folder
  relations
    define parent: [folder]
    define viewer: [user,user:*,group#member] or viewer from parent
type document
  relations
# documents live within folders
    define parent: [folder]
    define viewer: [    user,user:*,group#member] or viewer from parent

Need to provide accurate line and char location for exception.

@ewanharris has already started some of that work here

We already have validation for JS, we need to add the Go implementation of it, so that language can take over validation in the API

#184 is a priority to be in before this work, because our validation needs to cover at least the cases the API currently covers

This will allow us (and the community) to more easily generate parsers in other languages

We would like to provide a test suite that both us and community parsers can use to validate their parsers.

A proposed solution would look like:

/tests/data/
- v1.0/
  - parser/
    - {case name}.model.json
    - {case name}.model.openfga
  - checker/
    - dsl/ 
      - {case name}.results.json
      - {case name}.model.openfga
    - json/ 
      - {case name}.results.json
      - {case name}.model.json
  - formatter/
    - {case name}.input.json
    - {case name}.output.openfga
- v1.1/
  - parser/
  - checker/
  - formatter/

See Related Discussion

There is a circular dependency between

As a result, using the syntax transformer will result in

OpenFGAParserListener.js:9 Uncaught TypeError: Class extends value undefined is not a constructor or null
    at ./node_modules/@openfga/syntax-transformer/dist/gen/OpenFGAParserListener.js (OpenFGAParserListener.js:9:1)
    at options.factory (react refresh:6:1)
    at __webpack_require__ (bootstrap:24:1)
    at fn (hot module replacement:62:1)
    at ./node_modules/@openfga/syntax-transformer/dist/transformer/dsltojson.js (dsltojson.js:30:1)
    at options.factory (react refresh:6:1)
    at __webpack_require__ (bootstrap:24:1)
    at fn (hot module replacement:62:1)
    at ./node_modules/@openfga/syntax-transformer/dist/transformer/index.js (index.js:17:1)
    at options.factory (react refresh:6:1)

See: openfga/openfga#1164

The below model is invalid because the intersection definition in the document#viewer relation is malformed. It’s missing a child: […] nested block.

{
  "schema_version": "1.1",
  "type_definitions": [
    {
        "type": "user"
    },
    {
        "type": "folder",
        "relations": {
            "viewer": {"this": {}},
            "parent": {"this": {}}
        },
        "metadata": {
            "relations": {
                "viewer": {
                    "directly_related_user_types": [{"type": "user"}]
                },
                "parent": {
                    "directly_related_user_types": [{"type": "folder"}]
                }
            }
        }
    },
    {
        "type": "document",
        "relations": {
            "parent": {"this": {}},
            "viewer": {
                "union": {
                    "child": [
                        {
                            "intersection": {
                                "tupleToUserset": {
                                    "tupleset": {
                                        "relation": "parent"
                                    },
                                    "computedUserset": {
                                        "relation": "viewer"
                                    }
                                }
                            }
                        },
                        {"this": {}}
                    ]
                }
            }
        },
        "metadata": {
            "relations": {
                "parent": {
                    "directly_related_user_types": [{"type": "folder", "relation": "parent"}]
                },
                "viewer": {
                    "directly_related_user_types": [{"type": "user"}]
                }
            }
        }
    }
  ]
}

When time allows, we can build off the following PR and improve the tokenization of the lexer and parser.

#22

Core problem stopping this is the character chosen to trigger a comment - it is very difficult to match with best practices in ANTLR4.
https://github.com/antlr/grammars-v4/blob/3ecefc5f8ed0a38ff4b68705bcfd521bcd59f8d3/python/python2-js/Python2.g4#L454

One error I'm encountering;

If I make an error here like in the attached screenshot (removing a closing bracket on the last line), it reports an invalid range. I get the following error contents;

{
  severity: 8,
  startColumn: 0,
  endColumn: 0,
  startLineNumber: 21,
  endLineNumber: 21,
  message: "Invalid syntax",
  source: "linter",
}

Right line, but 0s on the start & end cols.

For example, the below currently cannot be represented in JSON

{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user",
      "relations": {}
    },
    {
      "type": "folder",
      "relations": {
        "admin": {
          "this": {}
        },
        "viewer": {
          "this": {}
        },
        "blocked": {
          "this": {}
        },
        "can_view": {
          "union": {
            "child": [
              {
                "computedUserset": {
                  "object": "",
                  "relation": "admin"
                }
              },
              {
                "difference": {
                  "base": {
                    "computedUserset": {
                      "object": "",
                      "relation": "viewer"
                    }
                  },
                  "subtract": {
                    "computedUserset": {
                      "object": "",
                      "relation": "blocked"
                    }
                  }
                }
              }
            ]
          }
        }
      },
      "metadata": {
        "relations": {
          "admin": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "viewer": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "blocked": {
            "directly_related_user_types": [
              {
                "type": "user"
              }
            ]
          },
          "can_view": {
            "directly_related_user_types": []
          }
        }
      }
    }
  ]
}

and the language transforms it to:

model
  schema 1.1

type user

type folder
  relations
    define admin: [user]
    define blocked: [user]
    define can_view: admin or
    define viewer: [user]

Summary

I used docker compose to spin a container for openfga. In the playground, I copied the example found at https://openfga.dev/docs/modeling/user-groups.

The playground give me this error :

By debugging, at discovered that the real error is:

TypeError: Cannot read properties of undefined (reading 'member')
    at b (_app-3f8777cf4f50374e.js:1:559716)
    at _app-3f8777cf4f50374e.js:1:566200
    at Array.forEach (<anonymous>)
    at _app-3f8777cf4f50374e.js:1:566115
    at O (_app-3f8777cf4f50374e.js:1:566418)
    at t.validateDSL (_app-3f8777cf4f50374e.js:1:566784)
    at t.validateDSL (_app-3f8777cf4f50374e.js:1:407940)
    at onChange (_app-3f8777cf4f50374e.js:1:867140)
    at 727.3d4089e0c45544c8.js:1:3895891
    at e.value (727.3d4089e0c45544c8.js:1:943659)

Did I do something wrong when I paste the Authorization Model copied from you documentation ?

Store data

model_file: |
model
  schema 1.1
type user
type document
  relations
    define editor: [team#member]
type team
  relations
    define member: [user]

Other data

Docker compose file : https://openfga.dev/docker-compose.yaml

Trailing whitespaces after relations currently cause:

See: https://github.com/openfga/openfga/blob/main/pkg/typesystem/typesystem_test.go

Depends on #99

Schema could alternatively be a number.

Also realized since this is just JSON, i have no range to use for marking which contents in fga.mod when generating errors. The structure is missing line and character values, such that i'd also need to parse the YAML as well to get line numbers.

The following model will fail to parse in fga model test --tests testfile.yaml

model.fga:

# I can't believe it's not yaml
model
  schema 1.1

type user

testfile.yaml:

model_file: ./model.fga

Error:

Error: error running tests due to failed to transform due to 2 errors occurred:
	* syntax error at line=1, column=7: token recognition error at: '''
	* syntax error at line=1, column=20: token recognition error at: '''

If you remove the comment on model.fga, the test passes.

Schema version currently hardcoded as 1.1 - allow for version bumps in lexer, but validate version number during model validation.

For example, for the modular model specified here, this will be the combined DSL:

model
  schema 1.2

## module = core; filename = ./core.fga
type user

type organization
  relations
    define member: [user]
    define admin: [user]
    ## extended by: module = confluence; filename = ./confluence.fga
    define can_create_page: member
    ## extended by: module = jira; filename = ./jira/projects.fga
    define can_create_project: member

type group
  relations
    define member: [user]

## module = confluence; filename = ./confluence.fga
type space
  relations
    define organization: [organization] 

type page
  relations
    define space: [space]
    define owner: [user]

## module = jira; filename = ./jira/projects.fga
type project
  relations
    define organization: [organization]

## module = jira; filename = ./jira/tickets.fga
type ticket
  relations
    define project: [project]
    define owner: [user]

Note that ideally the extended relations will be sorted last and by module/filename

We had split supporting the following JSON from #16 to reduce scope as this still needed discussion.

As a suggestion, consider the following three cases:

I-

"relation": {
  "union": {
    "child": [
      {
        "computedUserset": {
          "relation": "rel3"
        }
      },
      {
        "difference": {
          "base": {
            "intersection": {
              "child": [
                {
                  "computedUserset": {
                    "relation": "rel1"
                  }
                },
                {
                  "computedUserset": {
                    "relation": "rel2"
                  }
                }
              ]
            }
          },
          "subtract": {
            "this": {}
          }
        }
      }
    ]
  }
}

II-

"relation": {
  "union": {
    "child": [
      {
        "intersection": {
          "child": [
            {
              "this": {}
            },
            {
              "computedUserset": {
                "relation": "allowed"
              }
            }
          ]
        }
      },
      {
        "difference": {
          "base": {
            "this": {}
          },
          "subtract": {
            "computedUserset": {
              "relation": "blocked"
            }
          }
        }
      }
    ]
  }
}

III-

"relation": {
  "difference": {
    "computedUserset": {
      "relation": "rel1"
    },
    "subtract": {
      "this": {}
    }
  }
}

Note: We should consider rejecting this case (define relation: rel1 but not [user]) as it is nonsensical

Some potential solutions:
A. Allow restating the full type restrictions:
e.g.

• define relation: rel3 or ((rel1 and rel2) but not [user])
• define relation: ([user] and allowed) or ([user] but not blocked)
• define relation: rel1 but not [user]

B. Allow using self
e.g.

• define relation: [user] | rel3 or ((rel1 and rel2) but not self)
• define relation: [user] | (self and allowed) or (self but not blocked)
• define relation: [user] | rel1 but not self

C. Allow using self but require defining it for clarity (we can also have the define as optional)
e.g.

• define relation: [user] as self | rel3 or ((rel1 and rel2) but not self)
• define relation: [user] as self | (self and allowed) or (self but not blocked)
• define relation: [user] as self | rel1 but not self

D. Allow defining an using an arbitrary name in lieu of self (needs an extension to the json to support it)
e.g.

• define relation: [user] as some_name | rel3 or ((rel1 and rel2) but not some_name)
• define relation: [user] as some_name | (some_name and allowed) or (some_name but not blocked)
• define relation: [user] as some_name | rel1 but not some_name

Other questions to consider, does | as a separator make sense?

For other ideas, please post in the comments

Ref: Follow-up on #16

In the below case, Language should not treat it as unsupported by DSL, and should allow it

- name: relation def where this is not in first place
  json: >-2
    {
      "schema_version": "1.1",
      "type_definitions": [
        {
          "type": "user",
          "relations": {
            "rel1": {
              "this": {}
            },
            "rel2": {
              "union": {
                "child": [
                  {
                    "computedUserset": {
                      "relation": "rel1"
                    }
                  },
                  {
                    "this": {}
                  }
                ]
              }
            }
          },
          "metadata": {
            "relations": {
              "rel1": {
                "directly_related_user_types": [
                  {
                    "type": "user"
                  }
                ]
              },
              "rel2": {
                "directly_related_user_types": [
                  {
                    "type": "user"
                  }
                ]
              }
            }
          }
        }
      ]
    }
  valid: true

The DSL today does not support nested userset rewrite operands and/or compound expressions delineated by parenthetical expressions. The DSL language should be extended to support compound expressions with parenthetical expressions so that it supports the same expressiveness of the JSON support existing today.

Below are some examples of the unsupported functionality.

# sample1
type document
  relations
    define restricted as self
    define editor as self
    define viewer as editor or (self but not restricted)

# sample2
type document
  relations
    define restricted as self
    define parent as self
    define editor as self
    define (viewer but not restricted) or (editor and viewer from parent)

These same models are supported in the JSON structure today, for example:

# sample 1
{
  "type_definitions": [
    {
      "type": "document",
      "relations": {
        "restricted": { "this": {} },
        "editor": { "this": {} },
        "viewer": {
          "union": {
            "child": [
              { "computedUserset": { "object": "", "relation": "editor" } },
              {
                "union": {
                    "child": [
                        { "this": {} },
                        {
                            "difference": {
                                "base": {
                                    "this": {} 
                                },
                                "subtract": {
                                    "object": "",
                                    "relation": "restricted"
                                }
                            }
                        }
                    ]
                }
              }
            ]
          }
        }
      }
    }
  ]
}

# sample2
{
  "type_definitions": [
    {
      "type": "document",
      "relations": {
        "parent": { "this": {} },
        "restricted": { "this": {} },
        "editor": { "this": {} },
        "viewer": {
          "union": {
            "child": [
              {
                "difference": {
                    "base": {
                        "this": {} 
                    },
                    "subtract": {
                        "object": "",
                        "relation": "restricted"
                    }
                }
              },
              {
                "intersection": {
                    "child": [
                        {
                            "computedUserset": {
                                "object": "",
                                "relation": "editor"
                            }
                        },
                        {
                            "tupleToUserset": {
                                "tupleset": {
                                    "object": "",
                                    "relation": "parent"
                                },
                                "computedUserset": {
                                    "object": "",
                                    "relation": "viewer"
                                }
                            }
                        }
                    ]
                }
              }
            ]
          }
        }
      }
    }
  ]
}

See openfga/frontend-utils#95 (comment) , we want to revisit whether $ should be only allowed on relations, not types in the DSL.

When we run the fully combined model through validateJSON currently the errors have no metadata associated with them that would allow us to (or at least easily) look up the line and column information associated with the error.

When we raise a validation error we should include the new file and module metadata fields so that we can improve the error reporting for these errors. Then in the catch for validateJSON we can lookup the file contents and get line/column data to improve these errors.

Right now ANTLR does soft fails (it prints the errors to STDERR, but still attempts to parse)

In the below invalid example (and and or and but not cannot be mixed)

model
  schema 1.1

type user
  relations
    define can_view: user or follower and allowed
    define user: [user]
    define follower: [user]
    define allowed: [user]

The generated parse tree is:

Nothing after or follower is processed, but no error is being reported

Causes: openfga/cli#133

Related to #16

Currently the Go bindings do not properly support mixed operators. Work has happened in #107 to add the bindings to JS

The following will result in incorrect JSON

Tests for these cases are already in place and the Go implementation fails on them

 define relation: (rel1 and rel2) but not rel3
 define relation: ((rel1 and rel2) but not rel3) # transformation back to DSL will not keep the extraneous surrounding brackets
 define relation: rel1 and (rel2 but not rel3)
 define relation: rel1 and ((rel2 but not rel3) or (rel4 and (rel5 but not rel6 from rel7)))
 define relation: [user, user:*, user#follower with condition] or ((rel1 and rel2) but not rel3)
 define relation: ([user] or ((rel1 and rel2)) but not rel3 

Intro

Roadmap Item: openfga/roadmap#39
Modular Models RFC

Sub-tickets

• #149
• #150
• #151
• #152
• #153
• #154
• #180
• #186
• #187
• #199

For this epic, we're going to have a long running feature branch feat/148-support-modular-models that will have all our changes to support this feature

Related tickets

• openfga/api#137 (blocker)
• openfga/vscode-ext#165
• openfga/cli#262
• openfga/openfga#1402