Merge branch 'feature/mergePr29'

buildingSMART · Jul 26, 2016 · cf84c1a · cf84c1a
2 parents e2d9d9d + c71a76c
commit cf84c1a
Showing 6 changed files with 331 additions and 46 deletions.
diff --git a/README.md b/README.md
@@ -12,11 +12,14 @@
   * [1.1 Paging, Sorting and Filtering](#11-paging-sorting-and-filtering)
   * [1.2 Caching](#12-caching)
   * [1.3 Updating Resources via HTTP PUT](#13-updating-resources-via-http-put)
-  * [1.4 Cross Origin Resource Sharing (Cors)](#14-cross-origin-resource-sharing-cors)
+  * [1.4 Cross Origin Resource Sharing (CORS)](#14-cross-origin-resource-sharing-cors)
   * [1.5 Http Status Codes](#15-http-status-codes)
   * [1.6 Error Response Body Format](#16-error-response-body-format)
   * [1.7 DateTime Format](#17-datetime-format)
-  * [1.8 Additional Response Object Properties](#18-additional-response-object-properties)
+  * [1.8 Authorization](#18-authorization)
+    + [1.8.1 Per-Entity Authorization](#181-per-entity-authorization)
+    + [1.8.2 Determining Authorized Entity Actions](#182-determining-authorized-entity-actions)
+  * [1.9 Additional Response Object Properties](#19-additional-response-object-properties)
 - [2. Topologies](#2-topologies)
   * [2.1 Topology 1 - BCF-Server only](#21-topology-1---bcf-server-only)
   * [2.2 Topology 2 - Colocated BCF-Server and Model Server](#22-topology-2---colocated-bcf-server-and-model-server)
@@ -35,13 +38,19 @@
     + [4.1.2 GET Project Service](#412-get-project-service)
     + [4.1.3 PUT Project Service](#413-put-project-service)
     + [4.1.4 GET Project Extension Service](#414-get-project-extension-service)
+    + [4.1.5 Expressing User Authorization Through Project Extensions](#415-expressing-user-authorization-through-project-extensions)
+      - [4.1.5.1 Project](#4151-project)
+      - [4.1.5.2 Topic](#4152-topic)
+      - [4.1.5.3 Comment](#4153-comment)
+      - [4.1.5.4 Viewpoint](#4154-viewpoint)
   * [4.2 Topic Services](#42-topic-services)
     + [4.2.1 GET Topics Service](#421-get-topics-service)
     + [4.2.2 POST Topic Service](#422-post-topic-service)
     + [4.2.3 GET Topic Service](#423-get-topic-service)
     + [4.2.4 PUT Topic Service](#424-put-topic-service)
     + [4.2.6 GET Topic BIM Snippet Service](#426-get-topic-bim-snippet-service)
     + [4.2.7 PUT Topic BIM Snippet Service](#427-put-topic-bim-snippet-service)
+    + [4.2.8 Determining Allowed Topic Modifications](#428-determining-allowed-topic-modifications)
   * [4.3 File Services](#43-file-services)
     + [4.3.1 GET Files (Header) Service](#431-get-files-header-service)
     + [4.3.2 PUT Files (Header) Service](#432-put-files-header-service)
@@ -50,6 +59,7 @@
     + [4.4.2 POST Comment Service](#442-post-comment-service)
     + [4.4.3 GET Comment Service](#443-get-comment-service)
     + [4.4.4 PUT Comment Service](#444-put-comment-service)
+    + [4.4.5 Determining allowed Comment modifications](#445-determining-allowed-comment-modifications)
   * [4.5 Viewpoint Services](#45-viewpoint-services)
     + [4.5.1 GET Viewpoints Service](#451-get-viewpoints-service)
     + [4.5.2 POST Viewpoint Service](#452-post-viewpoint-service)
@@ -59,6 +69,7 @@
     + [4.5.6 PUT Viewpoint Snapshot Service](#456-put-viewpoint-snapshot-service)
     + [4.5.7 GET Viewpoint Bitmap Service](#457-get-viewpoint-bitmap-service)
     + [4.5.8 PUT Viewpoint Bitmap Service](#458-put-viewpoint-bitmap-service)
+    + [4.5.9 Determining allowed Viewpoint modifications](#459-determining-allowed-viewpoint-modifications)
   * [4.6 Component Services](#46-component-services)
     + [4.6.1 GET Components Service](#461-get-components-service)
     + [4.6.2 PUT Components Service](#462-put-components-service)
@@ -153,7 +164,65 @@ DateTime values in this API are supposed to be in ISO 8601 compliant `YYYY-MM-DD
 
 For example, `2016-04-28-16:31.27+2:00` would represent _Thursday, April 28th, 2016, 16:31 (270ms) with a time zone offset of +2 hours relative to UTC._
 
-## 1.8 Additional Response Object Properties
+## 1.8 Authorization
+
+API implementors can optionally choose to restrict the actions a user is allowed to perform on the BCF entities
+via the API. The global default authorizations for all entities are expressed in the project extensions schema and can
+be locally overridden in the entities themselves.
+
+### 1.8.1 Per-Entity Authorization
+
+Whenever a user requests an update-able entity with the request parameter `includeAuthorization` equal to `true` the
+server should include an `authorization` field in the entity containing any local variations from the global
+authorization defaults for that entity. Using this information clients can decide whether to, for example, include an
+"Edit" button in the UI displaying the entity depending on the actions permitted for the user.
+
+### 1.8.2 Determining Authorized Entity Actions
+
+The client can calculate the available set of actions for a particular entity by taking the project-wide defaults from
+the project extensions, then replacing any keys defined in the entity's `authorization` map with the values specified
+locally. The meaning of each of the authorization keys is outlined in outlined in
+[4.1.5 Expressing User Authorization through Project Extensions](#415-expressing-user-authorization-through-project-extensions).
+
+**Example Scenario (Topic)**
+
+_In the Project Extensions_
+
+    {
+        "topic_actions": [],
+        "topic_status": [
+            "open",
+            "closed",
+            "confirmed"
+        ]
+    }
+
+Indicating that by default:
+
+* no modifications can be made to Topics
+* Topics can be placed in `open`, `closed` or `confirmed` status
+
+_In the Topic_
+
+    {
+        "authorization": {
+            "topic_actions": [
+                "update",
+                "createComment",
+                "createViewpoint"
+            ],
+            "topic_status": [
+                "closed"
+            ]
+        }
+    }
+
+Indicating that for this topic, the current user can:
+
+* update the Topic, or add comments or viewpoints
+* place the Topic into `closed` status
+
+## 1.9 Additional Response Object Properties
 
 All API response Json objects may contain additional properties that are not covered by this specification.
 This is to allow server implementations freedom to add additional functionality. Clients shall ignore those properties.
@@ -421,10 +490,19 @@ Retrieve a **collection** of projects where the currently logged on user has acc
     Body:
     [{
         "project_id": "F445F4F2-4D02-4B2A-B612-5E456BEF9137",
-        "name": "Example project 1"
+        "name": "Example project 1",
+		"authorization": {
+            "project_actions": [
+                "createTopic",
+                "createDocument"
+            ]
+        }
     }, {
         "project_id": "A233FBB2-3A3B-EFF4-C123-DE22ABC8414",
-        "name": "Example project 2"
+        "name": "Example project 2",
+		"authorization": {
+            "project_actions": []
+        }
     }]
 
 ### 4.1.2 GET Project Service
@@ -447,7 +525,13 @@ Retrieve a specific project.
     Body:
     {
         "project_id": "B724AAC3-5B2A-234A-D143-AE33CC18414",
-        "name": "Example project 3"
+        "name": "Example project 3",
+		"authorization": {
+            "project_actions": [
+                "update",
+                "updateProjectExtensions"
+            ]
+        }
     }
 
 ### 4.1.3 PUT Project Service
@@ -474,7 +558,13 @@ Modify a specific project.
     Body:
     {
         "project_id": "B724AAC3-5B2A-234A-D143-AE33CC18414",
-        "name": "Example project 3 - Second Section"
+        "name": "Example project 3 - Second Section",
+		"authorization": {
+            "project_actions": [
+                "update",
+                "updateProjectExtensions"
+            ]
+        }
     }
 
 ### 4.1.4 GET Project Extension Service
@@ -524,9 +614,78 @@ Project extensions are used to define possible values that can be used in topics
             "[email protected]",
             "[email protected]",
             "[email protected]"
+        ],
+        "project_actions": [
+            "update",
+            "createTopic",
+            "createDocument",
+            "updateProjectExtensions"
+        ],
+        "topic_actions": [
+            "update",
+            "updateBimSnippet",
+            "updateRelatedTopics",
+            "updateDocumentServices",
+            "updateFiles",
+            "createComment",
+            "createViewpoint"
+        ],
+        "comment_actions": [
+            "update"
+        ],
+        "viewpoint_actions": [
+            "update",
+            "updateBitmap",
+            "updateSnapshot",
+            "updateComponent"
         ]
     }
 
+### 4.1.5 Expressing User Authorization Through Project Extensions
+
+Global default authorizations for the requesting user can be expressed in the project schema. The actions authorized
+here will apply to any entities that do not override them locally. The complete set of options for the BCF entities are
+listed below.
+
+#### 4.1.5.1 Project
+
+The 'project_actions' entry in the project extensions defines what actions are allowed to be performed
+at the project level. The available actions include:
+
+* *update* - The ability to update the project details (see [4.1.3 PUT Project Service](#413-put-project-service))
+* *createTopic* - The ability to create a new topic (see [4.2.2 POST Topic Service](#422-post-topic-service))
+* *createDocument* - The ability to create a new document (see [4.9.2 POST Document Service](#492-post-document-service))
+
+#### 4.1.5.2 Topic
+
+The 'topic_actions' entry in the project extensions defines what actions are allowed to be performed at the topic
+level by default (i.e. unless overridden by specific topics) The available actions include:
+
+* *update* - The ability to update the topic (see [4.2.4 PUT Topic Service](#424-put-topic-service))
+* *updateBimSnippet* - The ability to update the BIM snippet for topics (see [4.2.7 PUT Topic BIM Snippet Service](#427-put-topic-bim-snippet-service))
+* *updateRelatedTopics* - The ability to update the collection of related topics (see [4.7.2 PUT Related Topics Service](#472-put-related-topics-service))
+* *updateDocumentReferences* - The ability to update the collection of document references (see [4.8.3 PUT Document Reference Service](#483-put-document-reference-service))
+* *updateFiles* - The ability to update the file header (see [4.3.2 PUT Files (Header) Service](#432-put-files-header-service))
+* *createComment* - The ability to create a comment (see [4.4.2 POST Comment Service](#442-post-comment-service))
+* *createViewpoint* - The ability to create a new viewpoint (see [4.5.2 POST Viewpoint Service](#452-post-viewpoint-service))
+
+#### 4.1.5.3 Comment
+
+The 'comment_actions' entry in the project extensions defines what actions are allowed to be performed at the comment level by
+default (i.e unless overridden by specific comments). The available actions include:
+
+* *update* - The ability to update the comment (see [4.4.4 PUT Comment Service](#444-put-comment-service))
+
+#### 4.1.5.4 Viewpoint
+
+The 'viewpoint_actions' entry in the project extensions defines what actions are allowed to be performed at the viewpoint level by
+default (i.e. unless overridden by specific viewpoints). The available actions include:
+
+* *update* - The ability to update the viewpoint (see [4.5.4 PUT Viewpoint Service](#454-put-viewpoint-service))
+* *updateBitmap* - The ability to update the bitmap for the viewpoint (see [4.5.8 PUT Viewpoint Bitmap Service](#458-put-viewpoint-bitmap-service))
+* *updateSnapshot* - The ability to update the snapshot for the viewpoint (see [4.5.6 PUT Viewpoint Snapshot Service](#456-put-viewpoint-snapshot-service))
+* *updateComponent* - The ability to update the component for the viewpoint (see [4.6.2 PUT Components Service](#462-put-components-service))
+
 ---------
 
 ## 4.2 Topic Services
@@ -718,6 +877,12 @@ Retrieve a specific topic.
             "is_external": true,
             "reference": "https://example.com/bcf/1.0/ADFE23AA11BCFF444122BB",
             "reference_schema": "https://example.com/bcf/1.0/clash.xsd"
+        },
+		"authorization": {
+            "topic_actions": [
+                "createComment",
+                "createViewpoint"
+            ]
         }
     }
 
@@ -797,6 +962,12 @@ Retrieves a topics BIM-Snippet as binary file.
 
 Puts a new BIM Snippet binary file to a topic. If this is used, the parent topics BIM Snippet property `is_external` must be set to `false` and the `reference` must be the file name with extension.
 
+### 4.2.8 Determining Allowed Topic Modifications
+
+The global default Topic authorizations are expressed in the project schema and when Topic(s) are requested with the
+parameter "includeAuthorization" equal to "true" Topics will include an "authorization" field containing any local
+overrides for each Topic.
+
 ## 4.3 File Services
 
 ### 4.3.1 GET Files (Header) Service
@@ -910,7 +1081,12 @@ Get comments that are closed and created after December 5 2015. Sort the result
         "date": "2016-08-01T12:34:22.409Z",
         "author": "[email protected]",
         "comment": "Clash found",
-        "topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228"
+        "topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228",
+		"authorization": {
+            "comment_actions": [
+                "update"
+            ]
+        }
     }, {
         "guid": "A333FCA8-1A31-CAAC-A321-BB33ABC8414",
         "date": "2016-08-01T14:24:11.316Z",
@@ -1003,6 +1179,7 @@ Update a single comment, description similar to POST.
         "comment": "will rework the heating model and fix the ventilation"
     }
 
+
 **Example Response**
 
     Response Code: 200 - OK
@@ -1017,6 +1194,12 @@ Update a single comment, description similar to POST.
         "topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228"
     }
 
+### 4.4.5 Determining allowed Comment modifications
+
+The global default Comment authorizations are expressed in the project schema and when Comment(s) are requested with the
+parameter "includeAuthorization" equal to "true" Comments will include an "authorization" field containing any local
+overrides for each Comment.
+
 ## 4.5 Viewpoint Services
 
 ### 4.5.1 GET Viewpoints Service
@@ -1084,6 +1267,14 @@ Retrieve a **collection** of all viewpoints related to a topic.
                     "z": 0.1
                 }
             }]
+        },
+        "authorization": {
+            "viewpoint_actions": [
+                "update",
+                "updateBitmap",
+                "updateSnapshot",
+                "updateComponent"
+            ]
         }
     }, {
         "guid": "a11a82e7-e66c-34b4-ada1-5846abf39133",
@@ -1132,8 +1323,12 @@ Retrieve a **collection** of all viewpoints related to a topic.
                     "z": 0.0
                 }
             }]
+        },
+        "authorization": {
+            "viewpoint_actions": []
         }
     }]
+
 ### 4.5.2 POST Viewpoint Service
 
 **Resource URL**
@@ -1347,6 +1542,14 @@ Retrieve a specific viewpoint.
                     "z": 0.0
                 }
             }]
+        },
+        "authorization": {
+            "viewpoint_actions": [
+                "update",
+                "updateBitmap",
+                "updateSnapshot",
+                "updateComponent"
+            ]
         }
     }
 
@@ -1497,10 +1700,15 @@ PUT Body contains binary image data
 
 **Example Response**
 
-
     Response Code: 200 - OK
     Empty Body
 
+### 4.5.9 Determining allowed Viewpoint modifications
+
+The global default Viewpoint authorizations are expressed in the project schema and when Viewpoint(s) are requested with the
+parameter "includeAuthorization" equal to "true" Viewpoints will include an "authorization" field containing any local
+overrides for each Viewpoint.
+
 ## 4.6 Component Services
 
 ### 4.6.1 GET Components Service
@@ -1799,4 +2007,4 @@ Retrieves a document as binary file.
 
 **Example Response**
 
-Retrieves a document as binary file.
+Retrieves a document as binary file.
diff --git a/Schemas_draft-03/Collaboration/Comment/comment_GET.json b/Schemas_draft-03/Collaboration/Comment/comment_GET.json
@@ -37,6 +37,19 @@
         "modified_author": {
             "type": ["string",
             "null"]
+        },
+        "authorization": {
+            "type": "object",
+            "required": false,
+            "properties": {
+                "comment_actions": {
+                    "required": false,
+                    "type": "array",
+                    "items": {
+                        "enum": ["update"]
+                    }
+                }
+            }
         }
     }
 }