Working with XML and XSD schemas in Visual Studio

I recently started working with XML files as part of a SharePoint project I was working on in Visual Studio. As the project evolved, I started creating some crazy XML files that defined the structure of a SharePoint site. It wasn't long before the crazy schema I invented on the fly started become confusing. Worse, I started forgetting the structure of the elements I had invented and had to start looking through the source code that processed it to try to remember what the structure and options were supposed to be.

Better solution: Create an XSD file with the structure definition in it. Basically, I followed these steps.

1. Reverse engineer the XSD from my XML file
2. Annotate the XSD file with some documentation about what it all meant
3. Add a reference to the XSD in the XML file
4. Continue editing the XML file in Visual Studio

Reverse Engineering the XSD 
First step was to create an XSD. I didn't want to type it all by hand, so I found this link: http://www.dotkam.com/2008/05/28/generate-xsd-from-xml/. It referenced a tool called "Trang" which processes and XML file and produces an XSD. Download it here.

I created a simple batch file:

@echo off
: Batch file to invoke Trang to convert an XML file to a XSD
set JAVA_HOME=C:\apps\jdk1.6.0_20
set TRANG_HOME=C:\apps\trang
%JAVA_HOME%\bin\java.exe -jar %TRANG_HOME%\trang.jar %*

 Then I converted my existing XML file:

xml2xsd.bat myFile.xml schema.xsd

And it produced a reasonable XSD file that I could begin using. What's nice, is if you load this file into Visual Studio, it provides some nice tools for exploring and viewing your schema. (I have NOT found any good ways for actually editing the schema other than hacking on the XSD code.)

Annotate XSD Schema

Once you get the basic XSD file, it's nice to add some explanation to it. You can easily use the "xs:annotate" and "xs:documentation" elements to do that.

<xs:annotation>
<xs:documentation xml:lang="en">
Documentation about your element.
Hint: First line is shown as "documentation"
<xs:documentation>
<xs:annotation>

This allows you to self-document the XSD file so you can look at it later and remember what the hell you were thinking when you first made it. It also has the added benefit of showing up when you turn on "Show Documentation" in Visual Studio Schema Model view.

A quick note on Visual Studio: When you open an XSD file in Visual Studio, it shows you the "XML Schema Explorer." From there, you can select elements and "Show in Content Model" which allows you to expand elements and browse through your schema. There are other modes, too, but I haven't figured them out.

Add Reference to XSD in XML File

Once you have an XSD, it's nice to actually make use of it. You can do this by annotating the root element in your XML file:

<RootNode  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="MySchema.xsd">

This allows anything processing the XML file to actually find the XSD and determine whether your XML file is "correct."  In my case, my XSD file was in the same directory as the XML file, so I didn't have to post the XSD anywhere.

Continue Editing XML File in Visual Studio

After doing all this, you're back to editing your XML file. The nice side effect of all this in Visual Studio is that it activates Intellisense for XML editing. This means:

1. It will suggest name completion as you start typing elements and attributes
   
2. It will suggest elements and attributes that can be inserted in a location
3. It will suggest errors when you type elements that don't exist

I immediately found that this helped me work with my XML files much more quickly without creating bad formatting errors.