What's new in BCF 3.0

New Concepts and Semantic Changes

One of the major changes in the BCF API for version 3.0 is that features common to all open APIs have been moved into the OpenCDE Foundation API. This means that the OpenCDE Foundation API is a mandatory building block for the implementation of the BCF API.

General

1. Improved BCF Test Cases #185
2. Integrated an automatic checking tool to validate BCF test cases: https://github.com/CBenghi/bcf-tool
3. Clarify path separator is forward slash / #180
4. Mandate lowercase GUIDs in XML and filenames #190
5. Clarify Bitmap height #194
6. UTC as Default Timezone #197
7. Fix bugs in XML Schema Definitions #183, #187, #188, #189, #195, #198
8. Remove the DetailedVersion element in bcf.version
9. Change extensions to use an XML instance instead of being an XSD that redefines markup.xsd for easier handling in client applications. This means that types in the markup that were previously defined in the extensions are now simple strings, their validity has to be enforced at the application level in accordance with the extensions.xml
10. Move commonly used types in XSD schemas to shared files for reusability
11. Refactor and cleanup existing schemas to provide a better and more consistent developer experience
12. Allow empty lists to be omitted from XML files
13. Clarify that required elements must have a value and may not use empty strings
14. To better convey that only a single project is supported in BCF 3.0 per BCF XML file, the ExtensionSchema from project.bcfp was removed and the Project itself is now wrapped in an element called ProjectInfo
15. Clarify how IFC files are mapped to File elements with more detailed documentation
16. Clarify that additional document properties in the Xml files should be ignored when deserializing the file and not produce errors. Readme

Topics

1. Added the server_assigned_id (API) / ServerAssignedId (XML) #329
2. Deprecated index
3. Clarify that TopicType and TopicStatus are required #303
4. Clarify that GUID is required for topics

Viewpoints

1. Enhance and clarify the camera definition
2. Clarify handling of decomposed objects #167
3. Align ViewSetuphHints with BCF-API #174](https://github.com/buildingSMART/BCF-XML/issues/174)
4. Remove default snapshot and viewpoint filename convention #179
5. Clarify ClippingPlane Direction #193
6. Mark IfcGuid in components as optional in the schema if alternatively the AuthoringToolId is provided
7. Mark Color in components as required for components in the Coloring parent element
8. Specify bitmap formats as lowercase for both BCF XML and BCF API
9. Clarify usage of visibility rules with additional examples and more documentation
10. Specified maximum dimensions to be used for images to reduce BCF file sizes
11. Update the schema to make it clear that either a PerspectiveCamera or OrthogonalCamera has to be provided, never both
12. The valid range for camera FieldOfView was increased to 0 - 180 degrees, from previously 45 - 60 degrees
13. Allow both png and jpeg (new) image formats for viewpoint snapshots
14. Extend documentation for the Coloring part of components
15. Added AspectRatio for the camera definitions to ensure reliable restoration of viewpoints on devices with varying screen dimensions
16. Clarify that FieldOfView and ViewToWorldScale is vertical
17. Added Implementation Notes for working with cameras, also when dealing with older versions of BCF, with code examples
18. Clarify that camera direction and up vectors must not be zero length vectors or parallel to each other

Comments

1. When no viewpoint is referenced in a comment, the text must not be empty #196

Document References

1. Mandatory reference GUID #158
2. DocumentReferences were refactored to use a dedicated type in the XSD schemas and to be wrapped in a list container

Documents

1. Added documents.xml to better manage document exchange
2. Clarified that document files should be stored under a /Documents folder at the root of the BCF file

Under Discussion or deferred to BCF 3.x

1. Additional Properties #161
2. Topic markers (pins) #86
3. Component data for non-geometric authoring tools #99
4. Normalize Camera Direction #178

BCF API Specific Changes

Per-Entity Authorization

Must include all possible user choices for enumerated fields including the current value.

Changed Services

GET Project Extension Service

1. project_actions enumeration no longer includes updateProjectExtensions - project extensions should be updated using the server's user interface.
2. Typo fix: updateDocumentServices corrected to updateDocumentReferences in the topic_actions enumeration

GET Topics Service

1. Added filters - priority and server_id
2. Added sort parameter - server_id
3. Returned topics must include a server_id

POST Topic Service

1. Clients can provide a desired guid, to have the BCF API better aligned with BCF XML

POST Comment Service

1. Clients can provide a desired guid

POST Viewpoint Service

1. Clients can provide a desired guid

Topic Event Service

GET Topics events and GET Topic events services can return additional stage_added stage_updated and stage_removed events.

Added Services

DELETE 'Object' Services

1. DELETE Topic Service - deletes a single topic
2. DELETE Comment Service - deletes a single comment.
3. DELETE Viewpoint Service - deletes a single viewpoint.

GET Project Files Information Service

User friendly listing of Project Files to streamline the association of topics and models

GET Snapshot Thumbnail Service

As proposed in BCF-XML/#186 as service that would allow clients to request a snapshot thumbnail from the server

Services Deleted

1. Versions Service
2. Authentication Services

Both have moved under the OpenCDE Foundation API.

---

OpenCDE Foundation API

The following changes have been introduced into the OpenCDE Foundation API and were not present in previous versions of the BCF API.

1. Clarification of how binary file uploads should be handled
2. Difference between null and empty lists