Menu
One of the greatest strengths of XML is how flexible it is as a data format. It has a few simple rules that must be followed – like nesting and case sensitivity, but otherwise XML can be used to create documents of any size and complexity required for a given task.
Unfortunately, the flexibility of XML can also be a serious challenge when it needs to be shared amongst different departments or businesses. XML is only useful as a format when all parties know what rules an XML document is going to follow beyond those imposed by the XML format. Rules like element names – and which elements are repeating elements versus those which are only allowed to be used once serve as an example. If you don’t have a commonly agreed upon standard for what your XML will look like, it makes it exceedingly difficult to write programs to produce or consume that XML. Imagine trying to talk to someone on the phone who only speaks French when all you know is English! To effectively use XML as a communication format, we have to have agreed upon rules, and we have to communicate those rules to everyone who’ll work with our XML.
Many times, companies that offer web services rely on documentation alone to provide guidance to those consuming them. While this is certainly preferable to a completely undocumented web service, it’s not inherently guaranteed to be synchronized with the web service. Keeping an external document matched up with a web service (especially a complex one) can be a real chore. The worst part is that no matter how good your process is, it’s only as perfect as those performing it. Eventually, despite all the reviews your documentation goes through, a typo will slip through somewhere, or a change to the code won’t be properly reflected in the documentation. Eventually you’ll cause some poor developer trying to work with your web service to have a real headache while attempting to figure out why your documentation is leading them astray. Without naming names, let’s just say this has forced me to keep a bottle of Advil near my desk!
Thankfully, there are better options! The XML Schema Definition, or XSD, allows you to clearly lay out rules an XML document must follow to be considered valid. It gives you the power to denote fields which should only contain numeric values, fields which are required as opposed to optional, and much more. The ability to specify data types is what puts an XSD above the other alternatives which try to perform the same task, like DTD. When you make an XSD the authoritative source for rules about your XML structure, it drastically limits the influence of human error. Similarly, because XSD is a W3C standard, you can be confident that it will be interpreted in the same way by everyone using it. A full discussion of the XSD is beyond the scope of this blog post, but suffice it to say that they’re a very powerful tool. In conjunction with a properly constructed WSDL, an XSD can make implementing a new web service a piece of cake.
The real power of an XSD is that the rules they represent they can be “run” against an XML document, letting you give that XML document a pass or fail grade depending on whether it met all the rules you designed. If you’re building XML prior to communicating with a web service, you can validate your XML against an XSD to find out if you’ve done things properly before you send a single byte of data. Similarly, if you’re hosting a web service you can move your validity checking logic into the XSD, and run XSD validation on each incoming request. Doing this ensures that both you and the client are operating off the same set of rules, which should avoid many implementation problems entirely.
To determine whether or not a specific XML document conforms to all the rules of an XSD is an easy task to perform in most languages and operating systems. I’m very excited to say that RPG API Express 3.11 adds a new API for IBM i to do this called RXS_Validate().
Without getting too technical, RXS_Validate() allows you to pass in an XML document, an XSD document, and a configuration data structure. The API will perform an XSD validation check, and then return an *On or *Off value depending on whether or not the XML passed validation. If it didn’t pass validation, the configuration data structure will contain a short message explaining what part failed.
Below is a short code sample. In it, we’re retrieving some sample XML and then passing RXS_Validate() an XSD file located on a remote web server. We could also place the XSD in the IFS or even simply within a character variable.
/*
H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)
/copy QRPGLECPY,RXSCB
D XsdValidateDS DS LikeDS(RXS_XsdValidationDS_t)
D Inz(*LikeDS)
D request S Like(RXS_Var64Kv_t)
D Xml S Like(RXS_Var64Kv_t)
/FREE
// Get good XML to test validation
reset TransmitDS;
TransmitDS.Uri =
'http://files.katointegrations.com/example/xsdvalidate/success.xml';
TransmitDS.HTTPMethod = RXS_HTTP_METHOD_GET;
Xml = RXS_Transmit( *Omit : TransmitDS );
// Test validation against URI (Expected Success)
reset XsdValidateDS;
XsdValidateDS.XsdLocation =
'http://files.katointegrations.com/example/xsdvalidate/validate.xsd';
if RXS_Validate( Xml : XsdValidateDS );
RXS_JobLog( 'XML Validated successfully');
else;
RXS_JobLog( 'XML Validation failed');
RXS_JobLog( 'Validation Error %s: %s'
: %Char( XsdValidateDS.ValidationErrorCode )
: XsdValidateDS.ValidationErrorText );
endif;
*INLR = *ON;
/END-FREE
*/
If XSD validation is a feature you’d like help implementing within your code or if you simply have questions relating to your specific requirements, feel free to contact us here!
Start putting the power of XSD validation to work within your web service communications today!