Feature/#321 topic files in viewpoints (#330)

* Add id to topic files

* Add topic file ids to viewpoints

* Update TOC

* Fix reference to correct section in README

* Add clarification to not allow deletion of used topic files

Author: GeorgDangl

README.md

@@ -90,6 +90,7 @@ The Open CDE workgroup develops the BCF standard. The group meets every second M
       - [3.5.2.14 Translucency](#35214-translucency)
         - [Optimization rules](#optimization-rules-3)
       - [3.5.2.15 Translucency setup hints](#35215-translucency-setup-hints)
+      - [3.5.2.16 Topic File Ids](#35216-topic-file-ids)
     - [3.5.3 GET Viewpoint Service](#353-get-viewpoint-service)
     - [3.5.4 GET Viewpoint Snapshot Service](#354-get-viewpoint-snapshot-service)
     - [3.5.5 GET Viewpoint Bitmap Service](#355-get-viewpoint-bitmap-service)
@@ -824,10 +825,12 @@ Retrieve a **collection** of file references as topic header.
     Response Code: 200 - OK
     Body:
     [{
+        "id": "570477df-428d-4d3d-a7ae-704d79da8cbd",
         "ifc_project": "0J$yPqHBD12v72y4qF6XcD",
         "filename": "OfficeBuilding_Architecture_0001.ifc",
         "reference": "https://example.com/files/0J$yPqHBD12v72y4qF6XcD_0001.ifc"
     }, {
+        "id": "5328e0a1-d027-4cca-81d1-d59afb4cf798",
         "ifc_project": "3hwBHP91jBRwPsmyf$3Hea",
         "filename": "OfficeBuilding_Heating_0003.ifc",
         "reference": "cf37bae6-0900-46be-b37f-b34754fe0b4a"
@@ -843,7 +846,7 @@ Retrieve a **collection** of file references as topic header.
 
 [file_PUT.json](Schemas/Collaboration/File/file_PUT.json)
 
-Update a **collection** of file references on the topic header. This operation is only possible when the server returns the `updateFiles` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications). Servers must always accept a [File](Schemas/Collaboration/File/file_GET.json) reference returned by the [files_information](#331-get-project-files-information-service) endpoint. Servers may also accept other values such as a combination of fields from the header of the IFC file. 
+Update a **collection** of file references on the topic header. This operation is only possible when the server returns the `updateFiles` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications). Servers must always accept a [File](Schemas/Collaboration/File/file_GET.json) reference returned by the [files_information](#331-get-project-files-information-service) endpoint. Servers may also accept other values such as a combination of fields from the header of the IFC file. Servers should reject requests that remove files that are still referenced by viewpoints withing the same topic.
 
 **Example Request**
 
@@ -864,10 +867,12 @@ Update a **collection** of file references on the topic header. This operation i
     Response Code: 200 - OK
     Body:
     [{
+        "id": "570477df-428d-4d3d-a7ae-704d79da8cbd",
         "ifc_project": "0J$yPqHBD12v72y4qF6XcD",
         "filename": "OfficeBuilding_Architecture_0001.ifc",
         "reference": "https://example.com/files/0J$yPqHBD12v72y4qF6XcD_0001.ifc"
     }, {
+        "id": "5328e0a1-d027-4cca-81d1-d59afb4cf798",
         "ifc_project": "3hwBHP91jBRwPsmyf$3Hea",
         "filename": "OfficeBuilding_Heating_0003.ifc",
         "reference": "cf37bae6-0900-46be-b37f-b34754fe0b4a"
@@ -1125,7 +1130,10 @@ Note: For viewpoints without audit information (For example viewpoints created i
                 "y": 0.4,
                 "z": 0.1
             }
-        }]
+        }],
+        "topic_file_ids": [
+            "570477df-428d-4d3d-a7ae-704d79da8cbd"
+        ]
     }, {
         "guid": "a11a82e7-e66c-34b4-ada1-5846abf39133",
         "creation_date": "2013-10-21T17:34:22.409Z",
@@ -1172,7 +1180,11 @@ Note: For viewpoints without audit information (For example viewpoints created i
                 "y": 0.0,
                 "z": 0.0
             }
-        }]
+        }],
+        "topic_file_ids": [
+            "570477df-428d-4d3d-a7ae-704d79da8cbd",
+            "5328e0a1-d027-4cca-81d1-d59afb4cf798"
+        ]
     }]
 
 ### 3.5.2 POST Viewpoint Service
@@ -1200,6 +1212,7 @@ JSON encoded body using the "application/json" content type.
 | bitmaps | array of [Bitmap](#3527-bitmap) | embedded pictures in the viewpoint | optional |
 | snapshot | [Snapshot](#3528-snapshot) | snapshot image of the viewpoint. Note: The longest dimension of should not exceed 1500 px, length or width. |  see viewpoint optional/mandatory fields clarification |
 | components | [Components](#3529-components) | Components in the viewpoint | optional |
+| topic_file_ids | array of strings | List of file ids that are referenced in the viewpoint | required, but can be an empty list |
 
 **Viewpoint optional/mandatory fields clarification**
 
@@ -1385,6 +1398,11 @@ BCF is suitable for controlling the translucency of a few components. A huge lis
 | space_boundaries_translucent | boolean | Translucency of space_boundaries | optional, default true |
 | openings_translucent         | boolean | Translucency of openings | optional, default true |
 
+
+#### 3.5.2.16 Topic File Ids
+
+Viewpoints are immutable, while topics may be changed later. To ensure that viewpoints are always referring to the correct models, the topic file IDs are used. This is a list of file IDs that are referenced in the viewpoint. The file IDs are from [GET Files (Header) Service](#332-get-files-header-service) endpoint.
+
 **Example Request**
 
     POST /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints
@@ -1492,7 +1510,10 @@ BCF is suitable for controlling the translucency of a few components. A huge lis
                     "openings_translucent": false
                 }
             }
-        }
+        },
+        "topic_file_ids": [
+            "570477df-428d-4d3d-a7ae-704d79da8cbd"
+        ]
     }
 
 **Example Response**
@@ -1567,7 +1588,10 @@ BCF is suitable for controlling the translucency of a few components. A huge lis
         }],
         "snapshot": {
             "snapshot_type": "png"
-        }
+        },
+        "topic_file_ids": [
+            "570477df-428d-4d3d-a7ae-704d79da8cbd"
+        ]
     }
 ### 3.5.3 GET Viewpoint Service
 
@@ -1657,7 +1681,10 @@ Retrieve a specific viewpoint.
         }],
         "snapshot": {
             "snapshot_type": "png"
-        }
+        },
+        "topic_file_ids": [
+            "570477df-428d-4d3d-a7ae-704d79da8cbd"
+        ]
     }
 
 ### 3.5.4 GET Viewpoint Snapshot Service

Schemas/Collaboration/File/file_GET.json

@@ -23,6 +23,10 @@
         "reference": {
             "type": ["string",
             "null"]
+        },
+        "id": {
+            "type": ["string",
+            "null"]
         }
     }
 }

Schemas/Collaboration/Viewpoint/viewpoint_GET.json

@@ -55,6 +55,13 @@
                     "$ref": "../Action/viewpoint_actions.json"
                 }
             }
+        },
+        "topic_file_ids": {
+            "required": true,
+            "type": "array",
+            "items": {
+                "type": "string"
+            }
         }
     }
 }

Schemas/Collaboration/Viewpoint/viewpoint_POST.json

@@ -41,6 +41,13 @@
         },
         "components": {
             "$ref": "components.json"
+        },
+        "topic_file_ids": {
+            "required": true,
+            "type": "array",
+            "items": {
+                "type": "string"
+            }
         }
     }
 }