0

First is I'm starting to build a standard XML format/structure for our users. The objectives are:

  • XML that can be used for multiple organisations
  • XML that can be used to map external system data to our system data
  • XML structure should be in best practices
  • XML should be adaptable to change

The above are the objectives, so our initial structure, users XML, would look like this:

<users>
    <user>
        <firstName></firstName>
        <lastName></lastName>
        <email></email>
        <!-- .. some user child node here -->
    </user>
</users>

So I'm thinking what if this structure grows which might have different objects associated to user something like:

<users>
    <user>
        <firstName></firstName>
        <lastName></lastName>
        <email></email>
        <element1>
            <child1></child1>
        </element1>
        <element2>
            <child1></child1>
            <child2>
                <innerChild1></innerChild1>
            </child2>
        </element2>
    </user>
</users>

Then I would have to implement urn namespace to uniquely identify same named <element>. This is where namespace is useful.

My questions are:

  • Do I have to implement namespace by having it implemented on the initial XML sample?
  • When to use attribute instead of creating elements as child node?
  • Best practices that I could use for our XML to be adaptable to change?
  • What are the things I should prevent when building or structuring XML?

Note: we are using XML instead of JSON because most of our users use XML.

  • 1
    What is your intend? Designing XML structures is not an end in itself, it is a means to an end - so what is your use case for these XML structure? – Doc Brown May 18 '17 at 16:30
  • Are you considering defining all of this in a proper schema (XSD)? I really recommend that. It allows you to distribute a data definition without needing to worry about "initial XML sample" that you mention. Also, many automated tools can generate code from XSDs. And you can use an XSD to validate an XML. – FrustratedWithFormsDesigner May 18 '17 at 19:08
  • As far as adapting to change, there are a number of things you can do. One thing I might recommend is versioning your data schemas, and requiring the XML document to contain a "version" attribute on the root element. This allows you to handle multiple versions of you schema. – FrustratedWithFormsDesigner May 18 '17 at 19:10
  • @FrustratedWithFormsDesigner Yes, I will be defining this in a schema. – rpmansion May 19 '17 at 1:14
4

Honestly, my answer would initially be: don't use XML. I've been working with XML for many years and the reality is that it's a terrible format for data exchange. JSON has it's own flaws but it is much better. XML is actually not a bad way to create documents but even that usage is being replaced with HTML5.

However, given that you are 'forced' to do this, here's my list of recommendations:

XML

  • XML Namespaces suck to deal with but if might need them, you are better off using them from the start. Retrofitting them in is a huge pain in my experience.
  • Use attributes only for metadata. Elements are much more powerful. When something you thought was simple becomes complex, it is still an element. An element can also be more than one thing depending on the context.
  • Never ever ever allow mixed content. That is, don't allow text nodes and child elements as content at the same time. It's either or.
  • Do not allow entity references. This is a serious security risk.
  • Declare all namespaces in the root and use prefixes. Putting namespace declarations on every element will add a lot of bloat to an already bloated document.
  • Remove all whitespace if you are doing any sort of encryption or signatures.

XSD

  • Forget all the stuff about salami slices and venetian blinds. Create element definitions at the schema level only for those things that you want to use as the root of a document. Everything else should a type.
  • Use sequences pretty much always. Choice elements can be useful but complicate things.
  • Do not specify nillable="true". Use minOccurs="0". The element is there with a value, there and empty, or is not there. Introducing null values at the interface level is a bad idea.
  • You can't say things like "at least 2 of the following three options" in XSD without getting nutty. Let it go and move on.

I will add more if I can think of anything.

  • I don't even want to use XML if it was not because our users use XML rather than JSON. I'm also considering a JSON version for this as an alternative and for the future organizations that would need integration between their system to our system. – rpmansion May 19 '17 at 1:16
  • 1
    @rpmansion Right I saw your reason for using it which is why I gave you my recommendations. If you want to create a JSON version of this, you might want to start with JSON and then back-port it to XML. JSON is more syntactically simple (which is it's advantage in this case.) It's possible to build XML structures that cannot be directly translated to JSON or are awkward. Being a little passive-aggressive about it and pointing out that you have XML simply to support 'old' ways of doing things is probably OK here. – JimmyJames May 19 '17 at 14:55
1

1) Name spaces are not required. For a simple project, just keep it as simple a s possible. Use name spaces when your project grows larger, and when you need several xml formats where there is a risk of name clashes.

2) The pros and cons between elements and attributes are subtle. Don't worry if your project is still small.

3) 4) Just keep your xml as simple as possible.

When you have created a working system and gained some experience, you might rethink the xml structures. If you worry too much now, you will get stuck.

You might also google on the risks of "premature optimization".

Good Luck!

  • The OP stipulates that this should be usable by multiple organizations. Not using namespaces for this may be problematic. – JimmyJames May 18 '17 at 20:55
  • @JimmyJames Right. May. Or may not. I have seen lots of xml without namespaces used by mult. orgs. without problems. If you worry too much at the start of a small project, you may get stuck. – Roland May 18 '17 at 20:57
  • 1
    The problem starts when someone what's to generate code from the schema. Have been through going without namespaces and then having to add them in, I've decided it's worth it to start with them. It's much less painful. At a high-level, I agree with you but a lot of people can't/won't work with XML without code generation. – JimmyJames May 18 '17 at 21:29

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.