How to write XML?

So, you make a convoluted XML spec which is way OTT and uses SOAP and https and god else knows what.

And then you try your hardest to fool people trying to work with it... Lets say you have part of the headers contain some IDs, e.g. a "Requester" and "Responder". For a start, they cannot be simple attributes they have to be a RequesterParty with a Party in that and a PartyIdentification in that and an ID in that and two different name spaces involved...

Finally this "ID" field has a value in the content which is a DUNS number (Dunn and Bradstreet, a unique entity ID). But to know this, the ID has an attribute identificationSchemeName="DUNS". Fair enough it seems.

Except, the RequesterParty/Party/PartyIdentification/ID has identificationSchemeAgencyName="DUNS"
and the ResponderParty/Party/PartyIdentification/ID has identificationSchemeName="DUNS"

Yes, different attributes to mean the same thing on the same field in the same field in a different parent field in the same message.

Then lets make the published schema allow both and have no front end checking. Bury some clues in a huge automatically generated word document as well.

Then lets make it so some requests work fine if both are identificationSchemeName="DUNS" but one specific type of request goes in to a black hole if the Requester side it not identificationSchemeAgencyName. No error, just an Acknowledgement of receipt...

Yep, you guessed it - our favourite telco. Took a week for then to work out what we did wrong.

We aim to learn from this and make the XML interface we plan to publish :-
  • Simple - not unnecessary nesting of nesting of nesting of fields - where the value can only ooccur once make it an attribute with a meaningful name.
  • Easy - one top level name space for it all
  • Helpful - errors that say what we did not like in the message
We'll see how we do...

No comments:

Post a Comment

Comments are moderated purely to filter out obvious spam, but it means they may not show immediately.

ISO8601 is wasted

Why did we even bother? Why create ISO8601? A new API, new this year, as an industry standard, has JSON fields like this "nextAccessTim...