Skip to content

Latest commit

 

History

History
240 lines (212 loc) · 7.78 KB

0048-schema-annotations.md

File metadata and controls

240 lines (212 loc) · 7.78 KB

Annotations for Cedar Schemas

Related issues and PRs

Timeline

  • Started: 2024-02-05

Note: These statuses are based on the first version of the RFC process.

Summary

Like Cedar policies, users may want to associate arbitrary, machine readable metadata with Schema objects. We solved this problem in Cedar policies by allowing for annotations: arbitrary key/value pairs that are attachable to policies. This could be extended to Cedar schemas, allowing users to attach attributes an entity type/common type/action declaration and attribute declaration.

Basic example

Here is a basic example for doc comments.

@doc("this is the namespace")
namespace TinyTodo {
    @doc("a common type representing a task")
    type Task = {
        @doc("task id")
        "id": Long,
        "name": String,
        "state": String,
    };
    @doc("a common type representing a set of tasks")
    type Tasks = Set<Task>;

    @doc("an entity type representing a list")
    @docComment("any entity type is a child of type `Application`")
    entity List in [Application] = {
        @doc("editors of a list")
        "editors": Team,
        "name": String,
        "owner": User,
        @doc("readers of a list")
        "readers": Team,
        "tasks": Tasks,
    };

    @doc("actions that a user can operate on a list")
    action DeleteList, GetList, UpdateList appliesTo {
        principal: [User],
        resource: [List]
    };
}

The @id("...") notation is similar to the notation used for policy annotations.

Motivation

Users should be allowed to associate machine readable metadata with objects in a Schema. While we could create special syntax for associating particular kinds of metadata, we cannot predict all of the metadata uses that users will have. Thus providing a flexible system that users can adapt to their needs is preferable. This proposal re-uses the same syntax from Cedar Policies, creating a unified syntax.

Detailed design

Semantics

Attributes have no impact on validation decisions. Attributes are arbitrary key/value pairs where:

  • 'key' is a valid Cedar identifier
  • 'value' is a Cedar string

The Cedar spec takes no opinion or stance on the interpretation of annotations. The interpretation is entirely up to users of Cedar.

Cedar Schema Syntax

Attributes in Cedar Schemas will mirror the syntax used for attributes in a policy: informally that's @<key>("value"). Formally the following rule is added to the Cedar grammar:

Annotation := '@' IDENT '(' STR ')'
Annotations := {Annotations}

With an arbitrary number of them being able to prepend to a namespace declaration, entity type declaration, common type declaration, action declaration, and an attribute declaration.

Thus the full schema syntax becomes:

Schema      := {Namespace}
Namespace   := (Annotations 'namespace' Path '{' {Decl} '}') | {Decl}
Decl        := Entity | Action | TypeDecl
Entity      := Annotations 'entity' Idents ['in' EntOrTyps] [['='] RecType] ';'
Action      := Annotations 'action' Names ['in' (Name | '[' [Names] ']')] [AppliesTo] [ActAttrs]';'
TypeDecl    := Annotations 'type' IDENT '=' Type ';'
Type        := PRIMTYPE | IDENT | SetType | RecType
EntType     := Path
SetType     := 'Set' '<' Type '>'
RecType     := '{' [AttrDecls] '}'
AttrDecls   := Annotations Name ['?'] ':' Type [',' | ',' AttrDecls]
AppliesTo   := 'appliesTo' '{' AppDecls '}'
ActAttrs    := 'attributes' '{' AttrDecls '}'
AppDecls    := ('principal' | 'resource') ':' EntOrTyps [',' | ',' AppDecls]
             | 'context' ':' RecType [',' | ',' AppDecls]
Path        := IDENT {'::' IDENT}
EntTypes    := Path {',' Path}
EntOrTyps   := EntType | '[' [EntTypes] ']'
Name        := IDENT | STR
Names       := Name {',' Name}
Idents      := IDENT {',' IDENT}
Annotation  := '@' IDENT '(' STR ')
Annotations := Annotation {Annotations}

IDENT       := ['_''a'-'z''A'-'Z']['_''a'-'z''A'-'Z''0'-'9']* - PRIMTYPE
STR         := Fully-escaped Unicode surrounded by '"'s
PRIMTYPE    := 'Long' | 'String' | 'Bool'
WHITESPC    := Unicode whitespace
COMMENT     := '//' ~NEWLINE* NEWLINE

JSON Syntax

None of the three top-level constructs (EntityTypes, Actions, CommonTypes) in JSON schemas allow for arbitrary key/value pairs. This means a new key can be safely added while preserving backwards compatibility. The same fact also applies to entity attribute declarations. This proposal reserves the annotations key at the top level of each of those constructs, which contains an Object, containing each annotation key as an Object key, associated with the annotation string. The only oddness here is Common Types, whose toplevel is a regular type. While this should still be backwards compatible, it will look a little odd to have annotations in some types and not in others.

A corresponding JSON schema for the above example is as follows.

{
    "": {
    "annotations": {
        "doc": "this is the namespace"
    },
    "commonTypes": {
        "Task": {
        "annotations": {
            "doc": "a common type representing a task"
        },
        "type": "Record",
        "attributes": {
            "id": {
            "type": "Long",
            "annotations": {
                "doc": "task id"
            },
            },
            "name": {
            "type": "String"
            },
            "state": {
            "type": "String"
            }
        }
        },
        "Tasks": {
        "type": "Set",
        "element": {
            "type": "Task"
        }
        }
    },
    "entityTypes": {
        "Application": {},
        "List": {
        "annotations": {
            "doc": "an entity type representing a list",
            "docComment": "any entity type is a child of type `Application`"
        },
        "memberOfTypes": [
            "Application"
        ],
        "shape": {
            "type": "Record",
            "attributes": {
            "editors": {
                "type": "Team"
            },
            "name": {
                "type": "String"
            },
            "owner": {
                "type": "User"
            },
            "readers": {
                "type": "Team"
            },
            "tasks": {
                "type": "Tasks"
            }
            }
        }
        }
    },
    "actions": {
        "CreateList": {
         "annotations": {
            "doc": "actions that a user can operate on a list"
        },
        "appliesTo": {
            "resourceTypes": [
            "Application"
            ],
            "principalTypes": [
            "User"
            ]
        }
       }
    }
  }
}

Drawbacks

  1. Complexity: adds more complexity to schema
  2. Oddness around syntax for Common Types in JSON form
  3. By not taking a stance on annotation meanings, it makes it harder for a standard to form around them (ex: for doc strings)
  4. Multi-line docstrings are technically valid but awkward.

Alternatives

Take a stance

Reverse our decision around annotations and start taking stances on what annotations mean. This lets us standardize certain annotations, like doc. This probably can't happen unless we also do this for policies, which we've said we don't want to do.

Doc Strings as comments

Instead of annotations, we could add "doc-strings" as a first class feature. Could look like this:

/# Stop users from accessing a high security document unless:
/#  A) The principal and user are at the same location
/#  B) The principal has a job level greater than  4
forbid(principal, action, resource) when {
    resource.security_level == "HIGH"
unless {
    (resource.location == principal.location) || (principal.job_level > 4 )
};

This has nice and easy multi-line syntax, but is special cased and not as general.