DDL Schema Validation

Using DOMCount to validate DDL files

The geometry files in CMSSW not only have to be in XML format, they also have to conform to specific requirements that are specified in the CMS geometry schema. This schema defines the Detector Description Language (DDL) used in the CMS geometry. The schema is defined in the file DetectorDescription/Schema/DDLSchema.xsd.

DOMCount is an executable from the Xerces-C examples. One thing that DOMCount does is check that the XML files it processes conform to the schema.

Running DOMCount Over All the XML Files in a Scenario

Here is how to run DOMCount over all the XML files in a scenario:

cmsrel CMSSW_5_0_0
cd CMSSW_5_0_0/src
cmsenv
addpkg DetectorDescription/RegressionTest
setenv LOCAL_TOP_DIR $CMSSW_BASE
DetectorDescription/RegressionTest/test/run_DOMCount.py Geometry/CMSCommonData/cmsIdealGeometryXML_cfi

./DetectorDescription/RegressionTest/scripts/domcount.sh > domcount.log

The script above uses release 5_0_0 only as an example. It has been tested with releases 3_5_0 to 3_10_0_pre2 and will probably work for even earlier and later releases.

The line in the example above "cvs update -A DetectorDescription/RegressionTest/test/run_DOMCount.py" is not necessary in releases 3_10_0_pre1 and later. The file will already be there. (Even though the script run_DOMCount.py does not exist in earlier releases, it works in earlier releases.)

WARNING: Do not run run_DOMCount.py from a directory that contains the xml files because this script copies the xml files to the current directory, modifies them, and then deletes them.

You can check out other packages and modify xml files, xsd files, and cfi files. Make sure to use "scram b" after checking out any packages with cfi files. This script correctly selects the files from the working area if the package is checked out and from the base release if the package is not checked out. This allows one to test modifications, not just the geometry in the release.

The example above tests the xml files included in Geometry/CMSCommonData/python/cmsIdealGeometryXML_cfi.py. By modifying the argument passed to run_DOMCount.py you can test the xml files for other scenarios. Here are some of the other choices currently available:

Geometry/CMSCommonData/cmsExtendedGeometryXML_cfi
Geometry/CMSCommonData/cmsExtendedGeometryGFlashXML_cfi
Geometry/CMSCommonData/cmsExtendedGeometryLiMinXML_cfi
Geometry/CMSCommonData/cmsExtendedGeometryLiMaxXML_cfi
Geometry/CMSCommonData/cmsExtendedGeometryX0MinXML_cfi
Geometry/CMSCommonData/cmsExtendedGeometryX0MaxXML_cfi

You can determine if errors occurred by looking for the string "Error" in the output. If no errors occur, then the output will only contain one line like the following for each xml file.

cmsMuon.xml: 6 elems.

Running DOMCount on a Single XML file.

DOMCount can be run directly on individual files.

cmsrel CMSSW_5_0_0
cd CMSSW_5_0_0/src
cmsenv
addpkg DetectorDescription/Schema
cvs co Geometry/CMSCommonData
cd Geometry/CMSCommonData/data
DOMCount -n -s -f -v=always cmsMuon.xml

Release 5_0_0 is just used as an example. This should work in other releases. The Schema package should always be checked out, but the other package that needs to be checked out is the one that contains the xml file you want to test.

You can determine if errors occurred by looking for the string "Error" in the output. If no errors occur, then the output will only contain one line like the following.

cmsMuon.xml: 6 elems.

There is one quirky thing to be aware of when testing individual files. Each xml file contains the relative path to the schema file. It looks something like this:

<DDDefinition xmlns="http://www.cern.ch/cms/DDL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.cern.ch/cms/DDL ../../../DetectorDescription/Schema/DDLSchema.xsd">

In many xml files the relative path is incorrect (someone should fix this someday). The script named run_DOMCount.py is smart enough to correct these errors, but when running on individual files you may or may not have to correct this path in the XML file to get DOMCount to work.

What do errors look like?

Some of the common errors and their fixes are

• Providing a wrong relative path for the DDLSchema.
• Violating order of internal elements.
• Violating uniqueness key constraints.
• Missing required elements or attributes.

Wrong relative path.

Errors on every line and start with the following error.

DOMCount output

Warning at file , line 0, char 0
  Message: An exception occurred! Type:RuntimeException, Message:Warning: The primary document entity could not be opened.
  Id=*whereItExpectsToFind*/DDLSchema.xsd

Error at file *fullPathToYourFileNameHere* line N, char CCCC
  Message: Unknown element 'DDDefinition'

Solution

The XML files should all contain a relative path to the DDLSchema.xsd file. The errors above will occur if the path is incorrect. There are some xml files known to have an incorrect path, but it is known that this particular class of errors is harmless. When using the script run_DOMCount.py these harmless errors will get fixed automatically and you will never see them in the output. If you are running DOMCount on individual files the errors will appear in the output. In that case you should probably run the script to make sure the errors are of the harmless type. (You can also fix the path locally without checking in the fix and that will be enough to get DOMCount to run). When someone has some spare time we should probably fix all those errors ...

Violating order of internal elements.

The following snippet will fail validation although the DDD does process it correctly.

 <PosPart copyNumber="1">
   <rChild name="muonBase:MB"/>
   <rRotation name="rotations:000D"/>
   <rParent name="muonBase:MUON"/>
 </PosPart>

The error will look horrible because of my attempt to allow more than one way of defining the PosPart's content.

DOMCount output

Error at file /build/case/dddwork/validation/CMSSW_3_4_X_2009-10-20-0100/src/Geometry/CMSCommonData/data/muonMB.xml, line 9, char 12
  Message: Element 'rRotation' is not valid for content model: '(((((rParent,rChild)|(rChild,rParent)),(Translation|(ARotation|rRotation)|
  rReflectionRotation))|((Translation,rParent,((ARotation|rRotation)|rReflectionRotation|)),rChild))|
  ((((ARotation|rRotation)|rReflectionRotation|),Translation),((rParent,rChild)|(rChild,rParent)|)))'

Errors occurred, no output available

Solution

Fix the order. Look at other XML files as example, or check the DDLSchema itself (TO DO: Ideally I should generate a canonical example of each element.).

 <PosPart copyNumber="1">
   <rParent name="muonBase:MUON"/>
   <rChild name="muonBase:MB"/>
   <rRotation name="rotations:000D"/>
 </PosPart>

Violating uniqueness key constraint.

For example here, I defined two LogicalParts named World. This example demonstrates why it is important to run DOMCount as well as other validation tools. The Detector Description, in order to provide unique LogicalParts quietly overwrites the existing part with the second part in the C++ code. By checking with DOMCount outside of the cmsRun application we can catch such accidental mistakes.

DOMCount output

Error at file /build/case/dddwork/validation/CMSSW_3_4_X_2009-10-20-0100/src/Geometry/CMSCommonData/data/cms.xml, line 106, char 51
  Message: Duplicate key value declared for identity constraint of element 'DDDefinition'.

Errors occurred, no output available

Solution

Check the file on the line specified, decide which one is wrong or accidental and repair or fix the file by renaming the LogicalPart or deleting lines.

Missing required elements or attributes.

It is essential that some attributes or elements are part of an element being processed. That is that it contains other elements or it has required attributes. For example, a LogicalPart must have a Solid.

So this would be wrong:

 <LogicalPart name="OCMS" category="unspecified">
  <rMaterial name="materials:Air"/>
 </LogicalPart>

DOMCount output

Error at file /build/case/dddwork/validation/CMSSW_3_4_X_2009-10-20-0100/src/Geometry/CMSCommonData/data/cms.xml, line 109, char 16
  Message: Not enough elements to match content model : '(((Solid|rSolid),(Material|rMaterial))|((Material|rMaterial),(Solid|rSolid)))'

Errors occurred, no output available

Solution

Include the missing element (or attribute). Check other existing XML files as a model (TO DO: again, a set of examples would be great).

 <LogicalPart name="OCMS" category="unspecified">
  <rSolid name="OCMS"/>
  <rMaterial name="materials:Air"/>
 </LogicalPart>

Review Status

Responsible: IannaOsborne
Last reviewed by: