We help IT Professionals succeed at work.

Most appropriate way for adding comments to XSD elements?

8,833 Views
Last Modified: 2013-11-19
I am creating a simple XSD, and need to add descriptions to the elements.  I've seen that the "official" way is to add an <xs:annotation> to the element and then add a <xs:documentation>, but that seems like a lot of wasted work to simply add a description, not to mention difficult to read by humans, e.g.

                    <xs:element name="FirstName" type="xs:string" />
                    <xs:annotation>
                      <xs:documentation xml:lang="en">
                         Persons First Name
                      </xs:documentation>
                    </xs:annotation>

I'd like to have something like

                    <xs:element name="FirstName" description="Persons first name" type="xs:string"/>

There isn't a "description" attribute defined for xs:element, but xs:element is allowed to have "any attributes" described as  "Optional. Specifies any other attributes with non-schema namespace".  .Net 2005 balks at it too.  Is there a standard convention for the attribute to use for comments within an element?

Comment
Watch Question

Information Architect
CERTIFIED EXPERT
Top Expert 2006
Commented:
This one is on us!
(Get your first solution completely free - no credit card required)
UNLOCK SOLUTION

Author

Commented:
Hmmm, close.  If I do that in Studio 2005, I get the warnings "namespace prefix 'doc' is not defined" and "The 'description' attibute is not allowed".

If I add xmlns:doc="something here", the error goes away!!  What should I put for "Something here"?

Gertone (Geert Bormans)Information Architect
CERTIFIED EXPERT
Top Expert 2006

Commented:
well, you have to define the namespace prefix and bind it to a namespace,
you have found that right

whatyou put in the "something right", should be a unique identifier for your schema

this is a good pattern
xmlns:doc="http://www.JohnBPrice.com/schemas/documentation",

you can pick any url you own, in order to make sure the full string is unique

make sure you add this in the root element, so you only have to bind it once

cheers

Author

Commented:
Do I need to put anything at that location?
Gertone (Geert Bormans)Information Architect
CERTIFIED EXPERT
Top Expert 2006

Commented:
no, it is nothing more than a identifier using
the syntax of a url
what is important is that it is a string that you would expect no one els to use as an identifier,
so you could be certain it is unique

cheers

Author

Commented:
Thanks a lot...
Gertone (Geert Bormans)Information Architect
CERTIFIED EXPERT
Top Expert 2006

Commented:
welcome

Gain unlimited access to on-demand training courses with an Experts Exchange subscription.

Get Access
Why Experts Exchange?

Experts Exchange always has the answer, or at the least points me in the correct direction! It is like having another employee that is extremely experienced.

Jim Murphy
Programmer at Smart IT Solutions

When asked, what has been your best career decision?

Deciding to stick with EE.

Mohamed Asif
Technical Department Head

Being involved with EE helped me to grow personally and professionally.

Carl Webster
CTP, Sr Infrastructure Consultant
Empower Your Career
Did You Know?

We've partnered with two important charities to provide clean water and computer science education to those who need it most. READ MORE

Ask ANY Question

Connect with Certified Experts to gain insight and support on specific technology challenges including:

  • Troubleshooting
  • Research
  • Professional Opinions
Unlock the solution to this question.
Join our community and discover your potential

Experts Exchange is the only place where you can interact directly with leading experts in the technology field. Become a member today and access the collective knowledge of thousands of technology experts.

*This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

OR

Please enter a first name

Please enter a last name

8+ characters (letters, numbers, and a symbol)

By clicking, you agree to the Terms of Use and Privacy Policy.