updates for rfc#70 and cedar#1150 (#130)

docs/collections/_schema/human-readable-schema-grammar.md

@@ -37,7 +37,7 @@ Namespace := ('namespace' Path '{' {Decl} '}') | Decl
 Decl      := Entity | Action | TypeDecl
 Entity    := 'entity' Idents ['in' EntOrTyps] [['='] RecType] ';'
 Action    := 'action' Names ['in' RefOrRefs] [AppliesTo]';'
-TypeDecl  := 'type' IDENT '=' Type ';'
+TypeDecl  := 'type' TYPENAME '=' Type ';'
 Type      := Path | SetType | RecType
 EntType   := Path
 SetType   := 'Set' '<' Type '>'
@@ -56,8 +56,10 @@ Names     := Name {',' Name}
 Idents    := IDENT {',' IDENT}
 
 IDENT     := ['_''a'-'z''A'-'Z']['_''a'-'z''A'-'Z''0'-'9']*
+TYPENAME  := IDENT - RESERVED
 STR       := Fully-escaped Unicode surrounded by '"'s
 PRIMTYPE  := 'Long' | 'String' | 'Bool'
 WHITESPC  := Unicode whitespace
 COMMENT   := '//' ~NEWLINE* NEWLINE
+RESERVED  := 'Bool' | 'Boolean' | 'Entity' | 'Extension' | 'Long' | 'Record' | 'Set' | 'String'
 ```

docs/collections/_schema/human-readable-schema.md

@@ -199,29 +199,21 @@ namespace Demo {
 }
 ```
 
- Common types and entity types can both be qualified with namespaces.
- The human-readable format allows *inline* declarations. Because of this, there may be conflicts between type names declared within a namespace and those declared using inline declarations. The resolution rule for this scenario is like *static scoping*: type names within the same namespace have higher priority. The following example demonstrates this rule.
+Common types and entity types can both be qualified with namespaces.
+We do not allow defining entity types or common types that would shadow definitions of other entity types or common types in the empty namespace.
+For example, the following schema is *invalid*.
 
  ```cedarschema
 type id = {
   group: String,
   name: String,
 };
 
-type email_address = {
-  id: String,
-  domain: String,
-};
-
 namespace Demo {
   entity User {
-    // The type of attribute `name` is the primitive type `String`
-    // because there is a common type declaration below.
     name: id,
-    // The type of attribute `email` is the common type `email_address`
-    // declared above.
-    email: email_address;
   };
+  // ERROR - this definition of `id` would shadow the one above
   type id = String;
 }
 ```

docs/collections/_schema/json-schema-grammar.md

@@ -34,7 +34,7 @@ The grammar ignores whitespace and comments.
 
 ## `Schema` {#grammar-schema}
 
-A schema consists of a [`Namespace`](#grammar-schema-Namespace) JSON object that contains a list of [`EntityTypes`](#grammar-schema-EntityTypes), and a list of [`Actions`](#grammar-schema-Actions).
+A schema consists of a [`Namespace`](#grammar-schema-Namespace) JSON object that contains [`EntityTypes`](#grammar-schema-EntityTypes), [`Actions`](#grammar-schema-Actions), and (optional) [`CommonTypes`](#grammar-schema-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.
 
@@ -55,7 +55,7 @@ Namespace ::= '"' STR { '::' STR } '"'
 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`](../schema/schema.html#schema-entityTypes).
 
 ```
-EntityTypes ::= 'entityTypes' ':' '[' [ EntityType { ',' EntityType } ] ']'
+EntityTypes ::= 'entityTypes' ':' '{' [ EntityType { ',' EntityType } ] '}'
 ```
 
 ## `EntityType` {#grammar-schema-EntityType}
@@ -71,7 +71,7 @@ EntityType ::= IDENT ':' '{' [ 'memberOfTypes' ':' '[' [ IDENT { ',' IDENT } ] '
 The `Actions` element is a list of the individual actions supported by your application.
 
 ```
-Actions ::= '"actions"' ':' '[' [ Action { ',' Action } ] ']'
+Actions ::= '"actions"' ':' '{' [ Action { ',' Action } ] '}'
 ```
 
 ## `Action` {#grammar-schema-Action}
@@ -175,3 +175,21 @@ STR ::= Fully-escaped Unicode surrounded by '"'s
 ```
 IDENT ::= ['_''a'-'z''A'-'Z']['_''a'-'z''A'-'Z''0'-'9']* - RESERVED
 ```
+
+## `CommonTypes` {#grammar-schema-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`](../schema/schema.html#schema-commonTypes).
+
+```
+CommonTypes ::= 'commonTypes' ':' '{' [ CommonType { ',' CommonType } ] '}'
+```
+
+## `CommonType` {#grammar-schema-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](#grammar-schema-Namespace), uniquely identifies this common type.
+
+```
+CommonType ::= TYPENAME ':' TypeJson
+TYPENAME   ::= IDENT - RESERVED
+RESERVED   ::= 'Bool' | 'Boolean' | 'Entity' | 'Extension' | 'Long' | 'Record' | 'Set' | 'String'
+```

docs/collections/_schema/json-schema.md

@@ -84,6 +84,8 @@ You can reference entity types and actions defined in other namespaces of the sa
 }
 ```
 
+One special case: you cannot define entity types, actions, or common types in a namespace that would shadow definitions in the empty namespace. For example, if the entity type `Table` was also defined in the empty namespace, then the schema above would be invalid.
+
 If you change a declared namespace in your schema you will need to change the entity types appearing in your policies and/or in other namespaces declared in your schema to instead reference the changed namespace.
 
 ## `entityTypes` {#schema-entityTypes}