If you set out to explore XQuery, the XML query language, you'll soon encounter a collection of examples, or use-cases, that show how XQuery can query and transform XML data. These scenarios are elaborated in a W3C document that presents a sample data set -- about books, authors, prices, and reviews -- and enumerates a set of queries against that data. For each query, there's a description ("List names of users who have placed multiple bids of at least $100 each"), a solution written in XQuery code, and an expected XML output.

XQuery vendors love to demonstrate that their software can run these standard tests and produce correct results. Such demonstrations help validate implementations and serve as tutorials for learning the language.

The use-cases weren't just slapped onto XQuery after the fact. They actually came first, and they guided the long and difficult process of developing XQuery. Jonathan Robie was one of the prime movers in the development of XQuery. When I interviewed him last year, he said that the use-cases provided invaluable guidance, and that he'd never attempt a project of similar scope without such guidance.

Now let's contrast XQuery with another XML-based standard of comparable heft, XBRL (Extensible Business Reporting Language). Even if you're not an accountant, you may know that XBRL is building momentum. There's growing recognition that financial reporting based on a mishmash of Word, Excel, PDF, and HTML files won't suffice. We require more speed and better transparency, and the consensus is that XBRL can and must meet those needs.

Last year the FDIC required banks to submit call reports in XBRL format. In September, the SEC awarded US$54 million in contracts to convert its legacy EDGAR system to XBRL, and to complete the taxonomies that will enable all U.S. companies to file their required disclosures in XBRL.

But where are the XBRL use-cases? Nowhere in particular. You can find scattered examples on Web sites run by XBRL International, the International Accounting Standards Board, or XBRL vendors. But there's nothing like XQuery's canonical set. As a result, a vast chasm stretches between accountants, who know about corporate earnings reports and SEC filings, and XML technologists, who know about XML Schema and XLink.

Charlie Hoffman, an accountant who saw the need for XBRL in 1998 and who has been the prime mover in its development ever since, is hard at work trying to bridge that chasm. In the podcast mentioned in my last column on XBRL, I noted that one of XBRL's claimed virtues -- modular extensibility -- wasn't clearly illustrated in any existing documentation. Hoffman took that as an action item and recently showed me a draft document that's rich with examples. But why only now? And why Charlie Hoffman, rather than the XML experts who have worked on XBRL?

The answer is that XQuery's history is an exception. Software technologists, as a rule, undervalue examples. The Unix man page is a classic illustration of this mind-set. It's a dictionary of raw capabilities. Applying them is left as an exercise for the reader.

Would up-front use-cases have made XBRL simpler and better? We'll never know; that's water under the bridge. If the XBRL examples arrive late, that's better than never. But here's hoping that future projects will heed Jonathan Robie's advice and write the use-cases first.