This project has moved. For the latest updates, please go here.

Base type from included schemas not linked to the parent elements

Topics: Questions
Jun 5, 2009 at 5:17 PM
Edited Jun 5, 2009 at 9:53 PM


In XSD Documenter, for schemas which only present the interface schema ("face schema") and are deeply nested using includes from a hierarchy of base types which are in turn inherited from other includes

(see slide 13 in http://www.docstoc.com/docs/2706130/Introduction-to-OpenTravel-Schemas)

the XSD documenter generates only the face schema as a single element and any elements which are derived from base types are not presented as child types of the face schema master element(s). Instead they are presented as "Elements" and "CompexTypes" in the tree view in a technical documentation.


.When you work with a nested schema (linked with included which could be a few levels deep), the types from the parent schemas don't expand to the child elements which are declared and defined in the included schemas. This is a serious drawback as business users who don't know XSD cannot be expected to click "AttributeGroups", "SimpleTypes" and "ComplexTypes".

What I would really like is the XmlSpy type of nested treeview which expands the types from the parent schemas into the child elements even though the child elements are declared and defined in another include, which could be using further base types from a more deeply nested include, and so on...

[ I am working with Open Travel schemas (www.opentravel.org - download specifications).  They are nested 4 levels deep and inherit types from the base includes.]

How can I create a Business Data Dictionary instead of Technical documentation of "Elements" / "CompexTypes" / Attributes / etc where the includes complexTypes are presented as child elements of the master element in the treeview?

Jun 5, 2009 at 9:53 PM
Edited Jun 5, 2009 at 10:00 PM

Forgot to say Thanks! for this wonderful plugin. I am quite grateful for it, but this is how it can be improved:

All the XSD documenters out there seem targeted at Technical folks (generates namespaces, "AttributeGroups", "SimpleTypes" and "ComplexTypes" etc which scares away the business analysts ) , but we need a XSD documenter for business people. This is how we can keep the XSDs and the Data Dictionaries in synch (and have to update any external Data Dictionary separately which often gets out of synch in this manual process).

One such is available at www.pilotfish-net.com as in

http://adriatic.pilotfish-net.com/ota-modelviewer/

but the company wants $10,000 for it (when contacted as they don't sell it directly)

 

Jun 10, 2009 at 3:34 PM

I'm happy to work with you on this (I see you have a bit of a budget). But I'd suggest a different approach. Essentially your problem is that you need to document the schema component model, rather than the raw schema documents. Building the SCM from the raw documents is a lot of work, and doing it in XSLT is not that easy. Instead, take a tool that already builds the SCM (Saxon comes to mind!) and work from that. Contact me off-list if interested. Michael Kay (mike at saxonica)

Coordinator
Jun 12, 2009 at 9:37 AM

Hi CodeCola,

thank you very much for taking the time giving feedback.

At our company we face the same problem you mentioning. XSDDoc produces XML reference documentation that is more targeted to those who want to understand the schema structure as opposed to the modelled XML.

Although I know that this does not mean that I can easily fix it. I would prefer having an option that produces documenation that only contains namespaces, elements and attributes as these are the only publicly visible XML entities. I would prefer making this optional as this only applies if you want to use the schema to write an XML document - if you want to extend the schema or use it information after validation inside your app things you still need the full details.

However, this is not as simple as it sounds. Purging groups and named types from the schema requires "inlining" their usages. Inlining has the downside that the amount of generated topics can be quite large (at the end, you need a topic for every namespace, element, and attribute). In addition, not every type can be easily inlined. For example, if types are somehow recursive (keep in mind that they can be even indirectly recursive) the question is how this becomes visualized in the table of contents.

But goods news is that if you have control over the schema you can create documenation that is very close to a "Business Data Dictionary" by only using global elements and avoiding named complex types altogether. That is the approach the Windows Installer XML (WiX) team has chosen. The WiX documentation is part of the samples; have look - I think it is very easy to understand and should match your expectations.

As I understand from what you said you do not have control over the schema. Although the upcoming release will still document groups and types I have included a couple of options to reduce "the noise":

  • You can separately disable documentation for schema files, root schemas, and root elements
  • You can disable the generation of the syntax sections
  • You can disable the documentation of elements constraints (xs:unique, xs:key, and xs:keyref)
  • You can disable the creation of a namespace toc entry if you only have a single namespace

Hope this helps.

Best,
Immo

Jun 15, 2009 at 10:59 PM

Immo,

Thanks for your response. I could not understand your WIX angle at all!

It seems this problem is deeper and thornier than I first thought. I have been talking to Michael Kay (XSLT guru) and he outlined why....I have captured the issue in my blog post here. Please download the attachment at the end (SchemaModelDocumenter.doc)  look at the last page - Approaches to the Solution.

Have you heard of Saxonica before? This might be the best tool to model the schema, and I will most likely have to purchase it for this project.

I would like to hear your thoughts and any other angles you may have on this.

Coordinator
Jun 16, 2009 at 5:13 AM

Hi CodeCola,

sorry about the confusion regarding the WiX example. The current samples include the documentation of the XML schemas for the Windows Installer XML (WiX) toolkit. The WiX help file does not contain groups, attribute groups or complex types. The reason is that the XSD schema has been written that way (they only used global elements). This schema design is typically called salami slice.

The benefit is that the resulting CHM file is very close to what (as far as I have understood) you want to achieve. The downside of this approach is that this only works if you have control over the schema. Nobody really wants to manually re-write an existing XSD file just to have a nicer documentation (which is the case with your schemas).

As far as I have understood the approach you mentioned in the word document you want to use a tool produced by Saxonica to reverse engineer that kind of salami sliced XSD. I think that is an interesting approach. In the meantime I have thought about how to inline complex types and I think that it is doable - although non-trivial. I think I will address this issue in one of the next releases.

Best,
Immo

Marked as answer by terrajobst on 2/15/2014 at 6:18 PM