Getting Started / Helpful Guides
Validation Methods and Tools
For validation of BuildingSync XML files, the XML file undergoes a two-step validation process.
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.
- XSDs 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
-
- 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.
- Validation against XSD for general correctness and usage of BuildingSync
- Validation against Schematron for understanding XML document requirements for different use cases
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:
- If you do not have a GitHub account, then sign up for one on GitHub
- Sign into GitHub and navigate to BuildingSync Schema's GitHub page
- Fork the repository and add new files to the examples folder
- 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.
New Users
"I have a BuildingSync file, but I do not know if it is valid and/or will work for my use case." - Use the Validator Tool to validate the file against the BuildingSync schema and all published use cases
Application Developer
"I have an application that I want to build and I would like to validate the incoming BuildingSync schema automatically." - Set up an automated validation workflow through the Validator API and/or a Python package
BuildingSync Developer
"I want to update BuildingSync and I need to test examples" - Use any XML&XSD editor to modify the BuildingSync schema; create and edit the BuildingSync XML instance and validate the XML files against the schema
Available third-party tools: