Grammar specification for JSON schemas

This topic describes the grammar specification for the Cedar schema. For a more complete description, see Schema format.

This grammar uses the following symbols:

• A vertical bar | designates alternatives. Only one alternative can be used.
• Brackets [ ] designate an optional element.
• Parentheses ( ) designate grouping
• Braces { } designate repetition of an element zero or more times.

Capitalized words represent grammar constructs, and lexical tokens are displayed in all-caps.

Tokens are defined using regular expressions:

• Brackets [ ] represent a range of characters.
• A vertical bar | designates alternatives.
• An asterisk * represents zero or more occurrences of an element.
• A plus sign + represents one or more occurrences of an element.
• A question mark ? represents exactly zero or one occurrences of an element.
• A tilde ~ represents the complement of the following element.
• A hyphen - represents difference.
• Single quotation marks ' ' surround elements that must be entered literally as shown.

The grammar ignores whitespace and comments.

Schema

A schema consists of a Namespace JSON object that contains EntityTypes, Actions, and (optional) CommonTypes components. The grammar assumes a particular order of keys in JSON objects to simplify the presentation, but this order is not technically required. For example, the grammar as written requires that entity type declarations appear before actions, but actions may nonetheless be declared before entity types.

Schema ::= '{' Namespace ':' '{' EntityTypes ',' Actions [',' CommonTypes] '}' '}'

Namespace

The Namespace element is a string made up of a sequence of one or more substrings separated by double colons (::). This namespace serves as a qualifier, or disambiguator, for entity types that might be defined in multiple namespaces. The type reference must include the namespace so that Cedar uses the correct entity type. For more information see namespace.

Namespace ::= '"' STR { '::' STR } '"'

EntityTypes

The EntityTypes element is identified by the keyword entityTypes followed by a comma-separated list of Entity types supported by your application. For more information see entityTypes.

EntityTypes ::= 'entityTypes' ':' '{' [ EntityType { ',' EntityType } ] '}'

EntityType

An EntityType element describes one entity type supported by your application. It begins with a name string for the entity type that, when qualified by its parent namespace, uniquely identifies this entity type. This element contains a memberOfTypes element that is an array list of any parent entity types that entities of this type can be a member or child of in a hierarchy. It also contains a shape element that describes the attributes of entities of this type, and a tags element that declares the tag type for entities of this type.

EntityType ::= IDENT ':' '{' [ 'memberOfTypes' ':' '[' [ IDENT { ',' IDENT } ] ']' ] [ ',' 'shape': TypeJson ] [ ',' 'tags': Type ] '}' | IDENT ':' '{' 'enum': STR+ '}'

Actions

The Actions element is a list of the individual actions supported by your application.

Actions ::= '"actions"' ':' '{' [ Action { ',' Action } ] '}'

Action

The Action element describes one action supported by your application. An action consists of a name string, an optional memberOf element, and a required appliesTo element. The memberOf element specifies what action groups the declared action is a member of in the action hierarchy. The appliesTo element defines the principal types, resource types, and other context information that can be specified in a request for the action.

Action ::= STR ':' '{' [ '"memberOf"' ':' '[' [ STR { ',' STR } ] ']' ] ',' '"appliesTo"' ':' '{' PrincipalTypes ',' ResourceTypes [',' Context] '}' '}'

PrincipalTypes

The PrincipalTypes element is identified by the keyword principalType followed by a comma-separated array list of the principal types supported by your application for the containing action.

PrincipalTypes ::= '"principalTypes"': '[' [ IDENT { ',' IDENT } ] ']'

ResourceTypes

The ResourceTypes element follows the same format and serves the same purpose as as the PrincipalTypes, but instead lists the resource types supported for the containing action.

ResourceTypes ::= '"resourceTypes"': '[' [ IDENT { ',' IDENT } ] ']'

Context

The Context element describes the type of the context record for an action using the same TypeJson format used for the shape of an entity type.

Context ::= '"context"' ':' TypeJson

TypeJson

The TypeJson element describes

TypeJson ::= '{' Type '}'

Type

The Type element describes

Type ::= Primitive | Set | EntityRef | Record | Extension | EntityOrCommon

Primitive

The Primitive element describes

Primitive ::= '"type":' ('"Long"' | '"String"' | '"Boolean"' | TYPENAME)

Set

The Set element describes

Set ::= '"type": "Set", "element": ' TypeJson

EntityRef

The EntityRef element describes

EntityRef ::= '"type": "Entity", "name": "' Name '"'

Record

The Record element describes

Record ::= '"type": "Record", "attributes": {' [ RecordAttr { ',' RecordAttr } ] '}'

RecordAttr

The RecordAttr element describes

RecordAttr ::= STR ': {' Type [',' '"required"' ':' ( true | false )] '}'

Extension

The Extension element describes

Extension ::= '"type": "Extension", "name": "' Name '"'

EntityOrCommon

The EntityOrCommon element describes

EntityOrCommon ::= '"type": "EntityOrCommon", "name": "' Name '"'

STR

STR ::= Fully-escaped Unicode surrounded by '"'s

IDENT

IDENT ::= ['_''a'-'z''A'-'Z']['_''a'-'z''A'-'Z''0'-'9']* - RESERVED

CommonTypes

The CommonTypes element is identified by the keyword commonTypes followed by a comma-separated list of common types supported by your application. For more information see commonTypes.

CommonTypes ::= 'commonTypes' ':' '{' [ CommonType { ',' CommonType } ] '}'

CommonType

A CommonType element describes one common type supported by your application. It begins with a name string for the common type that, when qualified by its parent namespace, uniquely identifies this common type.

CommonType ::= TYPENAME ':' TypeJson
TYPENAME   ::= IDENT - RESERVED
RESERVED   ::= 'Bool' | 'Boolean' | 'Entity' | 'Extension' | 'Long' | 'Record' | 'Set' | 'String'