Semantic bSDD
Improving the GraphQL, JSON and RDF Representations of buildingSmart Data Dictionary

We used this query but then removed uninteresting RDF classes:

select ?type (count(*) as ?c) {
  ?x a ?type
} group by ?type order by desc(?c)

The GraphQL API returns 108 Domains. The distribution of number of Classifications per domain is as follows:

Domains with no classifications:

http://identifier.buildingsmart.org/uri/spr/spr-cfhios-0.1
https://identifier.buildingsmart.org/uri/ArcDox/ArcDox-1.0
https://identifier.buildingsmart.org/uri/BBRI/BBRI-0.1
https://identifier.buildingsmart.org/uri/FCSI/keq-0.1
https://identifier.buildingsmart.org/uri/MTR/MTR-1
https://identifier.buildingsmart.org/uri/bimeta/bimeta-0.1
https://identifier.buildingsmart.org/uri/bimlib/bimlib-ru-temp-1
https://identifier.buildingsmart.org/uri/buildingsmart/demo-2-1.1
https://identifier.buildingsmart.org/uri/csi/omniclass-1
https://identifier.buildingsmart.org/uri/ethz/hosszu-0.1
https://identifier.buildingsmart.org/uri/growingcircle/transsmart-0.1
https://identifier.buildingsmart.org/uri/ifcrail/ifcrail-0.1

One domain has more than 5000 classifications, but returns only 5000 due to lack of pagination in the GraphQL API:

https://identifier.buildingsmart.org/uri/nbs/uniclass2015-1

This shows the total number of defined fields, and fields that are actually used in various entities.

This shows the percentage of use of fields in Classification. It ignores null values like "" and "[]".

prefix bsdd: <http://bsdd.buildingsmart.org/def#>
select ?field (count(?field) as ?c)
where {
  ?cla a bsdd:Classification; ?field ?value .
  filter (?field != rdf:type && ?value != "" && ?value !="[]")
} group by ?field order by ?field

This shows the percentage of use of fields in ClassificationProperty.

PREFIX bsdd: <http://bsdd.buildingsmart.org/def#>
select  ?field (count(?field) as ?c)
where {
  ?prop a bsdd:ClassificationProperty; ?field ?value .
  filter (?field != rdf:type && ?value != "" && ?value !="[]")
} group by ?field order by ?field

Note: allowedValue is a multivalued property, so it is counted separately like this:

select (count(*) as ?c) {
  ?prop a bsdd:ClassificationProperty
  filter exists {?prop bsdd:allowedValue []}
} group by ?field order by ?field

This shows the percentage of use of fields in Property.

PREFIX bsdd: <http://bsdd.buildingsmart.org/def#>
select  ?field (count(?field) as ?c)
where {
  ?prop a bsdd:Property.
  ?prop ?field ?value .
  filter (?field != rdf:type && ?value != "" && ?value !="[]")
} group by ?field order by ?field

This shows the percentage of use of fields in PropertyValue (allowedValues). Note: we have merged the classes PropertyValue and ClassificationPropertyValue into one, because they have exactly the same structure.

PREFIX bsdd: <http://bsdd.buildingsmart.org/def#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
select ?field (count(?field) as ?c) {
  ?prop a bsdd:PropertyValue; ?field ?value
  filter (?field != rdf:type && ?value != "" && ?value !="[]")
} group by ?field order by ?field

In most PropertyValues, code=value and namespaceUri is not filled. But there are some exceptions, and we should improve our RDF refactoring logic to take care of that, as described in the table comments above. For example:

• namespaceUri https://identifier.buildingsmart.org/uri/FTIA/FTIAtie-1.0/prop/verkon-toiminnallinen-kayttotarkoitus/value/vtk01
• Has code "vtk01" and value "Pituushalkeamien ehkäisy"
• We made https://identifier.buildingsmart.org/uri/FTIA/FTIAtie-1.0/prop/verkon-toiminnallinen-kayttotarkoitus/Pituushalkeamien ehkäisy which is invalid URL because it includes a space
• Instead, we should have made URL from code, or use namespaceUri directly

select ?type (count(*) as ?c)  {
  ?x bsdd:classificationType ?type
} group by ?type order by ?type

Classification is a fairly generic entity, which can designate:

• CLASS: e.g. a building component, assembly, concept, etc
• MATERIAL: a building material
• COMPOSED_PROPERTY: a set of properties (we examine one such example below)

However, the other values in the table above cannot be justified:

• DOMAIN: there is a specific entity Domain, so Classification should not have such type
• REFERENCE_DOCUMENT: Classification has such a field, and there's a specific entity ReferenceDocument, so Classification should not have such type

We have listed all possible values in the table, and two of them are not used:

select ?value (count(?value) as ?c) {
  ?prop a bsdd:ClassificationProperty.
  ?prop bsdd:propertyValueKind ?value .
} group by ?value order by ?value

We have listed all possible values in the table, and two of them are not used:

select ?value (count(?value) as ?c) {
  ?prop a bsdd:Property.
  ?prop bsdd:propertyValueKind ?value .
} group by ?value order by ?value

Breakdown of main entities by status.

• Despite the endpoint being listed as "test", most objects are "Active"
• We also noticed that some Domains lack any value!

We used this query, but then changed the table to 2-dimensional:

select ?type ?status (count(*) as ?c) {
  ?x a ?type; bsdd:status ?status
} group by ?type ?status order by ?type ?status

Dynamic properties are interesting because they are calculated from other properties:

select (count(*) as ?c) ?isDynamic where {
  ?d bsdd:isDynamic ?isDynamic
} group by ?type order by desc(?c)

According to the above, nearly 10% of properties are dynamic. However, dynamicParameterPropertyCodes is always empty, so there is no indication from which properties those would be calculated.

isWritable specifies whether the Property can be edited. Most Properties don't have such a characteristic. Unless the default is false, this characteristic is badly under-specified.

We used this query, but then made a 2-dimensional table:

select ?type ?isWritable (count(*) as ?c) {
  values ?type {bsdd:Property bsdd:ClassificationProperty}
  ?x a ?type.
  optional {?x bsdd:isWritable ?isWritable1}
  bind(coalesce(?isWritable1,"UNDEF") as ?isWritable)
} group by ?type ?isWritable order by ?type ?isWritable

isRequired specifies whether the Property must be present in an object of the respective Classification. Similar to the previous section, most Properties don't have such a characteristic. Maybe here false is a suitable default.

We used this query, but then made a 2-dimensional table:

select ?type ?isRequired (count(*) as ?c) {
  values ?type {bsdd:Property bsdd:ClassificationProperty}
  ?x a ?type.
  optional {?x bsdd:isRequired ?isRequired1}
  bind(coalesce(?isRequired1,"UNDEF") as ?isRequired)
} group by ?type ?isRequired order by ?type ?isRequired

Let's find all domains that have isWritable and isRequired Properties, and count such properties:

select ?domain ?domainName (count(*) as ?c) {
  ?domain a bsdd:Domain; bsdd:name ?domainName; bsdd:classification ?cla.
  ?cla bsdd:classificationProperty ?prop.
  ?prop bsdd:isRequired true; bsdd:isWritable ?true
} group by ?domain ?domainName order by ?domainName

As you can see, the vast majority of isWritable and isRequired Properties are in this Domain:

• https://identifier.buildingsmart.org/uri/bimeta/bimeta-1.0 "Bauteiltypen nach DIN 276+x (geprüft)". For example class "421.43 - Abgaswärmetauscher" has property "Hersteller" that isWritable and isRequired.
• The rest are 6 test domains, and LCC_RG, Ponti_ClassificazioneDegrado, Uniweimar

bSDD includes multiple versions of some domains. For example, here are all ACCAtest domain versions:

This was obtained with this SPARQL query:

PREFIX bsdd: <http://bsdd.buildingsmart.org/def#>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
select * {
  ?dom bsdd:version ?ver
  filter(contains(str(?dom),"ACCAtest"))
} order by xsd:decimal(?ver)

We have seen no guidance on how version numbers should be formatted.

• If they are decimal number, they should be recorded with type xsd:decimal so they can be compared and sorted (we cast them to that datatype in the query above)
• But if they can have more decimal components (e.g. 1.0.1) then they should not be recorded as xsd:decimal

We believe it is worth explicating versions:

• Either as Domain relations such as previousVersion, nextVersion
• Or as a new entity DomainVersion, to allow linking all versions of a domain to its master Domain entity

The GraphQL specification sec 3.5.5 ID states: "The ID scalar type represents a unique identifier, often used to re-fetch an object or as the key for a cache." This data type is similar to String, but is specifically used for identifiers.

Furthermore, the Global Object Identification Guide for GraphQL recommends that all objects should have a field id that returns non-null ID! (through the Node interface). The id should be a "globally unique identifier" for the object, and given just this id, the server should be able to re-fetch that object.

• Most GraphQL implementations call this field simply id, whereas bSDD uses unwieldy property names like namespaceUri.
• Many nodes do not have their own namespaceUri field, or it is not fully populated

The key field classificationType specifies the kind of classification. Let's do a count:

PREFIX bsdd: <http://bsdd.buildingsmart.org/def#>
select (count(*) as ?c) ?type where {
  ?d bsdd:classificationType ?type
} group by ?type order by desc(?c)

Here are the results, and we see that some classificationType overlap with predefined entity types:

We can examine some of these unusual classifications with this query:

PREFIX bsdd: <http://bsdd.buildingsmart.org/def#>
select ?x ?name ?type {
  ?x a bsdd:Classification; bsdd:classificationType ?type; bsdd:name ?name
  filter(?type not in ("CLASS", "MATERIAL"))
}

Examples of unusual classifications:

• https://identifier.buildingsmart.org/uri/ATALANE/REX-OBJ-1.0/class/589b06ad-f802-468b-939c-e60436601a7a is a "REFERENCE_DOCUMENT" with name "décret 2011-321 (23/03/2011)". Why is it not a ReferenceDocument entity?
• https://identifier.buildingsmart.org/uri/acca/AASHTO-1.0/class/06 is a "DOMAIN" with name "Bridge Superstructure". This reflects the hierarchical nature of the AASHTO-1.0 classification, which we can see clearly with the following query. But bSDD accommodates classification hierarchies, so why "Bridge Superstructure" is "DOMAIN" and not "CLASS"?

PREFIX bsdd: <http://bsdd.buildingsmart.org/def#>
select ?code ?name ?type where {
  ?x a bsdd:Classification; bsdd:name ?name; bsdd:code ?code; bsdd:classificationType ?type.
  filter(strstarts(str(?x),"https://identifier.buildingsmart.org/uri/acca/AASHTO-1.0/class/06"))
} order by ?code

We can posit (guess) two reasons for this structural problem:

• The bSDD data model does not provide a way to model sub-domains or attach reference documents to specific domains
• Some bSDD data contributors use Classification as a "dump" of all kinds of data, not just single entities

Property and ClassificationProperty are two different classes, but the latter does not have a distinct URL in GraphQL and JSON. The same URL is overloaded to identify entities of both classes. ClassificationProperty are thus "second class" entities and are not returned separately by the JSON or RDF entity API, but only as part of the respective Classification:

curl https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegmentCABLESEGMENT/ACResistance
{"":["Classification with namespace URI
 'https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegmentCABLESEGMENT/ACResistance'
  not found"]}

ClassificationProperty is identified only in RDF since this format forces one to use different identities for different nodes:

<https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegmentCABLESEGMENT/ACResistance>
  bsdd:ClassificationProperty <https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegmentCABLESEGMENT>;
  bsdd:PropertyDomainName "IFC";
  bsdd:PropertyNamespaceUri "https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/prop/ACResistance".

Following the thinking of the previous section, all significant classes should have an ID, (which in the case of RDF data is the node URL).

However, many bSDD classes don't have such a field:

• Domain, Property, Classification do have namespaceUri
• Country, Language, Unit don't have an ID but have a field (code, isocode) that can be used to make an ID, when prepended with an appropriate prefix. However, Unit.code is not always fit to be used in a URL
• ClassificationProperty doesn't have an ID in GraphQL. We follow the bSDD RDF representation and assign a URL from the URL of the owning object (Classification) and its own propertyCode:

Classification.namespaceUri+"/"+propertyCode

• PropertyValue, ClassificationPropertyValue have namespaceUri but it's optional and is rarely filled. We assign URLs similarly to the previous case: from the URL of the owning object and its value:

Property.namespaceUri+"/"+value OR
ClassificationProperty.namespaceUri+"/"+value

• The following classes have no fields suitable to make a URL, so they remain blank nodes:
  • ReferenceDocument: only name, title, date
  • ClassificationRelation: a pair of related Classifications, no own URL
  • PropertyRelation: a pair of related Properties, no own URL

For example, the classification shown below has ClassificationProperties with no propertyCode

"namespaceUri": "https://identifier.buildingsmart.org/uri/uniweimar/uniweimar-0.1/class/Nondestructive",
"properties": [
  {
    "description": "Identifier of the tested structure",
    "isRequired": true,
    "isWritable": true,
    "predefinedValue": null,
    "propertySet": "Single",
    "__typename": "ClassificationProperty"
  }...]

The bSDD data model allows the modeling of complex properties that are composed of other properties: The key attribute propertyValueKind has values COMPLEX and COMPLEX_LIST used in combination with connectedProperties.

• These key values are defined for Property and ClassificationProperty
• However, connectedPropertyCodes is defined only for Property
• More importantly, these key values are never used

connectedProperty is used only on seven Properties (and not ClassificationProperties):

select ?prop (group_concat(?code) as ?connectedPropCodes) where {
  ?prop  bsdd:connectedPropertyCode ?code
} group by ?prop

The meaning of connectedPropertyCodes is not defined:

• Is it a symmetric/equivalence relation between properties?
• Or is it used to point from a "master" property to its "subsidiary properties"?

The examples don't clarify this question.

Instead of using connectedPropertyCode to describe complex properties, some people have used classifications with the type "COMPOSED_PROPERTY". One such example is https://identifier.buildingsmart.org/uri/buildingsmart-fr/BRIDGE-MINnD-1.0/class/609952491 with name "Pile location" and definition "Gather properties to locate a pile". We can see the properties comprising this "COMPOSED_PROPERTY" by using the link Classification.classificationProperty:

PREFIX bsdd: <http://bsdd.buildingsmart.org/def#>
select ?type ?code ?name ?def {
  bind(<https://identifier.buildingsmart.org/uri/buildingsmart-fr/BRIDGE-MINnD-1.0/class/609952491> as ?class)
  {bind(?class as ?x)} union {?class bsdd:classificationProperty ?x}
  ?x a ?type; bsdd:code ?code; bsdd:name ?name
  optional {?x bsdd:definition ?def}
}

12385 Properties are declared as isDynamic (135250 are not). However, the field dynamicParameterPropertyCode (used to compute the dynamic property) is always empty, so how can one know which "sub-properties" to use?

select * {
  ?prop bsdd:isDynamic true.
  optional {?prop bsdd:dynamicParameterPropertyCode ?dyn}
} order by desc(?dyn)

Additionally, dynamicParameterPropertyCodes is String, but should be [Property], i.e. an array of Properties .

bSDD includes numerous string attributes (codes or URLs) that should be converted to relations (object fields) to improve the connectedness of the bSDD GraphQL graph.

• ClassificationRelation and PropertyRelation do not have any outgoing relations. Instead, they use strings (e.g. relatedPropertyUri), thus blocking further GraphQL navigation.
• There are several entities (Country, Language, ReferenceDocument, Unit) that are not used anywhere. Instead of relations pointing to these types, the other types have properties (e.g. countryOfOrigin, countriesOfUse) representing the same information as String.

Problems related to this approach:

• One cannot easily navigate in the GraphQL graph. e.g. to find the country name for countriesOfUse: ["BG"], one needs to make a second query, get all countries, and look for that code.
• It represents data denormalization that creates opportunities for data inconsistency or redundancy, e.g. if countriesOfUse includes a code "XX" not defined in Country, is that a mistake, or is Country just an advisory table?

Here is a list of all strings that are candidates to be converted to object properties (relations). [Foo] indicates an array (multivalued property):

• connectedPropertyCodes: should become [Property]
• countriesOfUse: should become [Country]
• countryOfOrigin: should become Country
• creatorLanguagecode: should become Language
• documentReference: unclear whether it should be a URL, a bibliographic reference, a title, or some other free text. Should become ReferenceDocument
• dynamicParameterPropertyCodes: should become [Property]
• example "Illustrate possible use or values of the Property": could become PropertyValue if it's used consistently to show an example value (not a free text)
• languageCode: should become Language
• physicalQuantity: could become a separate entity, since it governs what possible units are allowed. See detailed analysis of units later on
• predefinedValue: should become PropertyValue. Actually this is a more difficult point because a predefined value could be a number thus not represented as PropertyValue.
• propertySet: should be made an entity, it's too important to be a mere string
• relatedClassificationUri: should become Classification (in our refactoring, we rename it to simply related to use the same name for both kinds of relation)
• relatedIfcEntityNames: since IFC is present as a bSDD Domain, should become a relation to the respective IFC Classification.
• relatedPropertyUri: should become Property (in our refactoring, we rename it to simply related to use the same name for both kinds of relation)
• replacedObjectCodes, replacingObjectCodes: should become some kind of object. But because the field is never filled, we cannot tell what kind of objects
• subdivisionsOfUse: should be made an entity and become [CountrySubdivision]: Just like the entity Country should be used as a lookup table for countriesOfUse. Furthermore, subdivisions are subjugated to countries, so each CountrySubdivision must have a relation to its parent Country
• units: should become [Unit]

Summarizing findings from previous sections, we recommend creating the following as additional first-class entities:

• CountrySubdivision: as lookup for subdivisionsOfUse, subjugated to Country
• DomainVersion: to explicitly relate domain versions to each other, and to a master Domain entity
• PhysicalQuantity: to govern allowed Units, and to be subjugated to the dimension* fields
• PropertySet: important concept in both IFC and bSDD

The following types are very similar, and most of their fields are duplicated between them, with no modularity or inheritance:

• PropertyValue and ClassificationPropertyValue: in fact are the same. These are "value objects" (simple immutable objects), so there's no need to have two different types.
• Property and ClassificationProperty. They differ by only 5 fields:
  • connectedPropertyCodes (String) and relations (PropertyRelation) belong uniquely to Property
  • isRequired (Boolean), isWritable (Boolean), predefinedValue (String), propertySet (String) and symbol (String) below uniquely to ClassificationProperty.

Property is a general property definition, while ClassificationProperty is a property modified locally to a Classification. But since there are no rules on which fields of Property to reuse in ClassificationProperty, the latter type copies most of the fields from the former.

For example, the property https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/prop/HandicapAccessible "Indication that this object is designed to be accessible by the handicapped" is used for all kinds of spaces, as indicated by its propertySet "Pset_SpaceCommon". There are over 300 Classification Properties that use the indicated property:

PREFIX bsdd: <http://bsdd.buildingsmart.org/def#>
select ?propName ?class ?className ?classPropName where {
  bind(<https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/prop/HandicapAccessible> as ?prop)
  ?prop bsdd:name ?propName.
  ?classProp bsdd:property ?prop; bsdd:name ?classPropName.
  ?class bsdd:classificationProperty ?classProp; bsdd:name ?className
} order by ?className

Note: a lot of these are duplicated between the two domains acca/ACCAtest-0.1, molio/cciconstruction-1.0, eg:

• https://identifier.buildingsmart.org/uri/acca/ACCAtest-0.1/class/A-FAA vs
• https://identifier.buildingsmart.org/uri/molio/cciconstruction-1.0/class/A-FAA

The problem is that all these ClassificationProperties copy the same field values from the Property, over and over again:

PREFIX bsdd: <http://bsdd.buildingsmart.org/def#>
select ?className ?classPropName ?field ?value1 ?value2 where {
  bind(<https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/prop/HandicapAccessible> as ?prop)
  ?classProp bsdd:property ?prop; bsdd:name ?classPropName.
  ?class bsdd:classificationProperty ?classProp; bsdd:name ?className.
  ?prop ?field ?value1.
  ?classProp ?field ?value2.
  filter(?field not in (rdf:type))
  filter(?value1 != ?value2)
}

We also investigated the same problems across all props. We ended up with a lot more complicated query:

PREFIX bsdd: <http://bsdd.buildingsmart.org/def#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
select ?className ?classPropName ?field ?value1 ?value2 where {
  ?classProp bsdd:property ?prop; bsdd:name ?classPropName.
  ?class bsdd:classificationProperty ?classProp; bsdd:name ?className.
  optional {?prop ?field ?val1}
  optional {?classProp ?field ?val2}
  filter(?field not in (rdf:type, bsdd:allowedValue, bsdd:connectedPropertyCode,
                        bsdd:countryOfUse, bsdd:name, bsdd:description, bsdd:textFormat))
  bind(replace(str(?val1),"[ \\n\\t]*(.*?)[ \\n\\t]*","$1") as ?value1)
  bind(replace(str(?val2),"[ \\n\\t]*(.*?)[ \\n\\t]*","$1") as ?value2)
  filter(!bound(?value1) || !bound(?value2) || ?value1 != ?value2)
}

It does the following:

• Allows for differences of optional fields, i.e. present in Property but missing in ClassificationProperty or vice versa
• Trims leading and trailing whitespace from field values (see next section)
• Ignores rdf:type because it's naturally different (bsdd:Property vs bsdd:ClassificationProperty)
• Ignores bsdd:name, bsdd:description because minor variations are often present. Example for bsdd:name are: "Inhalt(Menge)jeBestelleinheit" vs "Inhalt_(Menge)_je_Bestelleinheit"
• Ignores bsdd:allowedValue, bsdd:connectedPropertyCode, bsdd:countryOfUse because these multi-valued fields are not so easy to compare (separate queries would be needed for this)
• Ignores bsdd:textFormat because we saw only invalid values, such as "" and "F.001"

Valid changes include:

• min/maxInclusive/Exclusive: e.g. "Height" is defined to have a valid range 0..5000, but in the class "Apple" it's restricted to 1..25. However, we have seen this only in sample domains.
• unit, e.g. from "m" to "mm" or "cm." Ideally, this should happen if the physicalQuantity and dimension are preserved but it is often not the case:
  • "Pitting": "Profondità in media": unit "²" vs "mm" (which is invalid).
  • "Pitting": "Entità del fenomeno (sup)": unit "m" vs "m²". It seems there is an uncertainty how surface defects (pitting, erosion, patina) should be measured: as length/diameter or as area.

Perhaps because there is no clearly defined distinction between global properties (Property) and local properties (ClassificationProperty), and there are no rules on what fields they can inherit from one to the other, several local properties lack adequate descriptions. For example, let's look at the local property Status in classification IfcAirTerminalBox:

"name": "Status",
"description": "The status currently assigned to the permit.",
"propertyCode": "Status",
"propertyNamespaceUri": "https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/prop/Status",
"propertySet": "Pset_AirTerminalBoxTypeCommon",

The local definition refers to an appropriate propertySet Pset_AirTerminalBoxTypeCommon, but the description is not suitable to that classification (an "AirTerminalBox" is not a "permit"!).

PropertyValue and ClassificationPropertyValue are structured values with rich fields: code, value, namespaceUri, description, sortNumber. These fields allow:

• Unique identification of values through namespaceUri
• Potentially multilingual translations in the future (if value, description are made multivalued and attached a language tag)
• The logical ordering of values through sortNumber (as opposed to alphabetical ordering)

However, most structured values we've seen have only code, value

For example, consider this property:

curl https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/prop/ArrangementType

Its description includes not just a property description, but is followed by descriptions of values (newline-separated):

      "name": "ArrangementType",
      "description": "Terminal box arrangement.\n\
SingleDuct: Terminal box receives warm or cold air from a single air supply duct.\n\
DualDuct: Terminal box receives warm and cold air from separate air supply ducts.",

The same property when used in classification IfcAirTerminalBox has values described like this:

select * {
  <https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcAirTerminalBox/ArrangementType> bsdd:allowedValue ?val.
  ?val bsdd:code ?code;
       # bsdd:value ?value # same as "code"
} order by ?code

This has multiple problems:

• Individual values have no description (description is not filled out)
• Some values are described in the property definition, intermingling multiple descriptions together
• The "standard" values NOTKNOWN, OTHER, UNSET are not described at all.
• Values have no namespaceUri, precluding unique identification.

allowedValues (and its deprecated variant possibleValues) store structured values (ClassificationPropertyValue). However, their "sibling" property predefinedValue holds a mere string and not a structured value, which means that even in the future, predefinedValue cannot be an enumeration value identified globally with a URL. We could think of two possible reasons for this discrepancy:

• predefinedValue needs to hold not just enumeration values but also Real, String, Boolean, etc. Then it should be structured as a variant and not be cast down to String.
• It may be related to the poor description of PropertyValue

RDF is well suited to carry multilingual data because:

• Any property can carry multiple values
• rdf:langString literals are self-describing by carrying a lang tag (e.g. "wall"@en vs "wand"@de)

For example, the ClassificatonProperty apple/volume is represented like this in RDF:

<https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple/volume>
  bsdd:Description "The volume of an apple"@pl-pl;
  bsdd:Example "For example, the space that a substance or 3D shape occupies or contains."@pl-pl;
  bsdd:Name "Objętość"@pl-pl;
  bsdd:PhysicalQuantity "Volume"@pl-pl;
  bsdd:PropertyDomainName "Fruit and vegetables";
  bsdd:DataType "Real";
  bsdd:PropertyCode "volume";

Notes:

• Some of the values are correctly unilingual and shouldn't be translated because they are identifiers (DataType, PropertyCode)
• Other values are not translated, so their lang tag is misleading (Description, Example).
• PropertyDomainName is in fact redundant because there are links ClassificatonProperty-Classificaton-Domain, so it should be removed.

But there's no lang tag information in JSON:

"description": "The volume of an apple",
"name": "Objętość",

Currently bSDD assumes that a domain and all its sub-objects will be translated fully to multiple languages. (Translatable fields are specified in the buildingSMART Data Dictionary model). That's why it doesn't bother to store the lang tag of individual strings individually. As you can see in the Turtle example above, that leads to incorrect and misleading lang tags (e.g. "The volume of an apple"@pl-pl is in English not Polish).

From our experience with large thesauri, the assumption that everything will be translated is unrealistic. For example, the Getty AAT (a major thesaurus in Cultural Heritage) had 109 languages as of Nov 2016, but only 4 that cover all 40k concepts, and only 9 that have more than 1k labels (see Count_Terms_by_Language).

Such an assumption makes it harder to deploy a translation: it has to be 100% translated before it can be deployed. It is better to allow a mix of languages to be stored, and let the user pick desired language(s) by preference. This can be done by:

• Allowing translatable fields like name and description to carry multiple values
• Ensuring that translatable strings in the payload indicate their language tag (be self-describing)
• Having "language fallback" logic. For example, Ontotext Platform Semantic Objects include comprehensive facilities for selecting labels per language, including language fallback. For example, the following GraphQL query will fetch only one name value, preferring Polish, then English, then German:

classification {
  code
  name(lang:"pl,en,de")
}

According to basic principles of the Web Architecture, URIs (or their better sibling: resolvable URLs) are identifiers of resources (information resources or real-world things), so they shouldn’t reflect implementation or representation details. This is further elaborated in the blogs Cool URIs for the Semantic Web and Cool URIs don't change. When fetching an entity, it is preferred to use a constant URL, and specify representation details with HTTP headers. This happens through a process of Content negotiation using standard headers (see List of HTTP header fields).

• The client uses Accept for desired MIME type and Accept-Language for a list of preferred languages
• The server uses Content-Type to indicate the returned MIME type, and Language to indicate the language

For example, to fetch the classification "apple" in Polish (or English, or German) in Turtle, one should be able to use:

curl -L -Haccept-language:pl,en,de -Haccept:text/turtle \
  https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple

And to fetch it in English (or German) in JSON, one should be able to use:

curl -L -Haccept-language:en,de -Haccept:application/json \
  https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.0/class/apple

You will notice that we've used the same ("semantic") URL, and varied only the headers. Contrast this approach to the current one illustrated in sec 4.7.

The Ontotext Platform uses a pseudo "lang tag" BROWSER to indicate where to use the Accept-Language header, see GraphQL Query Tutorial: HTTP Accept-Language.

The current bSDD approach is to always append a region code to the lang tag, e.g. de-DE, de-AT, pl-PL etc (see https://api.bsdd.buildingsmart.org/api/Language/v1). However, RFC 5646: Tags for Identifying Languages specifies:

Region subtags are used to indicate linguistic variations associated with or appropriate to a specific country, territory, or region. Typically, a region subtag is used to indicate variations such as regional dialects or usage, or region-specific spelling conventions.

pl-PL means "Polish as spoken in Poland", but the language spoken there is just Polish, so using the region subtag is not right. Similarly, forcing a difference between de-DE and de-AT will lead to a lot of unnecessary duplication, because Standard Austrian German is mostly identical to the Standard German of Germany, but with some vocabulary differences (see Wikipedia). It's better to use de for the majority of translatable strings, and use de-AT only for specifically Austrian words.

The most important shortcomings of the original GraphQL API are:

• One can search only by very few parameters. The user is limited to very basic fetching of data: all entities of a class, entity by namespaceUri, or basic full-text search (classificationSearch). GraphQL users cannot search e.g. for:
  • Compound properties and their constituents
  • Dynamic properties (although currently none has constituents)
  • Classifications with relations, and their related classifications
  • Properties that are Writable or Required
  • Properties with relations, and their related properties
• No pagination. One cannot get only a portion of the results, and iterate through pages with limit/offset. Due to this limitation, one cannot get more than 5000 classifications per domain.

These shortcomings are not present in our refactored GraphQL endpoint, which includes a comprehensive where query language. You can see some sample queries towards the end.

There are a number of parallel relations (arrows) in the original GraphQL schema.

• Root.{domain,domains}
• Domain.{classification,classificationSearch}
• Classification.{property,properties}
• Property.{allowedValues,possibleValues}: possibleValues is deprecated and should be removed. UPD (19 May 2023): bSI [BROKEN LINK: took our suggestion] and removed deprecated field possibleValues.
• ClassificationProperty.{allowedValues,possibleValues}: same

This is not needed in GraphQL because the schema can use parameters to distinguish between different uses of the same field (e.g. fetch one entity by URL vs search for entities). It's best practice for the relation to be named the same as the target entity. We have eliminated such parallel links from the refactored schema.

A GraphQL schema can declare mandatory/optional status at the level of array and at the level of individual elements:

(As you see, there is no way to enforce a non-empty array in GraphQL.)

bSDD specifies arrays as [Classification], which is the most permissive specification. It means that [null, null, null] is a valid result of a query that returns an array of Classifications. However, such a result is not suitable because null elements are useless. It would be better to use the type [Classification!].

Although classificationSearch is declared as nullable (see previous section), a GraphQL error is returned whenever the backend returns null. Querying all domains with all their classifications:

query getDomainsAndClassifications {
  domains {
    namespaceUri
    classificationSearch {
      namespaceUri
    }
  }
}

Returns such an error:

{
  "errors": [
    {
      "message": "Error trying to resolve field 'classificationSearch'.",
      "locations": [
        {
          "line": 4,
          "column": 5
        }
      ],
      "path": [
        "domains",
        67,
        "classificationSearch"
      ],
      "extensions": {
        "code": "NULL_REFERENCE",
        "codes": [
          "NULL_REFERENCE"
        ]
      }
    }
  ],
  "data": {
    "domains": [
      {
...

Classification.childs is defined as nullable: with type [Classification] However, unless includeChilds: true is provided as input argument in classification, queries return NULL_REFERENCE errors, thus breaking GraphQL spec compliance. E.g. this query:

query getClassificationChildren {
  classification(namespaceUri: "https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcAirTerminalBox",
                 includeChilds: false) {
    namespaceUri
    childs {
      namespaceUri
    }
  }
}

Returns this error:

{
  "errors": [
    {
      "message": "Error trying to resolve field 'childs'.",
      "locations": [
        {
          "line": 4,
          "column": 5
        }
      ],
      "path": [
        "classification",
        "childs"
      ],
      "extensions": {
        "code": "NULL_REFERENCE",
        "codes": [
          "NULL_REFERENCE"
        ]
      }
    }
  ],
  "data": {
    "classification": {
      "namespaceUri": "https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcAirTerminalBox",
      "childs": null
    }
  }
}

Some ClassificationProperties have no name. Although that field is declared nullable, bSDD does not return such properties and instead returns NULL_REFERENCE errors. For example:

query getClassificationProperties {
  classification(namespaceUri: "https://identifier.buildingsmart.org/uri/molio/cciconstruction-1.0/class/L-NAA") {
    name
    properties {
      name
    }
  }
}

This query returns four out of five properties: the 4th property is returned as null, along with an error:

{
  "errors": [
    {
      "message": "Error trying to resolve field 'name'.",
      "locations": [
        {
          "line": 5,
          "column": 7
        }
      ],
      "path": [
        "classification",
        "properties",
        3,
        "name"
      ],
      "extensions": {
        "code": "NULL_REFERENCE",
        "codes": [
          "NULL_REFERENCE"
        ]
      }
    }
  ],
  "data": {
    "classification": {
      "name": "Pane",
      "properties": [
        {
          "name": "FireRating"
        },
        {
          "name": "ThermalTransmittance"
        },
        {
          "name": "GlassLayers"
        },
        null,
        {
          "name": "IsExternal"
        }
      ]
    }
  }
}

The GraphQL root field domains used to return some domains that are not available individually through the field domain, e.g.

{
  domains {
    id: namespaceUri
  }
  domain(namespaceUri: "http://identifier.buildingsmart.org/uri/spr/spr-cfhios-0.1") {
    id: namespaceUri
  }
}

The second response for domain will be null although the domain is present in the domains response. We saw this problem in January 2023, but it's not present in February 2023. Note: cfhios above is misspelled, because the name of that data standard is "CFIHOS".

The attribute propertySet is defined as single (SCALAR), see bsdd-graphql-schema-orig.json:

"name": "propertySet",
"description": "Name of the property set",
"args": [],
"type": {
  "kind": "SCALAR",
  "name": "String",
  "ofType": null
},

But in fact there are 1924 ClassificationProperty where this attribute is multivalued:

PREFIX bsdd: <http://bsdd.buildingsmart.org/def#>
select * where {
  ?classProp bsdd:propertySet ?set1, ?set2
  filter(?set1<?set2)
}

For example:

The original bSDD GraphQL endpoint happily returns such mis-declared values. E.g. this query:

{
  domain(namespaceUri: "https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3") {
    classification(namespaceUri:"https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcElementAssemblySUSPENSIONASSEMBLY") {
      name
      properties{
        name
        propertyValueKind
        propertySet
      }
    }
  }
}

Returns the offending property 3 times, without getting any warning:

{
  "name": "ContactWireStagger",
  "propertyValueKind": "SINGLE",
  "propertySet": "Pset_ElementAssemblyTypeCantilever"
},
{
  "name": "SystemHeight",
  "propertyValueKind": "SINGLE",
  "propertySet": "Pset_ElementAssemblyTypeCantilever"
},
{
  "name": "ContactWireHeight",
  "propertyValueKind": "SINGLE",
  "propertySet": "Pset_ElementAssemblyTypeOCSSuspension"
},
{
  "name": "ContactWireStagger",
  "propertyValueKind": "SINGLE",
  "propertySet": "Pset_ElementAssemblyTypeOCSSuspension"
},
{
  "name": "ContactWireStagger",
  "propertyValueKind": "SINGLE",
  "propertySet": "Pset_ElementAssemblyTypeSteadyDevice"
},

This will be an unpleasant surprise for processing applications that expect to get each property once, and you see that the 3 copies of "ContactWireStagger" are not even returned consecutively.

Let's try a similar query at our refactored GraphQL endpoint:

query DomainIFC_ClassWall_Props {
  domain(ID:"https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3") {
    classification(ID:"https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcWall") {
      name
      classificationProperty {
        name
        propertyValueKind
        propertySet
      }
    }
  }
}

In contrast to the original, it returns error information for each offending occurrence (in addition to returning data):

"errors": [
  {
    "message": "Found 2 values for single-valued field 'propertySet' from 'ClassificationProperty'",
    "path": [
      "domain",
      0,
      "classification",
      0,
      "classificationProperty",
      24,
      "propertySet"
    ],
    "locations": [
      {
        "line": 8,
        "column": 9
      }
    ]
  },

We could fix this error easily by declaring the property to be multi-valued, but we think that propertySet should in fact be single-valued, so the data should be fixed.

The field possibleValues is described as "deprecated". However, the GraphQL spec section Field Deprecation shows that a specific @deprecated directive should be used for this purpose. In the refactored RDF data and GraphQL schema, we removed this field since it just duplicates the function of allowedValues.

UPD (19 May 2023): bSI [BROKEN LINK: took our suggestion] and removed deprecated field possibleValues.

Many bSDD fields are defined as xsd:string. However, certain whitespaces in strings can be confusing and are not semantically meaningful (i.e. two values differing only by such whitespace must not be considered to be different):

• Leading and Trailing whitespaces should not be present
• Consecutive whitespaces should not be present
• Tabs should not be used: use spaces instead
• Newlines are permissible only in a few cases, but should not be used to describe enumerations

The datatypes xsd:TOKEN and xsd:NMTOKENS have restrictions in this regard.

The following query finds some of these cases:

select * {
  ?x ?field ?value
  filter(regex(str(?value),"^[ \\n\\t]|[ \\n\\t]$"))
}

Examples where this happens (not a comprehensive list):

• bsdd:dataType (eg "Real "): this is a crucially important key field that must be controlled.
• bsdd:description that is an enumeration. Should be expressed as allowedValues. e.g. in https://identifier.buildingsmart.org/uri/engisis/RFI-02/prop/S25750_0010:

"EL=Elettronica,
SE=Semi-elettronica,
EM=Elettromeccanica,
EMS=Elettromeccanica CPS,
STI= Sistema Telef. Integr.(STI).

EL=Centrale Telefonica Elettronica,
SE=Centrale Telefonica Semi-Elettronica
 EM= Centrale Telefonica Elettromeccanica,
EMS= Centrale Telefonica Elettromeccanica CPS,
STI=  Centrale STI (Sistema Telefonico Integrato)
"

The bSDD data entry or data ingest systems should have validations to prevent such whitespace. e.g. we could define SHACL rules to prevent such cases.

Properties have three characteristics that should be closely correlated:

• dimension: dimension vector as 7 integers in the format: L=Length M=Mass T=Time I=Electric current Θ=Thermodynamic temperature N=Amount of substance J=Luminous intensity. E.g. "1 1 -2 0 0 0 0" represents Force=Length*Mass/Time^2
• unit: unit of measure, which should be compatible with the dimension. E.g. "m, cm, mm, in" are all compatible with Length ("1 0 0 0 0 0 0")
  • Unfortunately, the units are not spelled consistently and are incompatible with the type Unit. There is some effort to incorporate (or migrate towards) the QUDT ontology: some properties have attribute qudtUnit in the JSON API.
  • But this is not the right approach: qudtUnit should be attached to Unit, or should replace Property.unit
  • Also, this migration is not yet implemented
• physicalQuantity: physical quantity being measured, should be compatible with the dimension. E.g. "Height, Width, Diameter" are all compatible with Length.

The following query finds all combinations of the three characteristics:

PREFIX bsdd: <http://bsdd.buildingsmart.org/def#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
select ?dim ?unit ?quant (count(*) as ?props) {
  ?x bsdd:unit ?unit; bsdd:physicalQuantity ?quant; bsdd:dimension ?dim
} group by ?dim ?unit ?quant  order by ?dim

There are 60 combinations, too many to present here. A lot of them are due to different spelling of physicalQuantity, which is free text, e.g.:

• "Longueur" vs "Länge | de-DE";
• "Force" vs "Kraft | de-DE";
• "Epaisseur" vs "Thickness"

This approach is wrong, because e.g. one cannot find all Thickness properties easily. QUDT provides URLs for various measurable quantities, and labels in numerous languages.

Let's ignore physicalQuantity, but allow some of dimension, unit to be missing:

PREFIX bsdd: <http://bsdd.buildingsmart.org/def#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
select ?dim ?unit (count(*) as ?props) {
  {?x a bsdd:Property} union {?x a bsdd:ClassificationProperty}
  optional {?x bsdd:unit ?unit}
  optional {?x bsdd:dimension ?dim}
} group by ?dim ?unit order by ?dim

There are 260 combinations, specifically:

• 134698 properties have no dimension.
  • 2434 properties have dimension "" (the empty string).
• 107861 properties have no unit, which is acceptable for enumerated and Boolean properties, and may be used for some dimensionless properties.
• 104887 properties have neither unit nor dimension, which is acceptable for enumerated and Boolean properties only.
• 29811 properties have unit but no dimension. e.g.
  • 38 properties with unit "m" have the correct dimension vector "1 0 0 0 0 0 0", but 1529 properties have no dimension.
  • 579 properties with unit "mm" have the correct dimension vector "1 0 0 0 0 0 0", but 14983 properties have no dimension, and 4 have the wrong dimension "2 0 3 0 0 0 0".

Query for the last observation (about unit "mm"):

PREFIX bsdd: <http://bsdd.buildingsmart.org/def#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
select ?dim (count(*) as ?props) {
  {?x a bsdd:Property} union {?x a bsdd:ClassificationProperty}
  ?x bsdd:unit "mm"
  optional {?x bsdd:dimension ?dim}
} group by ?dim order by ?dim

We can find these defective properties as follows:

PREFIX bsdd: <http://bsdd.buildingsmart.org/def#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
select * {
  {?x a bsdd:Property} union {?x a bsdd:ClassificationProperty}
  ?x bsdd:unit "mm"; bsdd:dimension "2 0 3 0 0 0 0"; bsdd:name ?name; bsdd:code ?code
}

They all represent the property EF007220 "Busbar thickness"

bSDD should define rules on how to express missing data. It is ok to have no physicalQuantity for dimensionless properties (e.g. count, percentage) or enumerated properties (having a list of allowedValues). But such missing data is expressed as various free texts:

• Property "Caractérisation du sol" ("Soil characterization") in class "Teneur en eau du sol" ("Soil water content") has physicalQuantity "sans grandeur" ("without magnitude") because it's a dimensionless quantity.
• Property "Document de référence de mise en œuvre d'un revêtement de sol résilient" ("Reference document for the implementation of a resilient floor covering") in class "Revêtement de sol résilient PVC à queues d'aronde et type puzzle" ("PVC resilient floor covering with dovetails of type puzzle") has physicalQuantity "Without" because it's an enumeration.
• There are 4 properties with physicalQuantity "N/A" but unit "m": this makes no sense (the quantity should be "Length")

It's better to omit physicalQuantity altogether, rather than use a variety of phrases to indicate NONE.

There are Unicode problems in some bsdd:description.

E.g. in https://identifier.buildingsmart.org/uri/buildingsmart-de/bSDTLS-1/prop/02-02-01-010 :

"Zeit der m�glichen Verarbeitung vor Aush�rtung in [min] bei +23�C und 50% rel. Luftfeuchtigkeit
"

(also has a trailing newline)

There are unresolved HTML entities (encoded chars).

E.g. in https://identifier.buildingsmart.org/uri/engisis/RFI-02/prop/S27300_0200:

"(*)
Può essere valorizzato un solo valore. SCIA = valorizzabile per le attività di tipo A o per le attività di tipo B o C nel caso in cui a seguito della valutazione favorevole del progetto si sia presentata la SCIA (ma non sia stato ancora rilasciato copia del verbale della visita tecnica dei VVF -attività di tipo A o B- o il CPI -attività ...".

Some classifications relate not to a full classification URL, but to https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/, which is incomplete. For example, this query at the original GraphQL endpoint:

{
  domain(namespaceUri: "https://identifier.buildingsmart.org/uri/BBRI/CCTB-2020") {
    classification(namespaceUri: "https://identifier.buildingsmart.org/uri/BBRI/CCTB-2020/class/42.15") {
      relations {
        relatedClassificationName
        relatedClassificationUri
      }
    }
  }
}

Returns the following:

"domain": {
  "classification": {
    "relations": [
      {
        "relatedClassificationName": null,
        "relatedClassificationUri": "https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/"
      }
    ]
  }
}

An example classification in JSON obtained with the following command:

curl -s https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegment | jq . > class-IfcCableSegment-orig1.json

Shortened for brevity:

{
  "referenceCode": "IfcCableSegment",
  "parentClassificationReference": {
    "namespaceUri": "https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcFlowSegment",
    "name": "IfcFlowSegment",
    "code": "IfcFlowSegment"
  },
  "classificationProperties": [
    {
      "name": "InstallationMethodFlagEnum",
      "description": "Special installation conditions relating to particular types of installation based on IEC60364-5-52:2001 reference installation methods C and D.",
      "dataType": "String",
      "possibleValues": [
        {
          "code": "BELOWCEILING",
          "value": "BELOWCEILING"
        }
      ],
      "propertyCode": "InstallationMethodFlagEnum",
      "propertyDomainName": "IFC",
      "propertyNamespaceUri": "https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/prop/InstallationMethodFlagEnum",
      "propertySet": "Pset_CableSegmentOccurrence",
      "propertyStatus": "Active",
      "propertyValueKind": "Single"
    },
  ],
  "domainNamespaceUri": "https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3",
  "activationDateUtc": "2022-12-31T00:00:00",
  "code": "IfcCableSegment",
  "countriesOfUse": [],
  "definition": "A cable segment is a flow segment used to carry electrical power, data, or telecommunications signals...",
  "name": "IfcCableSegment",
  "namespaceUri": "https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegment",
  "replacedObjectCodes": [],
  "replacingObjectCodes": [],
  "status": "Preview",
  "subdivisionsOfUse": [],
  "versionDateUtc": "2022-12-31T00:00:00"
}

The JSON representation obtained from the GraphQL API is very similar but not identical:

• We include __typename for each node to help assigning rdf:type later
• All fields are present, even when they are null
• GraphQL fields are sometimes named differently (e.g. properties instead of classificationProperties)
• There are some other differences, e.g. see class-IfcCableSegment-orig.json (shortened for brevity):

{
  "namespaceUri": "https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegment",
  "__typename": "Classification",
  "classificationType": "CLASS",
  "relatedIfcEntityNames": [],
  "synonyms": [],
  "referenceCode": "IfcCableSegment",
  "properties": [
    {
      "namespaceUri": "https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/prop/InstallationMethodFlagEnum",
      "__typename": "ClassificationProperty",
      "allowedValues": [
        {
          "namespaceUri": null,
          "__typename": "ClassificationPropertyValue",
          "code": "BELOWCEILING",
          "description": null,
          "value": "BELOWCEILING",
          "sortNumber": null
        },
      ],
      "dataType": "String",
      "description": "Special installation conditions relating to particular types of installation based on IEC60364-5-52:2001 reference installation methods C and D.",
      "dimension": null,
      "dimensionLength": null,
      "dimensionMass": null,
      "dimensionTime": null,
      "dimensionElectricCurrent": null,
      "dimensionThermodynamicTemperature": null,
      "dimensionAmountOfSubstance": null,
      "dimensionLuminousIntensity": null,
      "dynamicParameterPropertyCodes": null,
      "example": null,
      "isDynamic": false,
      "isRequired": null,
      "isWritable": null,
      "maxExclusive": null,
      "maxInclusive": null,
      "methodOfMeasurement": null,
      "minExclusive": null,
      "minInclusive": null,
      "pattern": null,
      "physicalQuantity": null,
      "predefinedValue": null,
      "propertySet": "Pset_CableSegmentOccurrence",
      "propertyValueKind": "SINGLE",
      "symbol": null,
      "units": null,
      "activationDateUtc": "2022-12-31T00:00:00",
      "code": "InstallationMethodFlagEnum",
      "creatorLanguageCode": null,
      "countriesOfUse": null,
      "countryOfOrigin": null,
      "deActivationDateUtc": null,
      "definition": null,
      "deprecationExplanation": null,
      "documentReference": null,
      "name": "InstallationMethodFlagEnum",
      "replacedObjectCodes": null,
      "replacingObjectCodes": null,
      "revisionDateUtc": null,
      "revisionNumber": null,
      "status": "Active",
      "subdivisionsOfUse": null,
      "uid": null,
      "versionDateUtc": "2022-12-31T00:00:00",
      "versionNumber": null,
      "visualRepresentationUri": null
    },
  ],
  "relations": [],
  "childs": null,
  "activationDateUtc": "2022-12-31T00:00:00",
  "code": "IfcCableSegment",
  "creatorLanguageCode": null,
  "countriesOfUse": null,
  "countryOfOrigin": null,
  "deActivationDateUtc": null,
  "definition": "A cable segment is a flow segment used to carry electrical power, data, or telecommunications signals...",
  "deprecationExplanation": null,
  "documentReference": null,
  "name": "IfcCableSegment",
  "replacedObjectCodes": null,
  "replacingObjectCodes": null,
  "revisionDateUtc": null,
  "revisionNumber": null,
  "status": "Preview",
  "subdivisionsOfUse": null,
  "uid": null,
  "versionDateUtc": "2022-12-31T00:00:00",
  "versionNumber": null,
  "visualRepresentationUri": null
}

The example GraphQL JSON is converted to the following "raw" RDF (shortened for brevity). Its structure is very similar to the original one, with empty blank nodes in various places, strings instead of URLs, etc.

@prefix bsdd: <http://bsdd.buildingsmart.org/def#> .
@prefix fx:   <http://sparql.xyz/facade-x/ns/> .
@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
@prefix xyz:  <http://sparql.xyz/facade-x/data/> .

[ rdf:type                   fx:root ;
  bsdd:__typename            "Classification" ;
  bsdd:activationDateUtc     "2022-12-31T00:00:00" ;
  bsdd:classificationType    "CLASS" ;
  bsdd:code                  "IfcCableSegment" ;
  bsdd:definition            "A cable segment is a flow segment used to carry electrical power, data, or telecommunications signals..." ;
  bsdd:name                  "IfcCableSegment" ;
  bsdd:namespaceUri          "https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegment" ;
  bsdd:properties [
    rdfs:member  [
    bsdd:__typename          "ClassificationProperty" ;
    bsdd:activationDateUtc   "2022-12-31T00:00:00" ;
    bsdd:allowedValues [
      rdfs:member  [
      bsdd:__typename        "ClassificationPropertyValue" ;
      bsdd:code              "BELOWCEILING" ;
      bsdd:value             "BELOWCEILING"
    ]] ;
    bsdd:code                "InstallationMethodFlagEnum" ;
    bsdd:dataType            "String" ;
    bsdd:description         "Special installation conditions relating to particular types of installation based on IEC60364-5-52:2001 reference installation methods C and D." ;
    bsdd:isDynamic           false ;
    bsdd:name                "InstallationMethodFlagEnum" ;
    bsdd:namespaceUri        "https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/prop/InstallationMethodFlagEnum" ;
    bsdd:propertySet         "Pset_CableSegmentOccurrence" ;
    bsdd:propertyValueKind   "SINGLE" ;
    bsdd:status              "Active" ;
    bsdd:versionDateUtc      "2022-12-31T00:00:00"
  ]] ;
  bsdd:referenceCode         "IfcCableSegment" ;
  bsdd:relatedIfcEntityNames []  ;
  bsdd:relations             []  ;
  bsdd:status                "Preview" ;
  bsdd:synonyms              []  ;
  bsdd:versionDateUtc        "2022-12-31T00:00:00"
] .

Now let's take a look at the original bSDD RDF class-IfcCableSegment-orig.ttl obtained with the following (shortened for brevity):

curl -s -Haccept:text/turtle https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegment > class-IfcCableSegment-orig.ttl

@base <https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegment>.

@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
@prefix bsdd: <http://bsdd.buildingsmart.org/def#>.
@prefix qudtUnit: <http://qudt.org/vocab/unit/>.
@prefix ifc4_3: <https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3>.

<https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegment>
  bsdd:ActivationDateUtc "2022-12-31";
  bsdd:Code "IfcCableSegment";
  bsdd:Definition "A cable segment is a flow segment used to carry electrical power, data, or telecommunications signals...";
  bsdd:Domain ifc4_3:;
  bsdd:Name "IfcCableSegment";
  bsdd:ReferenceCode "IfcCableSegment";
  bsdd:Status "Preview";
  bsdd:VersionDateUtc "2022-12-31";
  a bsdd:Classification.

<https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegment/InstallationMethodFlagEnum>
  bsdd:ClassificationProperty <https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegment>;
  bsdd:DataType "String";
  bsdd:Description "Special installation conditions relating to particular types of installation based on IEC60364-5-52:2001 reference installation methods C and D.";
  bsdd:Name "InstallationMethodFlagEnum";
  bsdd:PropertyCode "InstallationMethodFlagEnum";
  bsdd:PropertyDomainName "IFC";
  bsdd:PropertyNamespaceUri "https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/prop/InstallationMethodFlagEnum";
  bsdd:PropertySet "Pset_CableSegmentOccurrence";
  bsdd:PropertyStatus "Active";
  bsdd:PropertyValueKind "Single".

It has numerous problems:

• RDF naming conventions are not followed (prop names are in uppercase)
• Classification Properties don't have rdf:type bsdd:ClassificationProperty
• The relation from Classification Property to Classification is in the wrong direction (or should be renamed from bsdd:ClassificationProperty to bsdd:classification)
• bsdd:PropertyNamespaceUri should be a URL (object property) instead of string (datatype property) and should be called bsdd:property
• Dates (eg "2022-12-31") are rendered differently from JSON (have no timestamp), and lack appropriate datatype
• allowedValues and the respective ClassificationPropertyValue are missing altogether

After applying the refactoring transformation, we get the following refactored RDF class-IfcCableSegment-refact.ttl (shortened for brevity). Compare it to both the original RDF (sec 5.2.1) and the raw RDF (sec 5.1.2):

@prefix bsdd: <http://bsdd.buildingsmart.org/def#> .
@prefix fx:   <http://sparql.xyz/facade-x/ns/> .
@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
@prefix xyz:  <http://sparql.xyz/facade-x/data/> .

<https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegment>
  rdf:type                     bsdd:Classification ;
  bsdd:activationDateUtc       "2022-12-31T00:00:00"^^xsd:dateTime ;
  bsdd:classificationProperty  <https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegment/InstallationMethodFlagEnum>, ... ;
  bsdd:classificationType      "CLASS" ;
  bsdd:code                    "IfcCableSegment" ;
  bsdd:definition              "A cable segment is a flow segment used to carry electrical power, data, or telecommunications signals..." ;
  bsdd:name                    "IfcCableSegment" ;
  bsdd:referenceCode           "IfcCableSegment" ;
  bsdd:status                  "Preview" ;
  bsdd:versionDateUtc          "2022-12-31T00:00:00"^^xsd:dateTime .

<https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegment/InstallationMethodFlagEnum>
  rdf:type                bsdd:ClassificationProperty ;
  bsdd:activationDateUtc  "2022-12-31T00:00:00"^^xsd:dateTime ;
  bsdd:allowedValue       <https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegment/InstallationMethodFlagEnum/BELOWCEILING> , ... ;
  bsdd:code               "InstallationMethodFlagEnum" ;
  bsdd:dataType           "String" ;
  bsdd:description        "Special installation conditions relating to particular types of installation based on IEC60364-5-52:2001 reference installation methods C and D." ;
  bsdd:isDynamic          false ;
  bsdd:name               "InstallationMethodFlagEnum" ;
  bsdd:property           <https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/prop/InstallationMethodFlagEnum> ;
  bsdd:propertySet        "Pset_CableSegmentOccurrence" ;
  bsdd:propertyValueKind  "SINGLE" ;
  bsdd:status             "Active" ;
  bsdd:versionDateUtc     "2022-12-31T00:00:00"^^xsd:dateTime .

<https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegment/InstallationMethodFlagEnum/BELOWCEILING>
  rdf:type    bsdd:PropertyValue ;
  bsdd:code   "BELOWCEILING" ;
  bsdd:value  "BELOWCEILING" .

query domainEn_Class {
  domain(where: {languageCode: {EQ: "EN"}}) {
    name
    classification {
      id
      classificationType
      name
    }
  }
}

This returns thousands of classifications in under 0.2s, e.g.:

"domain": [
  {
    "id": "https://identifier.buildingsmart.org/uri/alma/hprops-1.0",
    "name": "h props",
    "classification": [
      {
        "id": "https://identifier.buildingsmart.org/uri/alma/hprops-1.0/class/New_class_8_copy_10",
        "name": "New classification 8"
      },

query DomainIFC_ClassWall_Props {
  domain(ID:"https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3") {
    classification(ID:"https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcWall") {
      name
      classificationProperty {
        name
        propertyValueKind
        propertySet
      }
    }
  }
}

This returns some errors about propertySet which is declared as single-valued, but sometimes happens to be multi-valued:

"errors": [
  {
    "message": "Found 2 values for single-valued field 'propertySet' from 'ClassificationProperty'",
    "path": [
      "domain",
      0,
      "classification",
      0,
      "classificationProperty",
      24,
      "propertySet"
    ],
    "locations": [
      {
        "line": 9,
        "column": 9
      }
    ]
  },

It then returns the requested data:

"domain": [
    {
      "classification": [
        {
          "name": "IfcWall",
          "classificationProperty": [
            {
              "name": "GrossFootPrintArea",
              "propertyValueKind": "SINGLE",
              "propertySet": "Qto_WallBaseQuantities"
            },
            {
              "name": "ManufacturingToleranceClass",
              "propertyValueKind": "SINGLE",
              "propertySet": "Pset_PrecastConcreteElementGeneral"
            },

Composed Properties are groups of thematically related properties. They are expressed as a specific classificationType COMPOSED_PROPERTY. Here you can see how we search for this enumerated value:

query Prop_composed {
  classification(where:{classificationType:{EQ:COMPOSED_PROPERTY}}) {
    code name
    domain {name}
    classificationProperty {code name}
  }
}

Part of the result:

{
  "code": "150822129",
  "name": "Stepped cap beam dimensions",
  "domain": {
    "name": "MINnD Bridge dictionary"
  },
  "classificationProperty": [
    {
      "code": "PR2054415455",
      "name": "Elevation of bottom of step"
    },
    {
      "code": "PR445726735",
      "name": "Elevation of top of step"
    },
    {
      "code": "PR1543732693",
      "name": "step depth"

query Prop_connected {
  property(where: {connectedPropertyCode:{}}) {
    id
    code
    connectedPropertyCode
  }
}

Part of the result:

{
   "id": "https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs-1.1/prop/volume",
   "code": "volume",
   "connectedPropertyCode": [
     "height",
     "depth",
     "width",
     "diameter"
   ]
 },
 {
   "id": "https://identifier.buildingsmart.org/uri/uniweimar/uniweimar-0.1/prop/TestObjective",
   "code": "TestObjective",
   "connectedPropertyCode": [
     "ComponentID",
     "StructureID"
   ]
 },

A significant limit of the original implementation is that it doesn't support pagination, i.e. fetching results in sections. The refactored implementation supports this for any object. Eg here we fetch 5 classifications from the largest domain, starting at number 100:

query Pagination {
  domain(ID:"https://identifier.buildingsmart.org/uri/nbs/uniclass2015-1") {
    classification(offset:100 limit:5) {
      id name
    }
  }
}

Result:

"domain": [
  {
    "classification": [
      {
        "id": "https://identifier.buildingsmart.org/uri/nbs/uniclass2015-1/class/Ac_32_10_68",
        "name": "Propagating"
      },
      {
        "id": "https://identifier.buildingsmart.org/uri/nbs/uniclass2015-1/class/En_75_10_10",
        "name": "Broadcast communications buildings"
      },
      {
        "id": "https://identifier.buildingsmart.org/uri/nbs/uniclass2015-1/class/PM_40_50_12",
        "name": "Building codes approval"
      },
      {
        "id": "https://identifier.buildingsmart.org/uri/nbs/uniclass2015-1/class/Pr_40_30_30_32",
        "name": "Food preparation worktops"
      },
      {
        "id": "https://identifier.buildingsmart.org/uri/nbs/uniclass2015-1/class/Pr_60_60_38_42",
        "name": "Instantaneous plate heat exchangers"
      }
    ]
  }
]

We can easily find Classifications that have relations, then fetch data of their related Classifications:

query ClassificationRel {
  classification(where:{relation:{}}) {
    id name
    relation {
      relationType
      related {
        id name
      }
    }
  }
}

Please note that for each relation, this returns both the original Classification we started from, and the target Classification. The reason is that the node ClassificationRelation has two related links:

"classification": [
  {
    "id": "https://identifier.buildingsmart.org/uri/ATALANE/REX-OBJ-1.0/class/262c5f4a-a631-4041-a5ea-569ebad4265b",
    "name": "Revêtement de sol résilient LVT acoustique à poisser",
    "relation": [
      {
        "relationType": "HasReference",
        "related": [
          {
            "id": "https://identifier.buildingsmart.org/uri/ATALANE/REX-OBJ-1.0/class/262c5f4a-a631-4041-a5ea-569ebad4265b",
            "name": "Revêtement de sol résilient LVT acoustique à poisser"
          },
          {
            "id": "https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCovering",
            "name": "IfcCovering"
          }
        ]
      },

We have implemented bidirectional graph navigation, so we can fetch related Classifications starting from ClassificationRelation instead of Classification:

query ClassificationRel2 {
  classificationRelation {
    relationType
    related {
      id name
    }
  }
}

"classificationRelation": [
   {
     "relationType": "HasReference",
     "related": [
       {
         "id": "https://identifier.buildingsmart.org/uri/ATALANE/REX-OBJ-1.0/class/262c5f4a-a631-4041-a5ea-569ebad4265b",
         "name": "Revêtement de sol résilient LVT acoustique à poisser"
       },
       {
         "id": "https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCovering",
         "name": "IfcCovering"
       }
     ]
   },

Let's find all Properties with dimension vector indicating "length":

query LengthProps {
  property(where:{dimension:{EQ:"1 0 0 0 0 0 0"}}) {
    physicalQuantity
    unit
  }
}

We can now compare the variety associated with such properties, e.g.:

• physicalQuantity: "Epaisseur", "Longueur", "Länge", "Fläche je Länge | de-DE", etc
• unit: "mm", "cm" but also stranger units like "mm²/m"

This visualization shows classifications of type "COMPOSED_PROPERTY" that serve as a container of related properties.

This visualization shows classifications of type "DOMAIN" that serve as a "sub-domain" of Classifications. Expanding a node shows its ClassificationProperties.

This visualization shows classifications that have relations (we ignore the relation name). It shows a number of French classes relating to Space, Slab, Covering. (Please note that another cluster that has "class" in the middle is due to data quality problems in BSDD.)

propSet is expected to be single-valued by the GraphQL schema, but in fact there are some multi-valued occurrences. This visualization looks for such cases (e.g. see this saved visual graph).