Merge branch 'master' into fcu-doc-cleanup

CONTRIBUTING.md

@@ -6,7 +6,7 @@ just a few small guidelines you need to follow.
 ## Contributor License Agreement
 
 Contributions to this project must be accompanied by a Contributor License
-Agreement. You (or your employer) retain the copyright to your contribution;
+Agreement (CLA). You (or your employer) retain the copyright to your contribution;
 this simply gives us permission to use and redistribute your contributions as
 part of the project. Head over to <https://cla.developers.google.com/> to see
 your current agreements on file or to sign a new one.
@@ -29,13 +29,12 @@ This project follows
 
 ## Pull requests
 
-If you are Google partner, please make sure not to add sensitive data on GitHub when:
-* Extending the ontology types through a pull request 
+If you are Google partner, please make sure not to add sensitive data on GitHub when performing the following actions:
+* Extending the ontology types through a pull request
 * Opening an issue
 * Asking a question
 
-Sensitive data is one of the following:
-* Building names or their locations, same applied for floors, rooms and zones.
-* Identifiers such as project id, subscription names
-* Equipment names and their locations.
-* Others
+Sensitive data is considered anything in any of the following categories:
+* **Buildings:** name, location, street address, information about floors/rooms/zones within the building, etc.
+* **Devices/Equipment:** name, id, location, etc.
+* **Other:** project id, subscription names, etc.

README.md

@@ -8,59 +8,61 @@
 
 The Digital Buildings project is an open-source, Apache-licensed effort to create a uniform schema and toolset for representing structured information about buildings and building-installed equipment. A version of the Digital Buildings ontology and toolset is currently being used by Google to manage buildings in its portfolio. 
 
-The Digital Buildings project originated from the need to manage a very large, heterogeneous building portfolio in a scalable way. The project aims to enable management applications/analyses that are trivially portable between buildings.  This goal is achieved through a combination of semantically-expressive abstract modeling, an easy-to-use configuration language, and robust validation tooling.  Digital Buildings work has been inspired by [Project Haystack](https://project-haystack.org/tag) and [BrickSchema](https://brickschema.org/) and maintains cross-compatibility and/or convergence as a long-term objective.
+The Digital Buildings project originated from the need to manage a very large and heterogeneous building portfolio in a scalable way. The project aims to enable management applications and analyses that are trivially portable between buildings. This goal is achieved through a combination of semantically-expressive abstract modeling, an easy-to-use configuration language, and robust validation tooling. Digital Buildings work has been inspired by [Project Haystack](https://project-haystack.org/tag) and [BrickSchema](https://brickschema.org/) and maintains cross-compatibility and/or convergence as a long-term objective.
 
 In creating the Digital Buildings project, we have considered the following:
 
-* Human Readability
+* Human readability
 * Machine readability and interpretation
 * Composable functionality
-* Dimensional Analysis
+* Dimensional analysis
 * Correctness validation
-* Cross compatibility
+* Cross-compatibility
 
 ## Project Structure
 
 This project is structured as follows:
-*  An [**ontology**](./ontology/README.md) that defines the parameters of the semantic data model (Terminology box) and tools for building, validating, and associating real equipment with a specific model. It contains the following formats:
-   * [Yaml format](./ontology/yaml/README.md)
+*  An [ontology](./ontology/README.md) that defines the parameters of the semantic data model ("Terminology box") and tools for building, validating, and associating real equipment with a specific model. It contains the following formats:
+   * [YAML format](./ontology/yaml/README.md)
    * [RDF/OWL format](./ontology/rdf/README.md)
-* [Building Configuration](./ontology/docs/building_config.md) which contains a mapping between the ontology and the "raw" data. Building Config is the Assertion Box.
-* Tools that allow the following:
-  * [ABEL](./tools/abel/README.md) generates from/to Google spreadsheet/[Building Configuration](./ontology/docs/building_config.md).
-  * [Explorer](./tools/explorer/README.md) allows users to explorer the ontology types and their associated fields.
-  * [Yaml Validator](./tools/validators/ontology_validator/README.md) which allows to validate the yaml ontology upon a change or an extension.
-  * [RDF/OWL Generator](./tools/rdf_generator/README.md) which allows to generate an RDF version from the yaml ontology files.
-* [Internal Building Representation](./ibr/README.md) (IBR) File Format to represent data from different verticals such as spatial, assets.
+
+* A [model instance configuration](./ontology/docs/building_config.md) (a.k.a building configuration file) that contains a mapping between the ontology and the "raw" real-world data. Building configuration files are the "Assertion box."
+* Tools that enable the following:
+  * [**ABEL**](./tools/abel/README.md)**:** facilitates easier building configration construction by converting from a templatized Google Sheet to a [building configuration file](./ontology/docs/building_config.md) (and from a building configuration file back to a Google Sheet).
+  * [**Explorer**](./tools/explorer/README.md)**:** allows users to explore ontology type fields and compare ontology types to each other.
+  * [**Instance Validator**](./tools/validators/ontology_validator/README.md)**:** validates a concrete application (instance) of DBO (i.e., a building configuration file) with optional telemetry validation.
+  * [**Ontology Validator**](./tools/validators/ontology_validator/README.md)**:** validates the ontology upon a change or an extension (currently supports YAML format only).
+  * [**RDF/OWL Generator**](./tools/rdf_generator/README.md)**:** generates an RDF version from the YAML ontology files.
+* An [Internal Building Representation (IBR)](./ibr/README.md) file format to represent data from different verticals such as spatial or assets.
 
 ## Learning Modules
-The learning modules provide an overview of:
-* The main concepts of the Digital Buildings Ontology.
-* How to model and extend types.
-* The Building configuration file concepts.
-* The validation tools for the Building Configuration file.
+The learning modules provide an overview of the following key concepts:
+* The main concepts and components of the Digital Buildings Ontology
+* How to model entities and extend types in the ontology
+* The components of building configuration files
+* How to use the validation tools for ontology extensions and building configuration files
 
 ### Module 1: Digital Buildings Ontology (DBO)
 In this module, you’ll fully explore the core modeling and organizational concepts of the DBO. These are essential concepts for data modeling and creating building configuration files.
 
 
 * [Lesson 1: Introduction to the DBO](./ontology/docs/learning/Module_1_Lesson_1_Introduction_to_the_DBO.pdf)
-* [Lesson 2: Conceptual Model](./ontology/docs/learning/Module_1_Lesson_2_Conceptual_model.pdf)
+* [Lesson 2: Conceptual model](./ontology/docs/learning/Module_1_Lesson_2_Conceptual_model.pdf)
 * [Lesson 3: Subfields](./ontology/docs/learning/Module_1_Lesson_3_Subfields.pdf)
 * [Lesson 4: Fields](./ontology/docs/learning/Module_1_Lesson_4_Fields.pdf)
-* [Lesson 5: States and Multi-states](./ontology/docs/learning/Module_1_Lesson_5_States_and_multistates.pdf)
-* [Lesson 6: Entity Types](./ontology/docs/learning/Module_1_Lesson_6_Entity_types.pdf)
+* [Lesson 5: States and multi-states](./ontology/docs/learning/Module_1_Lesson_5_States_and_multistates.pdf)
+* [Lesson 6: Entity types](./ontology/docs/learning/Module_1_Lesson_6_Entity_types.pdf)
 * [Lesson 7: Mappings](./ontology/docs/learning/Module_1_Lesson_7_Mappings.pdf)
 * [Lesson 8: Connections](./ontology/docs/learning/Module_1_Lesson_8_Connections.pdf)
 * [Lesson 9: Namespaces](./ontology/docs/learning/Module_1_Lesson_9_Namespaces.pdf)
 
 
-### Module 2: Module 2: Data Modeling with the DBO
+### Module 2: Data Modeling with the DBO
 
 In this module, you’ll deepen your understanding of the DBO and practice applying it. Through several hands-on activities, you'll walk through the recommended workflow for creating a building configuration file
 
 
-* [Lesson 1: Get Ready to data model](./ontology/docs/learning/Module_2_Lesson_1_Get_ready_to_data_model.pdf)
+* [Lesson 1: Get ready to data model](./ontology/docs/learning/Module_2_Lesson_1_Get_ready_to_data_model.pdf)
 * [Lesson 2: Determine which devices need to be modeled](./ontology/docs/learning/Module_2_Lesson_2_Determine_which_devices_need_to_be_modeled.pdf)
 * [Lesson 3: Determine which data points are required](./ontology/docs/learning/Module_2_Lesson_3_Determine_which_data_points_are_required.pdf)
 * [Lesson 4: Name each data point using the DBO](./ontology/docs/learning/Module_2_Lesson_4_Name_each_data_point_using_the_DBO.pdf)
@@ -70,16 +72,16 @@ In this module, you’ll deepen your understanding of the DBO and practice apply
 
 
 ## Issues
-Please post issues in [Issues](https://github.com/google/digitalbuildings/issues) section.
+Please post issues in the [Issues](https://github.com/google/digitalbuildings/issues) section.
 
 ## Discussion
-Open mailing list to discuss Google's Digital Building effort. The discussion could include general questions, standards, APIs, and more. [google-digital-building-discuss@googlegroups.com](mailto:google-digital-building-discuss@googlegroups.com)
+Our team has created an open mailing list to discuss Google's Digital Building effort. The discussion could include general questions, standards, APIs, and more. Join the discussion here: [google-digital-building-discuss@googlegroups.com](mailto:google-digital-building-discuss@googlegroups.com).
 
-Members are expected to adhere to this code of conduct: [https://opensource.google.com/conduct](https://opensource.google.com/conduct)
+Members are expected to adhere to this code of conduct: [https://opensource.google.com/conduct](https://opensource.google.com/conduct).
 
 ## How to Contribute
 
-Please see the [contribution section](CONTRIBUTING.md)
+Please see the [contribution](CONTRIBUTING.md) section.
 
 ## License
 ```

ontology/README.md

@@ -1,35 +1,40 @@
 # Digitalbuildings Ontology
 
-This section of the digitalbuildings tree contains configuration files and documentation for the digitalbuildings model. 
-
-The model is provided in two versions: 
-*    A [yaml](/ontology/yaml/README.md) version that is the primary configuration source
-*    A generated [RDF](/ontology/rdf/README.md) version
-
-Documentation for the model can be found in the [docs](docs/) folder.  
-*   [Ontology Overview](/ontology/docs/ontology.md) provides an overview of the structure and first principles of the ontology
-*   [Ontology Configuration](/ontology/docs/ontology_config.md) explains how to write and validate the .yaml configuration files
-*   [Model](/ontology/docs/model.md) describes the conventions used in the provided abstract model
-*   [Building Configuration](/ontology/docs/building_config.md) describes the configuration format for mapping concrete assets to a model and 
-validating the mapping
+This section of the digitalbuildings tree contains configuration files and documentation for the digitalbuildings model.
+
+The model is provided in the following file formats:
+*    A [yaml](/ontology/yaml/README.md) version, which is the primary configuration source
+*    A [RDF](/ontology/rdf/README.md) version that is generated from the yaml version using the [RDF Generator](/tools/rdf_generator/README.md)
+
+Documentation for the model can be found in the [docs](docs/) folder.
+*   [**Ontology Overview**](/ontology/docs/ontology.md)**:** provides an overview of the structure and first principles of the ontology
+*   [**Ontology Configuration**](/ontology/docs/ontology_config.md)**:** explains how to write and validate the .yaml configuration files
+*   [**Model**](/ontology/docs/model.md)**:** describes the conventions used in the provided abstract model
+    * [**Model HVAC**](/ontology/docs/model_hvac.md)**:** specifically describes the application of the model in the HVAC namespace
+        * [**AHU**](/ontology/docs/hvac_ahu.md)**:** example of the model applied to an air handling unit (AHU)
+        * [**CHWS**](/ontology/docs/hvac_chws.md)**:** example of the model applied to a chilled water system (CHWS)
+        * [**FCU**](/ontology/docs/hvac_fcu.md)**:** example of the model applied to a fan coil unit (FCU)
+        * [**HWS**](/ontology/docs/hvac_hws.md)**:** example of the model applied to a heating water system (HWS)
+*   [**Building Configuration**](/ontology/docs/building_config.md)**:** describes the configuration format for mapping concrete assets to a model and validating the mapping
+* [**Frequenty Asked Questions**](/ontology/docs/faq.md)**:** centralized answers to frequently asked questions regarding the ontology
 
 ## Learning Modules
-The learning modules provide an overview of:
-* The main concepts of the Digital Buildings Ontology.
-* How to model and extend types.
-* The Building configuration file concepts.
-* The validation tools for the Building Configuration file.
+The learning modules provide an overview of the following key concepts:
+* The main concepts and components of the Digital Buildings Ontology
+* How to model entities and extend types in the ontology
+* The components of building configuration files
+* How to use the validation tools for ontology extensions and building configuration files
 
 ### Module 1: Digital Buildings Ontology (DBO)
 In this module, you’ll fully explore the core modeling and organizational concepts of the DBO. These are essential concepts for data modeling and creating building configuration files.
 
 
 * [Lesson 1: Introduction to the DBO](./docs/learning/Module_1_Lesson_1_Introduction_to_the_DBO.pdf)
-* [Lesson 2: Conceptual Model](./docs/learning/Module_1_Lesson_2_Conceptual_model.pdf)
+* [Lesson 2: Conceptual model](./docs/learning/Module_1_Lesson_2_Conceptual_model.pdf)
 * [Lesson 3: Subfields](./docs/learning/Module_1_Lesson_3_Subfields.pdf)
 * [Lesson 4: Fields](./docs/learning/Module_1_Lesson_4_Fields.pdf)
-* [Lesson 5: States and Multi-states](./docs/learning/Module_1_Lesson_5_States_and_multistates.pdf)
-* [Lesson 6: Entity Types](./docs/learning/Module_1_Lesson_6_Entity_types.pdf)
+* [Lesson 5: States and multi-states](./docs/learning/Module_1_Lesson_5_States_and_multistates.pdf)
+* [Lesson 6: Entity types](./docs/learning/Module_1_Lesson_6_Entity_types.pdf)
 * [Lesson 7: Mappings](./docs/learning/Module_1_Lesson_7_Mappings.pdf)
 * [Lesson 8: Connections](./docs/learning/Module_1_Lesson_8_Connections.pdf)
 * [Lesson 9: Namespaces](./docs/learning/Module_1_Lesson_9_Namespaces.pdf)
@@ -40,7 +45,7 @@ In this module, you’ll fully explore the core modeling and organizational conc
 In this module, you’ll deepen your understanding of the DBO and practice applying it. Through several hands-on activities, you'll walk through the recommended workflow for creating a building configuration file
 
 
-* [Lesson 1: Get Ready to data model](./docs/learning/Module_2_Lesson_1_Get_ready_to_data_model.pdf)
+* [Lesson 1: Get ready to data model](./docs/learning/Module_2_Lesson_1_Get_ready_to_data_model.pdf)
 * [Lesson 2: Determine which devices need to be modeled](./docs/learning/Module_2_Lesson_2_Determine_which_devices_need_to_be_modeled.pdf)
 * [Lesson 3: Determine which data points are required](./docs/learning/Module_2_Lesson_3_Determine_which_data_points_are_required.pdf)
 * [Lesson 4: Name each data point using the DBO](./docs/learning/Module_2_Lesson_4_Name_each_data_point_using_the_DBO.pdf)

ontology/docs/building_config.md

@@ -239,20 +239,20 @@ The following example shows a building with one floor and one room:
 
 ``` yaml
 # Building
-UK-LON-S2:
+A-BUILDING-CODE:
   type: FACILITIES/BUILDING
 
 # Floor
-UK-LON-S2-1:
+A-BUILDING-CODE-FLOOR1:
   type: FACILITIES/FLOOR
   connections:
-    UK-LON-S2: CONTAINS
+    A-BUILDING-CODE: CONTAINS
 
 # Room
-UK-LON-S2-1-1C3G:
+A-BUILDING-CODE-FLOOR1-ROOM123:
   type: FACILITIES/ROOM
   connections:
-    UK-LON-S2-1: CONTAINS
+    A-BUILDING-CODE-FLOOR1: CONTAINS
 
 ```
 
@@ -471,14 +471,14 @@ Expanding the VAV definition from the previous section, and adding some lights:
 VAV-32:
   type: HVAC/VAV
   connections:
-    UK-LON-6PS-1: CONTAINS
-    AHU-123: FEEDS
+    A-BUILDING-FLOOR-GUID: CONTAINS
+    AN-AHU-GUID: FEEDS
 
 LF-123:
   type: LIGHTING/LIGHTING_FIXTURE
   connections:
-    UK-LON-6PS-1-1A2: CONTAINS
-    LCG-234: HAS_PART
+    A-BUILDING-ROOM-GUID: CONTAINS
+    A-LIGHTING-GROUP-GUID: HAS_PART
 ```
 
 ### Zones and Control Groups
@@ -495,15 +495,15 @@ Here are some examples:
 ZONE-123:
   type: HVAC/ZONE
   connections:
-    UK-LON-6PS-1: CONTAINS
-    VAV-123: FEEDS
+    A-BUILDING-FLOOR-GUID: CONTAINS
+    A-VAV-GUID: FEEDS
 
 # Lighting Control Group
 LCG-234:
   type: LIGHTING/SWITCH_GROUP
   connections:
-    UK-LON-6PS-1: CONTAINS
-    SW-456: CONTROLS
+    A-BUILDING-ROOM-GUID: CONTAINS
+    A-SWITCH-GUID: CONTROLS
 ```
 
 ## Building Configuration Modes
@@ -708,6 +708,9 @@ to the entity blocks keyed by `update_mask`. This is shown in the example for
 an entity coded as E4, showing all possible entity attributes, where
 `update_mask` is given with fields of `translation` and `cloud_device_id`.
 
+Note that `etag` is required for `UPDATE` and `DELETE` but not for `ADD`
+operations.
+
 ``` yaml
 CONFIG_METADATA:
   operation: UPDATE