bSDD tech updates

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:


:warning: 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. 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

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. 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.

Subject: Class types

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.

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

:warning: 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.

Subject: Update list of relations

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.

1 Like

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.

Subject: Pagination of API

Description: API should allow to specify a limit of records to be returned and offset from the first records shown.

Reason for change: To improve the performance and support implementation.

What is affected: REST API requests that return a list.

When: Already implemented on Test. Planned push to production: 2023-11-07T23:00:00Z.

Transition plan: No need, it only extends the functionality.

Subject: Property request API

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.

Hi @artur_tomczak, is there any fresh diagram of bSDD data model, covering all updates up-to-date?
THX!

Yes! It’s available at this branch of the bSDD repo: https://github.com/buildingSMART/bSDD/blob/bsdd-202-renaming/Documentation/bSDD%20JSON%20import%20model.md
This will become the main branch when we push changes to production.

2 Likes

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).

1 Like

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.

1 Like

Subject: Easier way to test bSDD

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.

Subject: Include reverse relations

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.

Subject: Support for diacritics

Description: Right now only (a-z, A-Z, 0-9, “_”, “.”, “-”) are allowed. Since the bSDD codes should be used as identifiers within the IFC and native formats, they should allow for diacritics and whitespaces, such as: ‘ä ą ż ź ć 開 発
Й Ӂ Д $ ( )’
.

Still forbidden should be special html characters such as * # % / \ : { } [ ’ ] | ; < > ? ` ~ " *, even though some software allows defining them in BIM models (e.g. Revit allows / ’ ( ) % # $

While generating the URI, the codes will be encoded.
Example: code: ”éc olé” → URI: “%C3%A9c%20ol%C3%A9“

Reason for change: Implementers requests. This way, it will be possible to reflect names commonly used in BIM datasets (Finnish, Japanese, Polish, etc).

What is affected: Code attributes (Class.Code, Property.Code, PropertySet, OrganizationCode, DictionaryCode). Software that didn’t allow for diacritics should prepare for such content.

When: Work in progress. Waiting for your feedback. Planned push to production, approximately 2024-02-29T23:00:00Z.

Transition plan: No need, it only extends the functionality.

Subject: Update the dictionary of IFC

Description: The key data dictionary - IFC - as it is the cornerstone of openBIM standards until now was published in a raw form, containing too many technical details from the documentation. On the other hand, it was missing many properties, attributes and inheritance of those.

The updated IFC dictionary has:

  • human-friendly names while keeping the machine-friendly codes unchanged. Example: Name: “Stair Flight” (Code: “IfcStairFlight”)..
  • The same applies to predefined types. Example: Name: “Solid Wall” (Code: “IfcWallSOLIDWALL”)..
  • definitions limited to the semantic explanation. The technical details such as History and implementation notes are omitted.
  • add hyperlinks pointing to other definitions from within the IFC
  • datatype of properties and whenever an entity is used as a datatype providing an explanation in the description.
  • dimension of properties (e.g. 3,0,0,0,0,0,0 for IfcVolumeMeasure)

Excluded will be all entities and properties (and their subelements):

  • marked as deprecated
  • primitives and geometry definitions (incl. IfcTime, IfcPoint, IfcLine, IfcBoundingBox, IfcApplication, IfcPerson)
  • relations
  • quantities
  • types, templates
  • selects
  • resources
  • measures

Reason for change: To improve the content of IFC data dictionary for better usability and clarity. To support the translation efforts.

What is affected: Content of the version 4.3 of the IFC dictionary from buildingSMART on the Production and Test servers. Link: IFC 4.3 (bSDD). It will not be a new version, but override current Preview version to maintain existing relations. Once activated, there will be no changes allowed to this version.

When: Work in progress. You might notice changes to the IFC dictionary on the Production server for the next weeks. Planned finalising of the IFC dictionary and changing the status to Active approximately 2024-02-29T23:00:00Z.
Using this occasion to apologise for the potential problems related to the unannounced update of the IFC earlier this month.

Transition plan: No transition plan, as the dictionary was in the Preview status.