root_reference and displayroot_reference

If you import a schema into BizTalk, you may get something in the schema editor that looks much different than something you'd get building one in the editor yourself. When you build a schema using the schema editor, you get a statically-defined schema - definitions of nodes exist "in place." This is great for simple schemas, but many more complex schemas rely on more powerful organizational structures made available by the XSD schema language to create more organized and extensible schemas.



This schema is defined structurally - definitions of structures (records, elements, attributes) are all made at the root level and then "referenced" to create the document structure. This is similar to how a DTD is defined - a "root node" exists only incidentally, because its at the top of the reference chain. This type of schema definition can be capitalized on by using complex, named structures to create extremely large and complicated schemas that can be extended very easily. Some industry-standard schemas are so large and well-defined that they actually resemble an inheritance tree that you'd see in an object-oriented language - structures inherit from other structures and are substituted in at various places in the schema as reusable types. Take a look at the documentation for Siemens' version 6.0.2 PLM (Product Lifecycle Management) XML schema standard (warning: The target of that link is an enormous piece of documentation, so large it is capable of crashing browsers). If you download the schemas and take a look at them, you'll see that they are defined in a way similar to how you'd define a tree of classes - classes inherit from other classes, and subclasses can be substituted wherever a parent class is referenced. By defining the schemas in this way, they can be extended infinitely despite their enormous size and scope, and they are very flexible.

In any case, its enlightening to look at a schema this way, but for many tasks it can be a pain. If you just want to take a look at the structure of the schema and verify a few things, it's easier to view it as a proper schema with a single root node. The tools provide a way to fix this and show a "normalized" view of the schema: root_reference and displayroot_reference.

With your schema open, click the top level "Schema" node in the schema editor and take a look at the Properties pane. In the Reference group, one of the available properties is "Root Reference," which provides a drop-down from which you can pick any of the records defined at the top level of the schema. I set this to "Document", which is the root node of my schema.

You can see the result in the schema snippet above: the schemaInfo element gets a new attribute, root_reference. What's not well documented is exactly what this does - by setting the root_reference to the root node of your schema, the view of the schema in the mapper tool will be corrected. If I was to take this schema right now and load it into a map, I'd see the simpler view of the schema. There is a little-documented, manual way to fix the view in the schema editor as well: open the schema file manually using the XML editor, and right next to the root_reference attribute, add another attribute, displayroot_reference, with the same value.

Save and close the schema, and re-open it in the schema editor. The view of the schema is now fixed around the root node, making the schema much easier to view. However, viewing the schema in this way comes with a big caveat. You must be careful when making edits to the schema. If you add an element to a record, what you may be doing under the covers is adding an element to that record's type, changing any other references to that record as well. Things are similarly complicated for all other kinds of edits as well, so tread lightly, be careful what you change, and check the node definition and other node references whenever you make a change. Depending on what you are doing, it may make more sense to work in non-"displayroot_reference" mode, so feel free to switch it on and off. The presence of displayroot_reference does not change the way the schema is parsed or handled by BizTalk at all.

Unlike the BizTalk schema editor tool, many schema tools create their schemas this way by default. Simple schemas that don't take advantage of reusable or substitutable types (and don't even really need to) end up being defined in an obtuse way. root_reference and displayroot_reference provide a way to cut through that definition and provide a simpler view of both a schema definition and a map.