@openfga/syntax-transformer

OpenFGA Syntax Transformer

The OpenFGA API accepts a JSON syntax for the configuration of the authorization model. The OpenFGA docs showcase an alternate friendlier syntax that can be used to build an OpenFGA authorization model.

This module transforms between the JSON syntax accepted by the OpenFGA API and the friendlier syntax you see throughout the documentation.

Table of Contents

• About OpenFGA
• Resources
• Installation
• Usage
  • From the Friendly Syntax to the JSON Syntax
  • From the JSON Syntax to the Friendly Syntax
• CLI
• Configuration Syntaxes
  • Schema v1.1
  • Schema v1.0
• Contributing
• Community Parsers
• Author
• License

About OpenFGA

OpenFGA is an open source Fine-Grained Authorization solution inspired by Google's Zanzibar paper. It was created by the FGA team at Auth0 based on Auth0 Fine-Grained Authorization (FGA), available under a permissive license (Apache-2) and welcomes community contributions.

OpenFGA is designed to make it easy for application builders to model their permission layer, and to add and integrate fine-grained authorization into their applications. OpenFGA’s design is optimized for reliability and low latency at a high scale.

It allows in-memory data storage for quick development, as well as pluggable database modules - with initial support for PostgreSQL.

It offers an HTTP API and a gRPC API. It has SDKs for Node.js/JavaScript, GoLang, Python and .NET. Look in our Community section for third-party SDKs and tools.

More SDKs and integrations such as Rego are planned for the future.

Resources

• OpenFGA Documentation
• OpenFGA API Documentation
• Twitter
• OpenFGA Discord Community
• Zanzibar Academy
• Google's Zanzibar Paper (2019)

Installation

npm install --save @openfga/syntax-transformer // OR yarn add @openfga/syntax-transformer

Usage

The syntax transformer has grown to encompass a lot more functionality than previously intended, mostly components used by the FGA Playground. Please note that all functionality except: friendlySyntaxToApiSyntax and apiSyntaxToFriendlySyntax is undocumented and should be considered tentative and may be removed at any moment. If you depend on them, please reach out so that we can discuss out future plans for that functionality and make sure our plans are taking your use-case into consideration.

From the Friendly Syntax to the JSON Syntax

const { friendlySyntaxToApiSyntax } = require("@openfga/syntax-transformer");

const apiSyntax = friendlySyntaxToApiSyntax(
`model
  schema 1.1
type user
type document
  relations
    define blocked: [user]
    define editor: [user] but not blocked
`);

From the JSON Syntax to the Friendly Syntax

const { apiSyntaxToFriendlySyntax } = require("@openfga/syntax-transformer");

const friendlySyntax = apiSyntaxToFriendlySyntax({
  "schema_version": "1.1",
  "type_definitions": [{
    "type": "user",
    "relations": {}
  }, {
    "type": "document",
    "relations": {
      "blocked": { "this": {} },
      "editor": {
        "difference": {
          "base": { "this": {} },
          "subtract": {
            "computedUserset": {
              "object": "",
              "relation": "blocked"
            }
          }
        }
      }
    },
    "metadata": {
      "relations": {
        "blocked": {
          "directly_related_user_types": [{ "type": "user" }]
        },
        "editor": {
          "directly_related_user_types": [{ "type": "user" }]
        }
      }
    }
  }]
}
);

CLI

This transformer comes with a basic CLI that can be used to transform between the Friendly and API JSON syntaxes

Transform from OpenFGA API's JSON syntax to the friendly OpenFGA DSL

 npx @openfga/syntax-transformer transform --from=json --inputFile=test.json

Transform from OpenFGA's friendly DSL to the OpenFGA API's JSON syntax

npx @openfga/syntax-transformer transform --from=dsl --inputFile=test.openfga

Configuration Syntaxes

Schema 1.1

The two below Syntaxes are equivalent. Find out more on OpenFGA's configuration language here.

Friendly Syntax (DSL)

model
  schema 1.1
type user
type folder
  relations
    define editor: [user]
type document
  relations
    define parent: [folder]
    define editor: [user] or editor from parent

JSON Syntax

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

Schema 1.0

The two below Syntaxes are equivalent. Find out more on OpenFGA's configuration language here.

Friendly Syntax (DSL)

type user
type folder
  relations
    define editor as self
type document
  relations
    define parent as self
    define editor as self or editor from parent

JSON Syntax

{
  "schema_version": "1.0",
  "type_definitions": [{
    "type": "user",
    "relations": {}
  }, {
    "type": "folder",
    "relations": {
      "editor": { "this": {} }
    }
  }, {
    "type": "document",
    "relations": {
      "parent": { "this": {} },
      "editor": {
        "union": {
          "child": [{
            "this": {}
          }, {
            "tupleToUserset": {
              "tupleset": {
                "object": "",
                "relation": "parent"
              },
              "computedUserset": {
                "object": "",
                "relation": "editor"
              }
            }
          }]
        }
      }
    }
  }]
}

Community Parsers

Repo	License	Maintainers	Language	Schema v1.0	Schema v1.1	Package Managers	Other Links
syntax-transformer	Apache-2.0	@openfga	Typescript	Yes	Yes
openfga-dsl-parser	Apache-2.0	@maxmindlin - @dblclik	Rust	Yes	No		WASM - Python
openfga-rs	Apache-2.0	@iammathew	Rust	Yes	No
openfga-dsl-parser	Apache-2.0	@craigpastro	ANTLR & Go	Yes	Partial (requires self). Supports nesting

Community Wrapper

Repo	License	Maintainers	Language	Schema v1.0	Schema v1.1	Package Managers	Other Links
fga-transformer-cli	MIT	@ozee-io	Javascript	Yes	Yes

Contributing

Take a look at our Contributing Guide

Author

OpenFGA team

License

Apache-2.0