Annotations

Managing and auditing large sets of permissions can be difficult. To address this challenge, we've introduced the ability to add permission annotations to roles.

An annotation is defined by two fields:

• uri - An identifier specifying the subset of permissions to be annotated. A GET request to this URI is expected to return an array of permissions.
• schema - The URL of an OpenAPI v3 schema document describing the API, including the endpoint specified in uri.

Annotations, being an auxiliary concept, are not stored in the Roles contract. Instead, they are posted to the blockchain via Poster (opens in a new tab) to become accessible to the Roles subgraph.

Resolving Annotations

The Roles app resolves annotations by fetching both the permissions to be annotated from uri and the schema document.

If the given role is not granted all of the permissions scoped by the annotation, the annotation will be ignored.

From the schema document, the Roles app extracts the Operation object (opens in a new tab) representing the uri endpoint. This information guides the generic rendering of the annotated permission set in the app.