Creating a data dictionary is a crucial step in managing the accessibility, quality, and integrity of data. A data dictionary serves as a centralized repository of information about data, such as meaning, relationships to other data, origin, usage, and format. Here are some good practices for defining a data dictionary.

Decompose complex data

It's essential to break down information effectively to optimize the structure and terminology of a data dictionary. We recommend decomposing complex terms into simpler, more fundamental concepts.

For instance, rather than using a compound term like "Steel Beam 300mm S355", break it down into its constituents:

• Beam (Class) - define the general purpose and function of this element.
• Steel (Class: Material) - define what steel is, regardless if it will be used for a beam or else.
• Height (Property) - with a numeric data type. You can put 300 as an example or have a list of allowed values like: 200, 250, 300, 350.
• Grade (Property) - where the value "S355" could be one of the enumerated allowed values.

This way you (and others) are able to reuse the definitions also in other contexts. The advantage of such an approach is also the reduction of definitions.

Make purpose-specific dictionaries

Don't try to put too much data into one dictionary. Instead, we recommend having multiple data dictionaries with specific content. For example, let's say you want to publish both a classification of building objects and list of common construction materials. It might be easier to split them into separate dictionaries so that people can easily find what they are looking for.

Reuse what already exists

Avoid replicating content from other dictionaries. If you want to use common definitions like 'wall' or 'height', there is a high chance those were already defined by someone else and published in bSDD. Browse the content of bSDD to see if there are already definitions that might be useful in your case. It's a good practice to reuse content by linking it to your dictionary. For example, you can add properties from other dictionaries. Note that some licenses do not allow redistribution or modifications, so pay attention when trying to upload definitions that might already exist.

Of course, it makes sense to publish terms that extend the existing definitions. For example, a Sauna is a more specialised type of Space.

Example: CCI class Sauna is related to a more general term from the IFC dictionary: IfcSpace.

To apply the existing property to your classes, simply define the connection using ClassProperties.

Example: CCI class Sauna is reusing the property Handicap Accessible from the IFC dictionary.

We recommend only reusing content that has a status Active, which indicates that the owner marked it as official and available for use. Content marked as Preview might be deleted or changed at any time, while the activated content will remain in unchanged form in bSDD.

Use hierarchical structuring

Organize data elements hierarchically to reflect relationships and dependencies. This can help in understanding how different pieces of data interact and rely on each other

Example 1:

• Built Element
  • Wall
    • Shear Wall

Example 2:

• Metal
  • Steel
    • Carbon steel
    • Stainless steel

Unique codes

The dictionary Code and Name need to be unique. Avoid using a name that is too generic, and avoid names that conflict with other dictionaries. For example, do not create classes with an 'Ifc' prefix. Choose a code that is recognizable with the dictionary name as it is used to generate the URIs of all the resources, so it should be short and preferably without spaces.

Standardize naming conventions

Choose your naming convention and follow it to enhance clarity. Common options include: "camelCase", "PascalCase", "snake_case", "kebab-case", "SCREAMING_SNAKE_CASE", "Train-Case", "Title Case". We highly recommend using the same naming convention as the IFC standard, which is: "PascalCase" for codes and "Title Case" for names. Avoid "flatcase" and "ALLUPPERCASE" as it is difficult to distinguish individual words.

Avoid pre-/suffixes:

If you work with a flat list of terms, it might be tempting to give them prefixes to indicate their type or origin (for example: "XYZ_Height"). However, this information doesn't add value and only makes this definition less universal. We recommend avoiding prefixes and suffixes in the names of classes and properties.

Property set names

The 'Pset_' prefix is only allowed for the official IFC dictionary.

Provide enough information

bSDD has only a few required and many optional attributes that you can fill with your content. You can read the full list here. We recommend providing at least:

• for Dictionary:
  • Dictionary license - to tell others what they can do with your content. For example, IFC uses CC BY-ND 4.0.
  • Change Request Email Address - to inform users how they can contact you if they have feedback.
• for Classes and Properties:
  • Code and Name - those two are required for all classes and properties. While both can be exactly the same, it is worth remembering that Code is what will be stored in IFC files, and Name is the more user-friendly label that can be translated into various languages.
  • Definition - explaining the semantic meaning of your term. This way, you explain what you have in mind when you use the Code/Name above. Highly important if you want others to reuse your terms.
• for Classes only:
  • ParentClassCode - to define hierarchy of terms within your dictionary.
  • RelatedIfcEntityNamesList - link to IFC entities to tell how your class should be represented in IFC model.
• for Property only:
  • DataType - if it's a text, number or else
  • Units
  • Example

Be cautious when using those fields

• Description - it is only for supplementary explanation in cases where the Definition field contains an official text from a standard, and you want to provide more information.
• DeActivationDateUtc—This field should be populated by the bSDD itself on the dictionary level, not per individual item.
• (Class/Property) Status—This field should inherit from the dictionary level and not differ between individual items.
• (Class/Property) VersionNumber—This field should inherit from the dictionary level and not differ between individual items.
• VisualRepresentationUri - bSDD doesn't host images, so make sure this URI points to a resource that will remain available.
• (Property) ConnectedPropertyCodes - ISO feature that is rarely supported by software.
• (Property) Dimension - there are two ways to provide information about dimension - read the documentation first.
• (Property) IsDynamic - ISO feature that is rarely supported by software.
• OwnedUri - in case you are trying to mirror existing classification/ontology in bSDD, and there is already a platform that generates URI for each term, you can provide them via this field. This way, bSDD will not generate a unique URI for each term, and some functionality might become unusable.
• (Property) TextFormat
• (Class:Material) Fraction

Upload all at once

The way bSDD works, you cannot upload the content in parts. All classes and properties of one dictionary must be uploaded in one file. You can always upload a sample and add more later, as long as you keep the status as "Preview" or keep track of changing the dictionary version each time.

The only exception is translations, as those are uploaded as a separate file.