#+options: ':nil *:t -:t ::t <:t H:5 \n:nil ^:{} arch:headline author:t #+options: c:nil creator:nil d:(not "LOGBOOK") date:t e:t email:nil f:t #+options: inline:t p:nil pri:nil prop:nil stat:t tags:t tasks:t tex:t #+options: timestamp:nil title:t toc:5 todo:t |:t #+startup: showeverything #+title: Semantic bSDD #+subtitle: Improving the GraphQL, JSON and RDF Representations of buildingSmart Data Dictionary #+date: <2023-05-25> #+author: Vladimir Alexiev, Mihail Radkov, Nataliya Keberle #+email: vladimir.alexiev@ontotext.com #+institute: Ontotext #+keywords: Linked building data, LBD, buildingSMART Data Dictionary, bSDD, FAIR data, data quality #+language: en #+select_tags: export #+exclude_tags: noexport #+creator: Emacs 28.1 (Org mode 9.5.2) #+html_head_extra: <link rel="icon" type="image/x-icon" href="img/favicon.ico"> #+options: html-preamble:"Author: %a (%e)Date: %d<img src='./img/SemBSDD-Logo-400px.png'/>" #+options: anchor:t

Table of Contents :TOC:noexport: :PROPERTIES: :TOC: :include all :CUSTOM_ID: table-of-contents :END:

:CONTENTS:

[[#abstract][Abstract]]
[[#introduction][Introduction]]
- [[#bsdd][bSDD]]
- [[#graphql-benefits][GraphQL Benefits]]
- [[#original-graphql-bsdd-schema-voyager][Original GraphQL bSDD Schema: Voyager]]
- [[#original-graphql-bsdd-schema-problems][Original GraphQL bSDD Schema: Problems]]
- [[#refactored-graphql-bsdd-schema-voyager][Refactored GraphQL bSDD Schema: Voyager]]
- [[#refactored-bsdd-schema-plantuml-overview-diagram][Refactored bSDD Schema: PlantUML Overview Diagram]]
- [[#refactored-bsdd-schema-plantuml-full-diagram][Refactored bSDD Schema: PlantUML Full Diagram]]
- [[#graphiql-querying-of-original-endpoint][GraphiQL Querying of Original Endpoint]]
- [[#graphiql-querying-of-refactored-endpoint][GraphiQL Querying of Refactored Endpoint]]
- [[#files][Files]]
- [[#endpoints-and-pages][Endpoints and Pages]]
[[#original-bsdd-data][Original bSDD Data]]
- [[#getting-bsdd-data-dumps][Getting bSDD Data Dumps]]
- [[#statistics][Statistics]]
  - [[#total-entities][Total Entities]]
  - [[#classifications-per-domain][Classifications Per Domain]]
  - [[#fields-used][Fields Used]]
  - [[#fields-used-in-classification][Fields Used in Classification]]
  - [[#fields-used-in-classificationproperty][Fields Used in ClassificationProperty]]
  - [[#fields-used-in-property][Fields Used in Property]]
  - [[#fields-used-in-propertyvalue][Fields Used in PropertyValue]]
- [[#key-fields][Key Fields]]
  - [[#classificationtype][ClassificationType]]
  - [[#propertyvaluekind-of-classificationproperty][PropertyValueKind of ClassificationProperty]]
  - [[#propertyvaluekind-of-property][PropertyValueKind of Property]]
  - [[#status][Status]]
  - [[#dynamic-properties][Dynamic Properties]]
  - [[#iswritable-property][isWritable Property]]
  - [[#isrequired-property][isRequired Property]]
  - [[#domains-with-iswritable-and-isrequired-properties][Domains with isWritable and isRequired Properties]]
[[#suggested-improvements][Suggested Improvements]]
- [[#return-the-same-data-across-apis][Return the Same Data Across APIs]]
- [[#improve-property-names][Improve Property Names]]
- [[#use-the-same-url-for-data-and-for-web-pages][Use the Same URL for Data and for Web Pages]]
- [[#time-dependent-search-uris][Time-Dependent search URIs]]
- [[#improve-url-structure-and-consistency][Improve URL Structure and Consistency]]
  - [[#explicate-domain-versions][Explicate Domain Versions]]
  - [[#declare-urls-to-be-id-and-use-a-mandatory-field-id][Declare URLs to be ID and Use a Mandatory Field id]]
  - [[#overlap-of-entity-classes-with-classificationtype][Overlap of Entity Classes with classificationType]]
  - [[#property-vs-classificationproperty-use-distinct-urls][Property vs ClassificationProperty: Use Distinct URLs]]
  - [[#all-entities-should-have-url][All Entities Should Have URL]]
- [[#modeling-issues][Modeling Issues]]
  - [[#modeling-of-complex-properties][Modeling of Complex Properties]]
  - [[#modeling-of-dynamic-properties][Modeling of Dynamic Properties]]
  - [[#improve-relations-between-entities][Improve Relations Between Entities]]
  - [[#add-more-entities][Add More Entities]]
  - [[#use-class-inheritance][Use Class Inheritance]]
  - [[#improve-description-of-classificationproperties][Improve Description of ClassificationProperties]]
  - [[#improve-representation-of-propertyvalues][Improve Representation of PropertyValues]]
  - [[#improve-representation-of-predefinedvalue][Improve Representation of predefinedValue]]
- [[#improve-multilingual-support][Improve Multilingual Support]]
  - [[#self-describing-langstrings][Self-Describing langStrings]]
  - [[#language-fallback][Language Fallback]]
  - [[#use-language-content-negotiation][Use Language Content Negotiation]]
  - [[#improve-lang-tags][Improve Lang Tags]]
- [[#improve-rdf-structure][Improve RDF Structure]]
- [[#graphql-improvements][GraphQL Improvements]]
  - [[#searchability-and-pagination][Searchability and Pagination]]
  - [[#eliminate-parallel-links-between-entities][Eliminate Parallel Links Between Entities]]
  - [[#graphql-arrays-and-nullability][GraphQL Arrays and Nullability]]
  - [[#null-classifications-error][Null Classifications Error]]
  - [[#null-classification-childs-error][Null Classification Childs Error]]
  - [[#null-classificationproperty-name-error][Null ClassificationProperty Name Error]]
  - [[#missing-domains][Missing Domains]]
  - [[#unexpected-multiple-values][Unexpected Multiple Values]]
  - [[#deprecated-properties][Deprecated Properties]]
- [[#data-quality-problems][Data Quality Problems]]
  - [[#trim-leading-trailing-consecutive-whitespace][Trim Leading, Trailing, Consecutive Whitespace]]
  - [[#improve-physical-quantities-and-units][Improve Physical Quantities and Units]]
  - [[#rules-about-missing-data][Rules About Missing Data]]
  - [[#unicode-problems][Unicode Problems]]
  - [[#unresolved-html-entities][Unresolved HTML Entities]]
  - [[#bad-classification-relations][Bad Classification Relations]]
[[#implementing-improvements][Implementing Improvements]]
- [[#converting-json-to-raw-rdf-using-sparql-anything][Converting JSON to Raw RDF using SPARQL Anything]]
  - [[#raw-json-example][Raw JSON Example]]
  - [[#raw-rdf-example][Raw RDF Example]]
- [[#refactoring-rdf-using-sparql-update][Refactoring RDF using SPARQL Update]]
  - [[#original-rdf-example][Original RDF Example]]
  - [[#refactored-rdf-example][Refactored RDF Example]]
- [[#graphql-to-soml-and-back][GraphQL to SOML and Back]]
- [[#sample-queries][Sample Queries]]
  - [[#domains-with-langen-and-their-classifications][Domains with lang=EN and their Classifications]]
  - [[#classificationproperties-in-ifc-class-ifcwall][ClassificationProperties in IFC class IfcWall]]
  - [[#classifications-of-type-composed_property-and-their-constituent-properties][Classifications of Type COMPOSED_PROPERTY and their Constituent Properties]]
  - [[#properties-that-have-connected-properties][Properties that Have Connected Properties]]
  - [[#pagination][Pagination]]
  - [[#classifications-with-relations][Classifications with Relations]]
  - [[#relations-of-classifications][Relations of Classifications]]
  - [[#length-properties][Length Properties]]
- [[#graph-visualizations][Graph Visualizations]]
  - [[#composed_property-classifications]["COMPOSED_PROPERTY" Classifications]]
  - [[#domain-classifications]["DOMAIN" Classifications]]
  - [[#classification-relations][Classification Relations]]
  - [[#multivalued-propsets][Multivalued propSets]]
[[#conclusions][Conclusions]]
- [[#future-work][Future Work]]
- [[#acknowledgements][Acknowledgements]] :END:

Abstract :PROPERTIES: :CUSTOM_ID: abstract :END: The buildingSmart Data Dictionary (bSDD) is an important shared resource in the Architecture, Engineering, Construction, and Operations (AECO) domain. It is a collection of datasets ("domains") that define various classifications (objects representing building components, products, and materials), their properties, allowed values, etc. bSDD defines a GraphQL API, as well as REST APIs that return JSON and RDF representations. This improves the interoperability of bSDD and its easier deployment in architectural Computer Aided Design (CAD) and other AECO software.

However, bSDD data is not structured as well as possible, and data retrieved via different APIs is not identical in content and structure. This lowers bSDD data quality, usability and trust.

We conduct a thorough comparison and analysis of bSDD data related to fulfillment of FAIR (findable, accessible, interoperable, and reusable) principles. Based on this analysis, we suggest enhancements to make bSDD data better structured and more FAIR.

We implement many of the suggestions by refactoring the original data to make it better structured/interconnected, and more "semantic". We provide a SPARQL endpoint using [[https://graphdb.ontotext.com/][Ontotext GraphDB]], and GraphQL endpoint using [[https://platform.ontotext.com/semantic-objects/][Ontotext Platform Semantic Objects]]. Our detailed work is available at [[https://github.com/Accord-Project/bsdd]] (open source) and [[https://bsdd.ontotext.com]] (home page, schemas, data, sample queries).

Introduction :PROPERTIES: :CUSTOM_ID: introduction :END:

** bSDD :PROPERTIES: :CUSTOM_ID: bsdd :END: Reusable data dictionaries are widely used for the electronic exchange of product and component information across industries, improving interoperation between systems. Examples include:

[[https://cdd.iec.ch/][IEC Common Data Dictionary]] (IEC CDD): electrical components, units of measure, documents and certificates, etc.
[[https://eclass.eu/en/][eCl@ss]]: a product classification and parts descri

Bsdd

Install / Use

README