Hi 
In this thread, we will inform you of planned and recently implemented bSDD updates that might affect you. We will cover changes to the API, search page, management portal, data model, documentation, and technology, if those happen.
We will be editing the posts, for example, to update when the change actually occurs. We will not cover here changes to the content of bSDD (dictionaries). You can comment on the updates, but please start a new topic if the question is unrelated. We reserve the right to move off-topic posts to new threads.
If you want to stay updated, turn on notifications for that topic. 
2 Likes
Subject: Slash not dash before version in URI
Description: Until now, we used to have a dash separating dictionary name and version (…/abc-1.2.3/…), but from now on we use a slash (…/abc/1.2.3/…).
Reason for change: For consistency and to support page navigation allowing to list all versions of a dictionary.
When: Already implemented on production.
Transition plan: To support all prior use cases, the dash URI will be recognized and translated to the proper one with a slash. All new uploads should use a slash to build relations. The API now returns a slash.
Subject: Breadcrumb navigation with URL and new subpages
Description: Until now, we used to have a generic URL of the search page. From now on, the actual URI (identifier) is also used for page navigation.
.../Classification/Index/58078 → /uri/bs-agri/fruitvegs/1.0.0
We also added the subpages for intermediate resources like classProperty or propertySet, and a lists of content.
Reason for change: To support intuitive page navigation with breadcrumbs and enable trimming of the path to reach certain resources. Now, it is possible to see, for example:
When: Already implemented on production. Additionally, the property set content page is on the development, and will be pushed to production soon.
Transition plan: This only extends existing functionality.
Subject: Management of the version lifecycle
Description: Until now, the status of the dictionary version depended on the information in an upload file. From now on, the Status of uploaded content will always be set to “Preview”, regardless of what the input file says, and there are two ways to change the status: through the Management Portal or via the API. After upload, you can reupload the content to modify it, activate the version, or permanently delete it. The status can be changed according to the diagram below:
Once the content is activated, it
will get an immutable URI, meaning the URL and content
will stay in bSDD forever, and can’t be deleted. Changing the status to “Inactive” is possible, but the page will still show the content to support use in contractual agreements. Consider that before activating a version of a dictionary.
New API endpoints:
Reason for change: Managing the status from the upload file was not intuitive. The new approach provides better control over the content.
What is affected: Import process, API, Management Portal.
When: New workflow already implemented on production. The new version of the API is available on the test environment Swagger UI before it is pushed to production.
Transition plan: The “status” property in the upload file will be ignored.
CC: @Erik.bSDD @berlotti @frederic.grand @michelangelo @Yousheng @jbrouwer @jan_erik_hoel
1 Like
Subject: Management portal changes
Description: The management portal will now have one comprehensive view of the dictionaries you can access, including upload and download options. All versions will now be grouped under dictionary name, and there will be new buttons to download, change status, delete/deprecate, change privacy and give access to certain people (if not public).
Reason for change: To reflect the changes to the content lifecycle and to make MP easier to use.
What is affected: Management Portal
When: Most already available in the production MP. The merging of download/upload will take place with the next deployment0.
Transition plan: No need for it.
Subject: Material APIs obsolete
Description All Material specific APIs will be removed. Separate listings of Materials will also be removed from API output.
Reason for change: As Materials are actually just Classifications it’s easier to have just one way to handle them. ClassificationType attribute will indicate if it’s a Material.
What is affected: Several APIs
When: We’re currently making preparations for a smooth transition.
Transition plan:
Step 1:
-
update APIs returning Classifications to optionally also include Materials; current behaviour will stay the same. Developers should update to use these APIs to also get Materials
-
update import to accept Materials being part of the list of Classifications, give warning when Materials list is used
-
the “mat” in the URI of Materials will be replaced by “class”; requests using “mat” in them will be supported, but all APIs will return new URI, e.g. …/uri/bimloket/naakt/0.1/class/betonbimsbeton
Step 2: planned for Februari 2024
Step 3: planned for August 2024
- remove support for requesting Materials using “mat” in the URI
Subject: Renaming to ‘Dictionary’ and ‘Class’
Description ‘Domain’ to be renamed to ‘Dictionary’ and ‘Classification’ to a ‘Class’.
Reason for change: Based on many discussions and user feedback, and to be more aligned with the interpretation of ISO standards…
What is affected: The documentation, API names, import/export model (all properties with those names), templates, search page UI.
When: We’re currently preparing for a smooth transition of multiple changes in one API update. Expected deployment to TEST: 2023-09-26T22:00:00Z.
Transition plan: For 6 months we will upkeep the old API and support old import template next to the new ones (until 2024-03-14T23:00:00Z). Please switch to a new API and templates when they are published.
Subject: Class types
Description Until now, possible class types included, among others: “ReferenceDocument”, “Domain”. Since ReferenceDocument list is governed by buildingSMART and cover most popular standards, this was an overlap. If some documents are missing, users can report and bS will review if list should be extended. Domain is confusing term and did not find application other than to define scope of interest for experts to review, which is not in scope of bSDD. We will also add “Material” to the list of types. “Class”, “GroupOfProperties”, “ComposedProperty” and “AlternativeUse” will remain.
Reason for change: This is to simplify bSDD and ensure all users refer to same documents.
What is affected: Existing content, data model, documentation.
When: We’re currently preparing for a smooth transition of multiple changes in one update. Expected deployment: 2023-08-22T22:00:00Z.
Transition plan: Existing classes of such type are mostly test data, so we will change their type to ‘AlternativeUse’. New uploads won’t allow for “ReferenceDocument” and “Domain” type.
Subject: Latest version URL
Description In bSDD, all resources get a unique identifier - URI. The URI, among other information, contains codes of the organisation, the dictionary and the version number, for example: …/uri/bs-agri/fruitvegs/1.0.0/class/fruit
If you want to reference specific resources but are not sure of the version or want to always point to the most recent version, we implemented the “latest” feature. Now, it is possible to use “latest” instead of a version number, and bSDD will resolve the link to the latest active or preview version:
…/uri/bs-agri/fruitvegs/latest/class/fruit
Try it out:
https://search.bsdd.buildingsmart.org/uri/bs-agri/fruitvegs/latest/class/fruit
The “latest” points to the most recent resource, meaning that it will change once a new version is present. Use with caution as it is not an immutable URI, and the content can change. For contractual agreements, we suggest using specific version numbers.
Reason for change: Sometimes users want to reference the most recent resource in other dictionaries. This prevents the need to update all relations manually.
What is affected: Additional feature. Changes page navigation and documentation.
When: Already implemented.
Transition plan: This extends bSDD functionalities, without limiting existing ones.
