Merge pull request #348 from BuildingSync/feat/translation

Feat/translation

Author: macintoshpie

.gitignore

@@ -9,4 +9,5 @@ gems
 .python-version
 BuildingSync.xpr
 schema_documentation.csv
-geojson.xsd
+geojson.xsd
+spec/output

spec/data/v2_for_translation.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<auc:BuildingSync xmlns:auc="http://buildingsync.net/schemas/bedes-auc/2019"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://buildingsync.net/schemas/bedes-auc/2019 https://raw.githubusercontent.com/BuildingSync/schema/v2.3.0/BuildingSync.xsd" version="2.3.0">
+  <auc:Facilities>
+    <auc:Facility ID="Facility-1">
+      <auc:Measures>
+        <auc:Measure ID="Measure-1">
+          <auc:TechnologyCategories>
+            <auc:TechnologyCategory>
+              <auc:OtherHVAC>
+                <auc:MeasureName>Repair leaks / seal ducts</auc:MeasureName>
+                <auc:MeasureName>Convert CV system to VAV system</auc:MeasureName>
+              </auc:OtherHVAC>
+            </auc:TechnologyCategory>
+          </auc:TechnologyCategories>
+        </auc:Measure>
+      </auc:Measures>
+    </auc:Facility>
+  </auc:Facilities>
+</auc:BuildingSync>

spec/validation_spec.rb

@@ -44,21 +44,21 @@
     # and point schemaLocation to it instead
     schema_doc = Nokogiri::XML(File.read('BuildingSync.xsd'))
 
-    GEOJSON_XSD_PATH = 'geojson.xsd'
-    GEOJSON_IMPORT_XPATH = 'xs:schema/xs:import[@namespace = "http://www.gbxml.org/schema"]'
-    if !File.file?(GEOJSON_XSD_PATH) then
-      imported_schema_locations = schema_doc.xpath(GEOJSON_IMPORT_XPATH).collect { |nokogiri_xml_node|
+    GBXML_XSD_PATH = 'gbxml.xsd'
+    GBXML_IMPORT_PATH = 'xs:schema/xs:import[@namespace = "http://www.gbxml.org/schema"]'
+    if !File.file?(GBXML_XSD_PATH) then
+      imported_schema_locations = schema_doc.xpath(GBXML_IMPORT_PATH).collect { |nokogiri_xml_node|
         nokogiri_xml_node.attribute("schemaLocation").value
       }
       expect(imported_schema_locations.length).to eq 1
 
-      open(GEOJSON_XSD_PATH, 'wb') do |file|
+      open(GBXML_XSD_PATH, 'wb') do |file|
         file << open(imported_schema_locations[0]).read
       end
     end
 
-    schema_doc.xpath(GEOJSON_IMPORT_XPATH).collect { |nokogiri_xml_node|
-      nokogiri_xml_node.attribute("schemaLocation").value = GEOJSON_XSD_PATH
+    schema_doc.xpath(GBXML_IMPORT_PATH).collect { |nokogiri_xml_node|
+      nokogiri_xml_node.attribute("schemaLocation").value = GBXML_XSD_PATH
     }
 
     @xsd = Nokogiri::XML::Schema.from_document(schema_doc)
@@ -389,3 +389,52 @@
     expect(dupe_names).to be_empty
   end
 end
+
+RSpec.describe 'Version translation from v2 to v3' do
+  before :all do
+    # TODO: DRY this up --- duplicate code from example validators spec above
+  
+    # Nokogiri doesn't seem to support XSDs which import other schemas with URLs
+    # for the schemaLocation. To allow testing, we download the imported schema
+    # and point schemaLocation to it instead
+    schema_doc = Nokogiri::XML(File.read('BuildingSync.xsd'))
+
+    GBXML_XSD_PATH = 'gbxml.xsd'
+    GBXML_IMPORT_PATH = 'xs:schema/xs:import[@namespace = "http://www.gbxml.org/schema"]'
+    if !File.file?(GBXML_XSD_PATH) then
+      imported_schema_locations = schema_doc.xpath(GBXML_IMPORT_PATH).collect { |nokogiri_xml_node|
+        nokogiri_xml_node.attribute("schemaLocation").value
+      }
+      expect(imported_schema_locations.length).to eq 1
+
+      open(GBXML_XSD_PATH, 'wb') do |file|
+        file << open(imported_schema_locations[0]).read
+      end
+    end
+
+    schema_doc.xpath(GBXML_IMPORT_PATH).collect { |nokogiri_xml_node|
+      nokogiri_xml_node.attribute("schemaLocation").value = GBXML_XSD_PATH
+    }
+
+    @xsd = Nokogiri::XML::Schema.from_document(schema_doc)
+
+    # clean up output dir
+    FileUtils.rm_rf('spec/output')
+    FileUtils.mkdir_p('spec/output')
+  end
+
+  it 'should result in valid v3 file' do
+    doc = Nokogiri::XML(File.read('spec/data/v2_for_translation.xml'))
+    xslt_doc = Nokogiri::XML(File.read('translation/v2_to_v3.xsl'))
+    # we must remove xsl:message from the stylesheet b/c nokogiri does not handle
+    # them properly -- it considers it a failure.
+    # See: https://github.com/sparklemotion/nokogiri/issues/1217
+    xslt_doc.search('//xsl:message').remove
+    xslt = Nokogiri::XSLT::Stylesheet.parse_stylesheet_doc(xslt_doc)
+
+    transformed_doc = xslt.transform(doc)
+    File.write('spec/output/v2_to_v3.xml', transformed_doc)
+
+    expect(@xsd.validate(transformed_doc)).to be_empty
+  end
+end

translation/README.md

@@ -0,0 +1,21 @@
+# Translation
+To assist with "updating" users BuildingSync documents, this directory provides XSLTs for translating one version into another.
+Note that the translation is not guaranteed to be perfect as there might not always be a one to one mapping.
+We will list any known limitations of the translators in the [limitations](#limitations) section below
+
+## Usage
+If using Linux or a Mac, make sure xsltproc is installed by running
+```bash
+xsltproc
+```
+Then transform your file(s) with
+```bash
+xsltproc [-o <output>] <stylesheet> <file> [<file> ...]
+```
+Where `-o <output>` can optionally be included to save the result, `<stylesheet>` is the path to the desired `.xsl` file, and `<file>` is the path to the file you'd like to transform.
+
+If on Windows, either find another XSLT processor or use an online processor.
+
+## Limitations
+### v2 to v3
+There are no known limitations.

translation/v2_to_v3.xsl

@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+
+XML Stylesheet Language Transformation (XSLT) to transform BuildingSync from v2 to v3
+
+Version: 0.1.0
+
+-->
+
+<xsl:stylesheet version="1.0"
+	xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+	xmlns:auc="http://buildingsync.net/schemas/bedes-auc/2019"
+	xmlns:xs="http://www.w3.org/2001/XMLSchema"
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	exclude-result-prefixes="xs">
+
+  <xsl:output method="xml" encoding="UTF-8" indent="yes"/>
+
+  <xsl:template match="/">
+    <xsl:comment>This BuildingSync v3.0 document was generated from a BuildingSync v2.X document via an XML Stylesheet Language Transformation (XSLT).</xsl:comment>
+    <xsl:text>&#10;</xsl:text>
+    <xsl:copy>
+      <xsl:apply-templates/>
+    </xsl:copy>
+  </xsl:template>
+
+  <xsl:template match="@* | node()">
+    <xsl:copy>
+      <xsl:apply-templates select="@* | node()"/>
+    </xsl:copy>
+  </xsl:template>
+
+  <xsl:template match="@xsi:schemaLocation">
+    <xsl:attribute name="xsi:schemaLocation">http://buildingsync.net/schemas/bedes-auc/2019 https://raw.githubusercontent.com/BuildingSync/schema/v3.0.0/BuildingSync.xsd</xsl:attribute>
+  </xsl:template>
+
+  <xsl:template match="@auc:version">
+    <xsl:attribute name="auc:version">3.0.0</xsl:attribute>
+  </xsl:template>
+
+  <!-- Map "Repair leaks / seal ducts" to "Repair leaks in ducts" -->
+  <xsl:template match="auc:MeasureName[. = 'Repair leaks / seal ducts']">
+    <xsl:copy>Repair leaks in ducts</xsl:copy>
+  </xsl:template>
+
+  <!-- Limit auc:MeasureName to exactly one by commenting out all other auc:MeasureNames -->
+  <xsl:template match="auc:MeasureName[not(position() = 1)]">
+    <xsl:message>WARNING: commenting out auc:MeasureName <xsl:value-of select="current()"/></xsl:message>
+    <xsl:comment>
+      <xsl:apply-templates select="@* | node()"/>
+    </xsl:comment>
+  </xsl:template>
+
+</xsl:stylesheet>