Hendon Publishing - Article Archive Details
Implementation of a LEXS-based IEPD
Written by Aaron Gorrell
The implementation of a LEXS-based IEPD offers significant opportunities and challenges. As discussed in earlier articles, it is during implementation that the potential of a LEXS-based message can be realized. The same code that is used to consume one LEXS-based document can be used to consume all LEXS-based documents. However, during implementation, additional techniques must be used to ensure that a message is both XML and LEXS compliant. The purpose of this article is to discuss these techniques. As with Part II, this article is technical in nature and assumes that the reader has read the previous two articles and has a working knowledge of XML.
One of the greatest strengths of XML is its ability to structure information in sophisticated ways to capture the complexities of real-life data structures. Validation of an XML message ensures that the message is both well-formed and that it conforms to these pre-defined data structures. Two types of conformance validation should be performed with a LEXS-based XML instance.
XML Schema Conformance
Two sets of XML Schema must be used to fully validate a LEXS message: the LEXS schema for the standardized digest and the extension schema for the payload. Accomplishing this requires the use of a technique called “double-pass” validation. In this, the original XML instance is first split into two files: one that contains the digest and the other that contains the payload. Each of these files is then validated against its respective schema. The instance document can be split either manually or automatically.
Manual: Open the XML instance in an editor and locate the element directly beneath the lexs:StructuredPayload element (see Figure 1). This element should be the root element defined in your extension schema. Cut and paste the contents of this root element into a new file and save it with a name indicating that it is the payload. Add the necessary schema header information to the payload file (e.g. prefix declarations) and include the necessary imports. Likewise, save the original file with the payload removed to a new file—indicating in the file name that it represents the digest. Each of these files can then be loaded into a validation tool such as XMLSpy© to ensure conformance to XML rules and corresponding schemas.
Automatic: Using X-Path, the code required to split the message into two files is surprisingly simple. In the sample code posted at http://waterholesoftware.com/index.php?s=55, we use X-Path to find the payload root element. The root element along with its children are programmatically copied to a new file, and the header information is automatically added. Xerces, a Java-based XML validation toolset, is then used to ensure that each file is conformant to XML and respective schemas. The advantage of automatically splitting and validating the instance document is that the software can be used during testing and even during production.
LEXS conformance tests to ensure that each identifier referenced in the payload through the SameAsDigestReference has a corresponding “id” attribute in the digest. Typically, XML validation includes a check between “id” and “ref.” However, the nature of LEXS renders typical validation out-of-scope—meaning that we must be validate this link ourselves. As before, this validation can be done manually by comparing references in the payload with ids in the digest. The software developed for splitting the file can also be extended to validate these references. In the aforementioned sample code, we use X-Path to retrieve all of the SameAsDigestReference elements in the payload. We then compare the ref attribute of each of these elements to ensure that a corresponding id attribute exists in the digest. Note that although we can check to make sure that the id exists, there is no way to automatically ensure that this relationship is an appropriate one. As such, a semantic assessment of the relationship should be included in testing.
Creating an XML Instance
Manual development of an XML instance will help ensure that the XML schema specification meets the data requirements indicated by the user community. Furthermore, an instance often becomes the only documentation developers will actually reference to figure out how to code to the specification. There are a number of best practices that should be considered in developing the instance:
• Automatic Generation: Many XML editors feature the ability to automatically generate an XML instance. This tends to be a bad idea because it does not truly provide the opportunity to test the contents of a schema. And for LEXS-based schema, it is an especially bad idea. A good instance document should be simple to be most beneficial to a developer. Because the digest is overly inclusive and consists of hundreds of elements that are not likely to be referenced in a single document, automatically generating an instance will result in hundreds of unnecessary additional lines in the sample document. Furthermore, the generator will not be able to generate sample XML for anything in the payload.
• Scenario-Based Examples: Best practices in IEPD development indicate that the effort should begin with the identification of the exchanges that this IEPD is intended to be used for. Taking this concept full circle, a sample instance document should be created for each exchange scenario.
• Right-Sized Sample: Part of creating realistic examples is to use realistic data. Ideally, the information is derived from a real sample document. Regardless of the source of the data, only populate those elements in the digest and payload that realistically occur within the context of a particular scenario. In other words, although the digest is overly inclusive, resist the temptation to include elements in your sample instance that would not occur on a real form in a similar context.
• Comment Code: We know commenting code is a good idea when developing software. Likewise, given the generic nature of digest elements, including comments that map each XML element to a specific data requirement is also a good idea.
• Abstract vs. Concrete Objects: The digest consists of abstract objects and concrete objects. Abstract objects provide a means of organizing concrete objects and are prefixed with “Entity…” such as EntityPerson. Only include the “id” attribute for concrete objects. Consequently, payload SameAsDigestReferences will only point to concrete objects.
• Documenting the Instance: Given the complex references that exist within a LEXS-based message, it is often useful to create a table with two columns. The first column indicates the semantic name of the object (e.g. Subject, Victim, Gang) while the second column indicates the id associated with that object. When referencing the object from the payload or creating associations, this table will help make sure the right objects are being connected together.
Reassembling Logical Objects
Once the message is received, it is the job of the receiving software to assemble objects split between the digest and payload into a single logical object. The best way to reassemble the objects is:
1. Use X-Path to find the document root in the full, un-split instance.
2. Deserialize payload elements into memory using such tools as Sun Microsystems Java Architecture for XML Binding (JAXB).
3. Scan the deserialized objects for the SameAsDigestReference. Use X-Path to retrieve the corresponding digest object referenced in the payload. Incorporate the digest element into a single logical element.
In conclusion, LEXS provides a number of techniques that enhance interoperability between systems. A number of organizations are prototyping and extending these techniques with national reference models to provide a standardized means of extending IEPDs.
Aaron Gorrell is president and CEO of Waterhole Software, a firm that specializes in the development of robust system architectures and specifications for justice organizations. He can be contacted at firstname.lastname@example.org.
Published in Public Safety IT, Sep/Oct 2008
Rating : 6.0
Related CompaniesWaterhole Software
Related ProductsStandards Implementation
Click to enlarge images.