Akoma Ntoso, Hackathon, HTML5, Standards, W3C

Update on our Web-based Legislative Editor

It’s been a while since my last blog post. I’ve been busy working on a number of activities. As a result, I have a lot of news to announce regarding the web-based editor, previously known as the AKN/Editor, that we originally built for the “Unhackathon” back in May.

As you might already have guessed, it has a new name. The new name is “LegisPro Web” which now more clearly identifies its role and relationship to Xcential’s XMetaL-based standalone editor “LegisPro”. Going forward, we will be migrating much of the functionality currently available in LegisPro into LegisPro Web.

Of course, there is now a new web address for the editor – http://legisproweb.com. As before, the editor prototype is freely available for you to explore at this address.

As I write this blog this early Sunday morning, I am in Ravenna, Italy where I just participated in the LEX Summer School 2012 put on by the University of Bologna. On Monday, the Akoma Ntoso Developer’s Workshop starts at the same venue. In addition to listening to the other developers present their work, I will be spending an afternoon presenting all the ins and outs of the LegisPro Web editor. I’m excited to have the opportunity to learn about the other developer’s experiences with Akoma Ntoso and to share my own experiences building a web-based XML editor.

Last month we demonstrated the LegisPro Web editor at the National Conference of State Legislators’s (NCSL) annual summit in Chicago this year. It was quite well received. I remain surprised at how much interest there is in an editor that is targetted to a tagging role rather than an editing role.

Of course, there has been a lot of development of the editor going on behind the scenes. I have been able to substantially improve the overall stability of the editor, its compliance with Akoma Ntoso, as well as add significant new functionality. As I become more and more comfortable and experienced with the new HTML5 APIs, I am starting to build up a good knowledge base of how best to take advantage of these exciting new capabilities. Particularly challenging for me has been learning how to intuitively work with the range selection mechanism. The origins of this mechanism are loosely related to the similar mechanism that is available within XMetaL. While I have used XMetaL’s ranges for the past decade, the HTML5 mechanisms are somewhat more sophisticated. This makes them correspondingly harder to master.

And perhaps the most exciting news of all is that the editor now has some customers. I’m not quite ready to announce who they are, but they do include a major government entity in a foreign country. As a result of this win, we will be further expanding our support of Akoma Ntoso to support Debate and Debate Reports in addition to the Bill and Act documents types we currently support. In addition, we will be adding substantial new capabilities which are desired by our new customers. I should also mention that Ari Hershowitz (@arihersh) has joined our team and will be taking the lead in delivering the customized solution to one of our customers.

Alongside all this development, work continues at the OASIS LegalDocumentML Technical Committee. Look to see me add support for the Amendment document type to the editor in support of this activity in the not- too-distant future.

All in all, I think we’re making terrific progress bringing the LegisPro Web editor to life. I started work on the editor as a simple idea a little more than six months ago. We used the “Unhackathon” in May to bootstrap it to life. Since then, it’s taken off all on its own and promises to become a major part of our plans to build a legitimate legal informatics industry around an Akoma Ntoso based standard.

HTML5, Standards, W3C

Why Not Build a Legislative Editor out of Google Docs?

Ever since I started working on my legislative editor (http://legalhacks.org/editor), I’ve been asked over and over if I was using Google Docs, and if not, why not.

So to answer the first part of the question, the answer is a simple no. I don’t use Google Docs or anything like it.

There are a number of good reasons why I take a different path. The first reason is that Google simply doesn’t open Google Docs to that type of customization. Even if the customization capability was there, there are still plenty of reasons why choosing to build a legislative editor around Google Docs would not necessarily make sense. We can start with the privacy and security concerns with storing legislation in Google’s cloud. Let’s set aside that level of concern to focus more on the technical issues of the editor itself.

We’ll start by considering the difference between a word processor and an XML editor. When done right, an XML editor should superficially look just like a word processor. With a lot of effort, an XML editor can also be made to feel like a word processor. When I was implementing XMetaL for the California Legislature, the goal was very much to achieve the look and feel of a word processor. That is possible, but only to an extent.

There is a big difference between a word processor and an XML editor. Just because modern word processors now save their data in an XML format, they are not XML editors as a result. If you take a look at their file formats, OOXML for Microsoft Word or ODF for Open Office, you’ll see very complex and very fixed schemas that are far more oriented around presentation than one typically desires in an XML document. In fact, we try to separate presentation from structure in XML documents while OOXML and ODF blend them together. That’s what is at the heart of the difference between a word processor and an XML editor. In a word processor you worry about things like page breaks, margins, fonts, and various other attributes of the document that make it “pretty”. In an XML document, typically all of that is going to be added after the fact using a “formula” rather than being customized into each document. So while what you see in an XML document might look WYSIWYG, it’s actually more like “Somewhat WYSIWYG” and your ability to customize the formatting is quite constrained. This approach focuses you on the content and structure of the document and allows the resulting information to be targetted to many different form factors for publication. By not dictating the formatting of the document, the publication engine is more free to choose the best layout for any particular publication form – be it web, paper, mobile, or whatever.

When I explain this, the next question is whether or not my implementation is similar to how Google Docs is implemented. The answer is, again, a simple no. Google Docs’ implementation is dramatically different from the approach that I take. My approach relies on the new APIs being added to the browsers, in a consistent standardized way under the HTML5 umbrella, that allow the text content to be selected, edited, dragged about, and formatted. While these capabilities existed in earlier browsers to some extent, the manner in which they were supported was in no ways consistent. This made supporting multiple browsers really difficult and the resulting application would be a patchwork of workarounds and quirks. Even then, the browser variations would result in inconsistent behaviors between the browsers and the support and maintenance task would be a nightmare. It is for this reason, along with a need for page-oriented layout features, that Google abandoned the approach I am taking – though at a time when the standards that help ensure consistency were lacking.

So how does Google Docs do it then? How come they didn’t get bogged down in a sea of browser incompatibilities amongst all the legacy browsers they support? They do it by completely creating their own editing surface in JavaScript – something codenamed “kix”. Rather than relying on the browser for very much, they instead have their own JavaScript implementation of every feature they need for the editing surface. That is how they are able to implement rulers, pages, and drag boxes in ways you’ve just never seen in a browser before. It’s an amazing accomplishment and it allows them to support a wide range of browsers with a single implementation. That’s what you can do when you’re Google and have deep pockets. It’s a very expensive and very complex solution to the problem I am attempting to solve with modern standards. So while I can reasonably support the future alone with no baggage from the past, they’re able to support future and past browsers by skipping on the baggage but instead having their own custom implementation of everything. While I’m amazed at Google Doc’s accomplishment, attempting a similar thing with an XML editor would be cost and time prohibitive. Keep in mind that a lot of the capabilities of Google Docs’ editing surface deal with presentation aspects of a document, something that is of less concern to the typical XML document.

I’ve been working in XML editors for over 10 years now. Over the years, I’ve spent a lot of time wondering how one might implement a real web-based XML editor. Every time that my thoughts went beyond wondering and moved towards considering, I quickly discovered that all the resulting limitations of divergent implementations of base technology would make the project impractical. That’s partly what drove Google to spend the big bucks on a custom editing surface for their word processor. Now however, HTML5 is beginning to make a web-based XML editor a practical reality. Don’t mistake me, it’s still very difficult. Figuring out how to keep and XML document and an HTML5 view synchronized in not a simple task. While the browsers have all come a long way, they all still have their own weaknesses. Drag and drop has been broken in Safari since 5.1.2. Opera’s selection mechanism breaks when you toggle the contentEditable attribute right now. But these are problems that will disappear with time. As the standards are implemented and the bugs are fixed, I can already see how much HTML5 is going to change the application landscape. I would think long and hard about returning to traditional application development given what I now know about HTML5.

Akoma Ntoso, HTML5, Standards, W3C

A Pluggable XML Editor

Ever since I announced my HTML5-based XML editor, I’ve been getting all sorts of requests for a variety of implementations. While the focus has been, and continues to be, providing an Akoma Ntoso based legislative editor, I’ve realized that the interest in a web-based XML editor extends well beyond Akoma Ntoso and even legislative editors.

So… with that in mind I’ve started making some serious architectural changes to the base editor. From the get-go, my intent had been for the editor to be “pluggable” although I hadn’t totally thought it through. By “pluggable” I mean capable of allowing different information models to be used. I’m actually taking the model a bit further to allow modules to be built that can provide optional functionality to the base editor. What this means is that if you have a different document information model, and it is capable of being round-tripped in some way with an editing view, then I can probably adapt it to the editor.

Let’s talk about the round-tripping problem for a moment. In the other XML editors I have worked with, the XML model has had to quite closely match the editing view that one works with. So you’re literally authoring the document using that information model. Think about HTML (or XHTML for an XML perspective). The arrangement of the tags pretty much exactly represents how you think of an deal with the components of the document.  Paragraphs, headings, tables, images, etc, are all pretty much laid out how you would author them. This is the ideal situation as it makes building the editor quite straight-forward.

However, this isn’t always the case. Depending on how much this isn’t the case determines how feasible building an editor is at all. Sometimes the issues are minor. For instance, in Akoma Ntoso, a section “num” element is out-of-line with the content block containing the paragraphs. So while it is quite common for the num to be inline in the first paragraph of the the section, that isn’t how Akoma Ntoso chooses to represent this. And it gets more difficult from there when you start dealing with subsections and sub-subsections.

To deal with these sorts of issues, a means of translating back and forth between what you’re editing and the information model you’re building is needed. I am using XSL Transforms, designed specifically for round-tripping to solve the problem. Not every XML model lends itself to document authoring, but by building a pluggable translating layer I’m able to adapt to more models than I have been able to in the past.

Along with these mechanisms I am also allowing for pluggable command structures, CSS styling rules, and, of course, the schema validation. In fact, the latest release of the editor at legalhacks.org has been refactored and now somewhat follows this pluggable architecture.

Next I plan to start working with modules like change tracking / redlining, metadata generation (including XBRL generation), and multilingual support following this pluggable architecture. I’m totally amazed at how much more capable HTML5 is turning out to be when compared to old-fashioned HTML4. I can finally build the XML editor I always wanted.

Akoma Ntoso, HTML5, Standards, Transparency

XBRL in Legislation

Over the past few weeks, my posts about the HTML5 editor I have been working on have received a lot of attention. One aspect that I have noticed throughout has been people equating legislative markup to XBRL. In fact, I have taken to explaining Akoma Ntoso as being like XBRL for legislation. That helps people better understand what we are up to.

Or does it? It’s a little misleading to describe a legislative information model as being like XBRL for legislation. The reason is that many of the people interested in the transparency aspects of legislative XML are interested in it precisely because they’re interested in tracking budget appropriations. The assumption being made is that the XML will somehow make it possible to track the money that flows through legislation.

In some respects XML does help track money. Certainly, reporting budgets as XML is a whole lot better than the other approach you often see – tables reported as images. Images are a very effective way to hide appropriations from machine processing. However, that’s less and less of a problem. Nowadays, if you take a look at any budget appropriation embedded within legislation, you’re likely to find the numbers reported in a table. Most likely that table will be in the form of an HTML table at that. How you interpret that table is up to you. Perhaps the CSS class names for each cell will provide some guidance as to each cell’s content, but the information is being reported in a manner intended for human consumption rather than machine processing. In short, the manner in which financial information is reported in legislation is not for the sake of improving the transparency of the data.

In California, when we designed the budget amending facilities within the bill drafting system, our objective was to find a way to draft a budget amendment with the limited tabular capabilities of XMetaL. Whether the result was transparent or not was not a consideration as it was not a requirement six years ago. Victory for us was finding a way to get the immediate job done. Elsewhere, I have yet to see any legislative information model attempt to address the issue of making budget appropriations more transparent. Rather, the focus is instead on things like the temporal aspects of amending the law, the issues that arise in a multilingual society, or ensuring the accuracy and authenticity of the documents.

So what is the solution? I must profess to know very little about XBRL. What I do know tells me that it is not a suitable replacement for all those HTML tables that we tend to use. XBRL is a complex data format normalized for database consumption. The information is not stored in a manner that would allow for easy authoring by a human author or easy reading by a human reader. I did find one article from three years back that begins to address the issue. Certainly we’ve come far on the subject of legislative XML and it’s time to reconsider this subject.

The good news is that we do have a solution for integrating XBRL with legislative XML. Within an Akoma Ntoso document is a proprietary section found inside the metadata block. This section is set aside specifically to allow foreign information models to be embedded within the legislative document. So, much as the metadata already contains analysis sections for recording the temporal aspects of the legislation, it is quite easy to add an XBRL section to record the financial aspects of the legislation.

So the next question is whether or not XBRL is designed to be embedded within another document. It would seem that the answer is yes – and it is called inline XBRL. While the specification addresses fragments of XBRL within HTML documents, I don’t see why this cannot be extended to a legislative information model.  Simply put, a fragment of inline XBRL data would be embedded within the metadata block of the legislative document recorded in XML. This data would be available for any XBRL processor to discover (how is another question) and consume. The inline XBRL would be produced prior to publication by analyzing the legislative XML’s tables used to draft the document.

Ideally, the XBRL data would be hooked directly to the legislative XML data, much like spreadsheet formalas can be attached to data, but maybe I’m getting ahead of myself. Providing budget appropriation information within inline XBRL embedded within the legislative XML would be a great step forward – and it would achieve the objectives that people that are interested in the transparency aspects of legislative XML actually have.

I’m certainly no expert in XBRL, so I’m interested in hearing what people in the know have to say about this. Let me know. If you know of an appropriations taxonomy for XBRL, let me know. And if you’re interested in following how the DATA Act might influence this subject, check out the Data Transparency Coalition.

Akoma Ntoso, Hackathon, HTML5, Standards, W3C

An HTML5-Based XML Editor for Legislation!

UPDATE: (May 17, 2012) For all the people that asked for more editing capabilities, I have updated the editor to provide rudimentary cut/copy/paste capabilities via the normal shortcut keys. More to follow as I get the cycles to refine the capabilities.

I’ve just released my mini-tutorial for the HTML5-based XML editor I am developing for drafting legislation (actually it’s best for tagging existing legislation at this point).

Please keep in mind that this editor is still very much in development – so its not fully functional and bug-free at this point. But I do believe in being open and sharing what I am working on. We will be using this editor at our upcoming International Legislation Unhackathons (http://legalhacks.org) this coming weekend. The editor is available to experiment with at legalhacks.org site.

There are three reason I think that this approach to building editors is important:

  1. The editor uses an open standard for storing legislative data. This is a huge development. The first couple generations of legislative systems were built upon totally proprietary data formats. That meant that all the data was locked into fully custom tools that were built years ago could only be understood by those systems. Those systems were very closed. That last decade was the development of the XML era of legislative tools. This made it possible to use off-the-shelf editors, repositories, and publishing tools. But the XML schemas that everyone used were still largely proprietary and that meant everyone still had to invest millions of dollars in semi-custom tools to produce a workable system. The cost and risk of this type of development still put the effort out of reach of many smaller legislative bodies.

    So now we’re moving to a new era, tools based on a common open standard. This makes it possible for an industry of plug-and-play tools to emerge, reducing the cost and risks for everyone. The editor I am showing uses Akoma Ntoso for its information model. While not yet a standard, it’s on a standards track at the OASIS Standards Consortium and has the best chance of emerging as the standard for legal documents.

  2. The editor is built upon open web standards. Today you have several choices when you build a legislative editor. First, you can build a full custom editor. That’s a bad idea in this day and age when there are so many existing editors to build upon. So that leaves you with the choice of building your editor atop a customizable XML editor or customizing the heck out of a word processor. Most XML editors are built with this type of customization in mind. They intrinsically understand XML and are very customizable. But they’re not the easiest tools to master – for either the developer or the end user. Another approach is to use a word processor and bend and distort it into being an XML editor. This is something well beyond the original intent of the word processor and dealing with the mismatch in mission statements for a word processor and a legislative drafting tool leaves open lots of room for issues in the resulting legislation.

    There is another problem as well with this approach. When you choose to customize an off-the-shelf application, you have to buy into the API that the tool vendor supplies. Chances are that API is proprietary and you have no guarantee that they won’t change it on a whim. So you end up with a large investment in software built on an application API that could become almost unrecognizable with the next major release. So while you hope that your investment should be good for 10-12 years, you might be in for a nasty surprise at a most inopportune time well before that.

    The editor I have built has taken a different approach. It is building upon W3C standards that are being built around HTML5. These APIs are standards, so they won’t change on a whim – they will be very long lived. If you don’t like a vendor and want to change, doing so is trivial. I’m not just saying this. The proof is in the pudding. This editor works on all four major browsers today! This isn’t just something I am planning to support in the future; it is something I already support. Even while the standards are still being refined, this editor already works with all the major browsers. (Opera is lagging behind in support for some of the application APIs I am using.) Can you do that with an application built on top of Microsoft Office? Do you want to switch to Open Office and have an application you built? You’re going to have to rewrite your application.

  3. Cloud-based computing is the future, Sure, this trend has been obvious for years, but the W3C finally recognizes the web-based application as being more than just a sophisticated website. That recognition is going to change computing forever. Whether your cloud is public or private, the future lies in web-based applications. Add to that the looming demands for more transparent government and open systems with facilitate real public participation and it becomes obvious that the era of the desktop application is over. The editor I am building anticipates this future.

  4. I’ve been giving a lot of thought to where this editor can go. As the standards mature, I learn to tame the APIs, and the browsers finish the work remaining for them, it seems that legislative drafting is only the tip of the iceberg for such an approach to XML-based editing. Other XML models such as DITA and XBRL might well be other areas worth exploring.

    What do you think? Let me know what ideas you have in this area.