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.
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.
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.
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.
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.
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. Update: Available on Test, planned push to production: 2023-11-07T23:00:00Z.
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
disable Materials APIs
disable APIs returning separate list of Materials
update import to block when Materials list is used
Step 3: planned for August 2024
remove support for requesting Materials using “mat” in the URI
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. Update: Available on Test, planned push to production: 2023-11-07T23: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.
Description Until now, possible class types included, among others: “ReferenceDocument”, “ComposedProperty”, “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. “ComposedProperty” can be addressed with the “GroupOfProperties” class type and “ConnectedPropertiesCode” attribute of property.
We will also add “Material” to the list of types. “Class”, “GroupOfProperties”, 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. Update: Available on Test, planned push to production: 2023-11-07T23: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”, “ConnectedProperties” and “Domain” types.
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
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.
Description: Remove IsSynonymOf relation and add IsSimilarTo, and IsPartOf.
Reason for change: To simplify the data model and make the interpretation of data dictionaries more straightforward for software implementation. IsSynonymOf was too ambiguous. IsPartOf is reverse of HasPart, enabling defining dependent dictionaries. This change makes bSDD more compliant with standards, as IsSimilarTo is directly coming from ISO12006-3. Update: also removed IsParentOf, IsChildOf, HasPart
for properties.
What is affected: List of Property and Class relation types.
When: Already implemented on Test. Planned push to production: 2023-11-07T23:00:00Z.
Transition plan: From now on we won’t allow uploading old relation types and will allow new ones.
All four changes are now implemented on the Test environment and are planned to be pushed to production on 2023-11-07T23:00:00Z. This might get delayed if we encounter problems during testing. Even though most existing API functionalities will be maintained for the transition period, please make sure your software implementation supports or is not affected by new changes. If you need more time, let us know.
Description: Add a GET method for getting all properties of a dictionary.
Added: GET /api/Dictionary/v1/Properties
Reason for change: To support implementation, when needed to provide a list of all properties for example, for IDS requirements or building relations between dictionaries.
What is affected: New REST API request, not affecting anything else.
When: Already implemented on Test. Planned push to production: 2023-11-07T23:00:00Z.
Transition plan: No need, it only extends the functionality.
UPDATE All those changes are now deployed on production (the actual bSDD), and reflected in the documentation. For search page users: you might need to refresh your browser cache (ctrl+F5).
We have updated bSDD’s Excel template to support the latest data model (2.0) and included instructions for the Python script to convert the Excel to JSON.
Note: The only accepted input format to bSDD is a JSON file structured according to our specifications; Excel is only to help prepare the JSON file.
Description: Add a simple way for users to test publishing in bSDD by uploading a sample data that will be visible to everyone, but will remain in Preview status and automatically disappear after 60 days. No option to activate such content.
Reason for change: We encourage people to test publishing in bSDD but see sometimes they leave such a demo content forever. Some users are also afraid of making a mistake or others using their demo content. We want to offer them an easy way to test without headaches.
What is affected: New button in the management portal and new boolean attribute IsTest on the upload API (POST /api/UploadImportFile).
When: Already implemented on the Test. Waiting for your feedback. Planned push to production: 2024-02-29T23:00:00Z.
Transition plan: No need, it only extends the functionality.
Description: Add an option to request also classes related to the class of interest (incoming relations). Those relations do not necessarily belong to the same dictionary. For example, ask to return all classes that point at IfcWall (related to IfcWall).
Reason for change: Based on developers requests. To enable getting related dictionaries without parsing whole bSDD.
What is affected:/api/Class got a new boolean attribute: IncludeReverseRelations
When: Already implemented on the Test. Waiting for your feedback. Planned push to production: 2024-02-29T23:00:00Z.
Transition plan: No need, it only extends the functionality.
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.
