Technical Resources

Guides

File Validation

For validation of BuildingSync XML files, the XML file undergoes a two step validation process (see Validation Using OxygenXML for an example).

  1. Validation against an XML XSD document

    • Download the most recent version of the schema and use an XML authoring tool to validate the XML instances.
    • XSD's are used to validate:
      • Elements and attributes that may appear in an XML document
      • Whether elements are required and how many are allowed
      • Whether attributes are required
      • Number and order of children
      • Data types for elements and attributes
      • Defaults and fixed values for elements and attributes
  2. Validation using Schematron

    • Example BuildingSync schematron documents can be found in the BuildingSync Use Cases GitHub repository. XML authoring tools can be used to validate against Schematron docs.
    • As opposed to an XSD, a Schematron document can be used to validate:
      • Elemental requirements on a use case basis. For example, requirements for ASHRAE Levels 1, 2, and 3 are different. Using the same base XSD, with three different Schematron documents (one for each ASHRAE level), validates whether the document expresses all of the requirements to achieve each of the ASHRAE Level 1, 2, and 3 use cases.
      • Constraints and requirements based on conditionals. For example, if an element is specified with a particular value, the applicable enumerations of another element may change.
      • other logical statements.

Usage of both validation approaches (XSD and Schematron) is recommended for developers actively working on creating BuildingSync files.

Additionally, there is an option to add a valid BuildingSync XML to the schema's continuous integration (CI) system. This will allow for the file to be tested during schema change/pull requests to ensure backward compatibility and validity. To add a BuildingSync instance to the CI, follow these steps:

  1. If you do not have a GitHub account, then sign up for one on GitHub
  2. Sign into GitHub and navigate to BuildingSync Schema's GitHub page
  3. Fork the repository and add new files to the examples folder
  4. Create a pull request which will trigger the validation workflow. If it passes, then the BuildingSync team will accept the pull request after reviewing the changes. If it does not pass, the BuildingSync team will work with you to understand the issues. Note: The new file will be validated on every commit/change to the BuildingSync schema ensuring that all provided user's files pass successfully and are backward compatible.

Validation Using OxygenXML

Clone the BuildingSync/schema repository locally, and open the following files:

open files

Validation Against XSD

Using the OxygenXML Validate button, the Valid Schema shows a valid result against the XSD:

valid schema

For the invalid schema, we can see all of the errors found, with descriptions:

invalid schema example 1
invalid schema example 2

Validation Against Schematron

Download the Schematron document Audit Template Example and save to a known local path.

In OxygenXML, choose the validate drop down, and select validate with:

schematron validation 1
schematron validation 2

The Schematron validator will provide very verbose errors specific to the use case. Note that schematron will generate errors on both the 'BuildingSync Website Valid Schema.xml' and 'BuildingSync Website Invalid Schema.xml' documents, because while these are valid according to the XSD, they do not conform to the use case requirements:

schematron validation 3