DOCSEARCHbyAlgolia
Submit Docs

buildingSMART Data Dictionary (bSDD)

repository·master·Indexed 41 days ago

https://github.com/buildingsmart/bsdd

An online service providing a canonical database for classifications, properties, and units to ensure data consistency in BIM workflows. It features REST and GraphQL APIs, a JSON import model for content providers, and tools for converting Excel dictionaries to JSON. The service includes a production environment and a dedicated TEST environment for developers to validate new features.

Tokens
22.2K
Snippets
32
Records
100
Agent score
52%

What's inside bSDD

  1. Overview of the buildingSMART Data Dictionary (bSDD)

    master

    The buildingSMART Data Dictionary (bSDD) is an online service for hosting data dictionaries. It stores classifications, properties, allowed values, units, and translations in a canonical database to improve data quality and information consistency in BIM (Building Information Modeling) workflows.

    Users can interact with bSDD through several interfaces:

    • APIs: The primary way for BIM software and applications to access data.
    • bSDD Search page: For manual lookup of dictionary content.
    • bSDD Manage portal: For authors to publish and manage content.
    • API: For automated content publishing.

  2. Overview of bSDD verification procedures

    master

    The buildingSMART Data Dictionary (bSDD) content undergoes several types of verification to ensure quality and trustworthiness. Depending on your role (Data Dictionary owner or user), different procedures apply:

    • Organisation review: Performed by the bSI team upon registration to ensure organizational objectives align with bSDD's mission (Free).
    • Import validation: An automated step triggered on every upload to verify compliance with the bSDD data structure (Free).
    • User/reactive review: Users can file 'change requests' to report problems or propose improvements (per ISO 12006-3:2022). The bSI team also investigates license violations (Free).
    • Detailed verification: An on-demand, paid service requested by the owner to obtain a 'verified badge'. This increases data trustworthiness by ensuring compliance with a specific quality checklist. The cost varies based on content volume, complexity, and iterations.

  3. Understand the bSDD Data Model

    master

    The buildingSMART Data Dictionary (bSDD) is a service for distributing data dictionaries published by independent organizations. The data model is centered around the Dictionary concept, which acts as a container for Classes and Properties.

    Key relationships include:

    • A Dictionary consists of multiple Classes and Properties.
    • Classes and Properties can be related to each other or to other Dictionaries.
    • Classes represent objects (e.g., "wall"), abstract concepts (e.g., "room"), or processes (e.g., "installation").

  4. Note on bSDD API name changes (Legacy Migration)

    master

    As of the 2023-11-08 update, several core terms were renamed across all APIs (in names, input contracts, and output contracts). While old APIs remain supported for at least 6 months after a change, it is highly recommended to migrate to the new naming conventions:

    Old TermNew Term
    ClassificationClass
    DomainDictionary
    NamespaceUriUri
    IncludeChildsIncludeChildren

    Key structural changes resulting from these updates:

    • Materials: No longer treated as a separate entity; they are now Class objects with a type of Material.
    • Pagination: Most Search and Dictionary APIs now support pagination.

  5. How to deliver multi-language data

    master

    To provide data in multiple languages, you should use a separate JSON file for each language.

    When creating a file for an additional language:

    1. Ensure OrganizationCode, DictionaryCode, and DictionaryVersion are exactly the same as the primary language file.
    2. Set LanguageOnly to true.
    3. Fill in all fields marked as Translatable? = "Yes" in the schema.
    4. Ensure all Code fields are populated.

  6. Use bSDD in openBIM workflows

    master

    The buildingSMART Data Dictionary (bSDD) serves several key roles in openBIM workflows to enhance model quality and standardization:

    • Model Enrichment: Access various standards to add semantic depth to an openBIM model.
    • Compliance Checking: Validate model data against established standards.
    • IDS Integration: Provide standardized concepts for Information Delivery Specifications (IDS).
    • IFC Extension: Use bSDD to extend the capabilities of the IFC standard.

  7. Assembling and grouping properties

    master

    There are three ways to group or connect properties depending on your goal:

    1. Groups of Properties (Organization)

    Use: Class.ClassType:GroupOfProperties Used to organize multiple properties into a logical collection within a dictionary (e.g., grouping all 'Global Warming Potential' properties together).

    2. Property Sets (IFC Serialization)

    Use: ClassProperty.PropertySet Used to define which IFC Property Set a ClassProperty belongs to when serialized to IFC data.

    • Note: A property can belong to multiple Groups of Properties, but a ClassProperty can only belong to one Property Set.
    • The prefix Pset_ is reserved for official IFC.

    3. Connected Properties (Dependencies)

    Use: Property.ConnectedPropertyCodes Used when the value of one property depends on another (e.g., a 'GWP' value that is only meaningful when paired with a 'PHASE' property).

    ⚠️ Caution: This feature is rarely supported by software implementations and is not supported by IFC for multiple properties with the same name in one set. Use sparingly.

  9. Defining relations between classes and properties

    master

    You can link concepts in bSDD using several attributes and relation types:

    Hierarchy and IFC Relations

    • ParentClassCode: Used to create a tree-like hierarchy within a dictionary (e.g., defining IfcPile as a child of IfcDeepFoundation).
    • ClassRelation and PropertyRelation: Used to link concepts across different dictionaries or define non-specialization relations like decomposition (HasPart).
    • RelatedIfcEntityNamesList: Specifically for relating a class to IFC entities (e.g., relating a custom 'Signalling LED diode' to IfcLamp). This helps tools filter classes by IFC category.

    Relation Types

    Relations must have a specific type for software interpretation:

    • IsEqualTo: Concepts are identical in name, code, definition, description, and class properties. Rare usage.
    • IsSimilarTo: Concepts are almost equal but differ in some attributes (e.g., 'IfcWall' vs 'Wall System').
    • HasReference: One concept references another without a hierarchy (e.g., a 'wall lamp' referencing a 'wall').
    • Deprecated: IsSynonymOf (use IsSimilarTo instead).

    Class-only Relations

    • IsChildOf: Specialization/subtype relationship.
    • IsParentOf: The inverse of IsChildOf.
    • HasPart: Composition relationship (e.g., a motor has a stator).
    • IsPartOf: The inverse of HasPart.
    • HasMaterial: Associates a class with a specific material (e.g., 'Steel Beam' relates to 'Steel').

  11. Understand the bSDD API workflow

    master

    The bSDD API allows developers to retrieve Class and Property information from various dictionaries (e.g., IFC, ETIM). A typical integration follows this sequence:

    1. Retrieve Dictionaries: Call the Dictionary method to get a list of available standards.
    2. Search Classes: The user selects a dictionary and enters search text; the app calls the SearchList method to return a list of matching Class objects.
    3. Get Details: Once a user selects a specific class, the app calls the Class method to retrieve full details and associated Properties.

    Note: The API is regularly updated. Breaking changes trigger a new version, and both the old and new versions are supported for 6 months.

  12. Define physical dimensions for quantities

    master

    For properties representing physical quantities, you can specify dimensions using the Dimension field or individual dimension fields.

    Using the Dimension field: Specify dimensions according to the International System of Quantities (ISO 80000-1). The order of values must be:

    1. length
    2. mass
    3. time
    4. electric current
    5. thermodynamic temperature
    6. amount of substance
    7. luminous intensity

    Example: Speed (m/s) is denoted as "1 0 -1 0 0 0 0".

    Using individual fields: Alternatively, you can specify parts separately using:

    • DimensionLength (Integer)
    • DimensionMass (Integer)
    • DimensionTime (Integer)
    • DimensionElectricCurrent (Integer)
    • DimensionThermodynamicTemperature (Integer)
    • DimensionAmountOfSubstance (Integer)
    • DimensionLuminousIntensity (Integer)