pvcollada

Developer Guide: Using `pvcollada_schema_2.0.xsd`

This guide explains how to use the pvcollada_schema_2.0.xsd XML schema file in the pvlib/pvcollada repository to validate PVCollada XML files. The schema ensures that your PVCollada XML files conform to the structure and enumerated types expected by the PVCollada format.

1. Schema Location

The schema file is located at:

schema/pvcollada_schema_2.0.xsd

This schema imports the COLLADA schema and defines enumerations and types specific to photovoltaic (PV) system design.

2. Schema Basics

The schema imports the COLLADA 1.5 schema (collada_schema_1_5.xsd). PVCollada data use the tags provided by COLLADA to allow extensions. Data described by the PVCollada 2.0 schema *must* be identified by profile="PVCollada-2.0". Example:

	<asset>
		<coverage>
			<geographic_location>
				<longitude>15.3</longitude>
				<latitude>10.1</latitude>
				<altitude mode="absolute">150</altitude>
			</geographic_location>
		</coverage>
		<unit meter="0.01" name="cm" />
		<up_axis>Z_UP</up_axis>
		<extra>
			<technique profile="PVCollada-2.0">
				<!-- software tag -->
				<pv:software>
					<pv:source>Helios 3D</pv:source>
					<pv:target>PVsyst</pv:target>
				</pv:software>
			</technique>
		</extra>
	</asset>

3. Validating PVCollada XML Files

A Python script is provided at schema/validate.py that uses lxml to validate an XML file.
Example usage:

from lxml import etree

XML_FILE_PATH = "../Examples/05 - VerySimpleFixedPVC2_with_electrical_layout.pvc2"
XSD_FILE_PATH = "pvcollada_schema_2.0.xsd"

with open(XML_FILE_PATH, "rb") as xml:
    xml_doc = etree.XML(xml.read())
with open(XSD_FILE_PATH, "rb") as xsd:
    schema_root = etree.XML(xsd.read())

schema = etree.XMLSchema(schema_root)

if schema.validate(xml_doc):
    print("XML is valid.")
else:
    print("! XML is invalid.")
    for error in schema.error_log:
        print("  -", error.message)

This validation is only a basic check for consistency against the schema. More extension validation can be done using schematron. The PVCollada repository includes a GitHub Actions workflow:
.github/workflows/validate_xml_with_xsd_and_schematron.yml

This workflow automatically validates the example PVCollada XML files on every push or pull request affecting relevant files.

Key steps:

Installs Python and lxml.
Checks out the schema and example XML files.
Runs the validation script.

4. Example XML File

Example XMLs are found in the Examples/ directory.
Example:
Examples/05 - VerySimpleFixedPVC2_with_electrical_layout.pvc2

5. Extending the Schema

You can add custom elements to a PVCollada file. To do so:

create a schema (xsd) for the custom elements.
choose a namespace identifier. The namespace identifier must be unique within a PVCollada document.

choose a profile for the custom technique. The profile must be unique within a PVCollada document. The custom technique is added inside blocks, in parallel with the "PVCollada-2.0" technique. For example, PVsyst adds tags using schema https://www.pvsyst.com/pvcollada-2.0-extensions, namespace pvsyst, and profile "PVCollada-2.0-PVsyst".

<COLLADA xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:pv="http://www.example.com/pvcollada" 
  xmlns:pvsyst="https://www.pvsyst.com/pvcollada-2.0-extensions"
  version="1.5.0" 
  xmlns="http://www.collada.org/2008/03/COLLADASchema">	
  <asset>
      <coverage>
          <geographic_location>
              <longitude>15.3</longitude>
              <latitude>10.1</latitude>
              <altitude mode="absolute">150</altitude>
          </geographic_location>
      </coverage>
      <extra>
          <technique profile="PVCollada-2.0">
              <!-- software tag -->
              <pv:software>
                  <pv:source>Helios 3D</pv:source>
                  <pv:target>PVsyst</pv:target>
              </pv:software>
          </technique>
          <technique profile="PVCollada-2.0-PVsyst">
              <pvsyst:tag specific to PVsyst/>
          </technique>
      </extra>
  </asset>
</COLLADA>

6. References

7. Troubleshooting

Make sure all XML files reference the correct schema location and namespace.
If validation fails, review the error messages—they typically indicate the offending element or attribute.
For more information, see the lxml documentation.

Note: This guide is based on a partial code search. For more details, explore the pvlib/pvcollada repository.

This site is open source. Improve this page.