Akoma Ntoso, LegisPro Web, LEX Summer School, Standards, Track Changes

Akoma Ntoso (LegalDocML) is now available for public review

It’s been many years in the making, but the standardised version of Akoma Ntoso is now finally in public review. You can find the official announcement here. The public review started May 7th and will end on June 5th — which is quite a short time for something so complex.

I would like to encourage everything to take part in this review process, as short as it is. It’s important that we get good coverage from around the world to ensure that any use cases we missed get due consideration. Instructions for how to comment can be found here.

Akoma Ntoso is a complex standard and it has many parts. If you’re new to Akoma Ntoso, it will probably be quite overwhelmed. To try and cut through that complexity, I’m going to try and give a bit of an overview of what the documentation covers, and what to be looking for.

There are four primary documents

  1. Akoma Ntoso Version 1.0 Part 1: XML Vocabulary — This document is the best place to start. It’s an overview of Akoma Ntoso and describes what all the pieces are and how they fit together.
  2. Akoma Ntoso Version 1.0 Part 2: Specifications — This is the reference material. When you want to know something specific about an Akoma Ntoso XML element or attribute, this is the document to go to. In contains very detailed information derived from the schema itself. Also included with this is the XML schema (or DTD if you’re still inclined to use DTDs). and a good set of examples from around the world.
  3. Akoma Ntoso Naming Convention Version 1.0. This document describes two very interrelated and important aspects of the proposed standard — how identifitiers are assigned to elements and how IRI-based (or URI-based) references are formed. There is a lot of complexity in this topic and it was the subject to numerous meetings and an interesting debate at the Coco Loco restaurant in Ravenna, Italy, one evening while being eaten by mosquitoes.
  4. Akoma Ntoso Media Type Version 1.0 — This fourth document describes a proposed new media type that will be used when transmitting Akoma Ntoso documents.

This is a lot of information to read and digest in a very short amount of time. In my opinion, the best way to try and evaluate Akoma Ntoso’s applicability to your jurisdiction is as follows:

  • First, look at the basic set of tags used to define the document hierarchy. Is this set of tags adequate. Keep in mind that the terminology might not always perfectly align with your terminology. We had to find a neutral terminology that would allow us to define a super-set of the concepts found throughout the world.
  • If you do find that specific elements you need are missing, consider whether or not that concept is perhaps specific to your jurisdiction. If that is the case, take a look at the basic Akoma Ntoso building blocks that are provided. While we tried to provide a comprehensive set of elements and attributes, there are many situations which are simply too esoteric to justify the additional tag bloat in the basic standard. Can the building blocks be used to model those concepts?
  • Take a look at the identifiers and the referencing specification. These parts are intended to work together to allow you to identifier and access any provision in an Akoma Ntoso document. Are all your possible needs met with this? Implicit in this design is a resolver architecture — a component that parses IRI references (think of them as URLs) and maps to specific provisions. Is this approach workable?
  • Take a look at the basic metadata requirements. Akoma Ntoso has a sophisticated metadata methodology behind it and this involves quite a bit of indirection at times. Understand what the basic metadata needs are and how you would model your jurisdictions metadata using this.
  • Finally, if you have time, take a look at the more advanced aspects of Akoma Ntoso. Consider how information related to the documents lifecycle and workflow might be modeled within the metadata. Consider your change management needs and whether or not the change management capabilities of Akoma Ntoso could be adapted to fit. If you work with complex composite documents, take a look at the mechanisms Akoma Ntoso provides to assemble composite documents.

Yes, there is a lot to digest in just a few weeks. Please provide whatever feedback you can.

We’re also now in the planning stages for a US LEX Summer School. If you’ve followed my blog over the years, you’ll know that I am a huge fan of the LEX Summer School in Ravenna, Italy — I’ve been every year for the past five years. This year, Kirsten Gullikson and I convinced Monica and Fabio to bring the Summer School to Washington D.C. as well. The summer school will be held the last week of July 2015 at George Mason University. The class size will be limited to just 30, so be sure to register early once registration opens. If you want to hear me rattle on at length about this subject, this is the place to go — I’ll be one of the teachers. The Summer School will conclude with a one day Akoma Ntoso Conference on the Saturday. We’ll be looking for papers. I’ll send out a blog with additional information as soon as it’s finalized.

You may have noticed that I’ve been blogging a lot less lately. Well, that’s because I’ve been heads down for quite some time. We’ll soon be in a position to announce our first full Akoma Ntoso product. It’s an all new web-based XML editor that builds on our experiences with the HTML5 based AKN/Editor (LegisPro Web) that we built before.

This editor is composed of four main parts.

  1. First, there is a full XML editing component that works with pure XML — allowing it to be quite scalable and very XML precise. It implements complex track changes capabilities along with full redo/undo. I’m quite thrilled how it has turned out. I’ve battled for years with XMetaL’s limitations and this was my opportunity to properly engineer a modern XML editor.
  2. Second, there is a sophisticated resolver technology which acts as the middleware, implementing the URI scheme I mentioned earlier — and interfacing with local and remote document resources. All local document resources are managed within an eXist-db repository.
  3. Third, there is the Akoma Ntoso model. The XML editing component is quite schema/model independent. This allows it to be used with a wide variety of structured documents. The Akoma Ntoso model adapts the editor for use with Akoma Ntoso documents.
  4. And finally, there is a very componentised application which ties all the pieces together. This application is written as an AngularJS-based single page application (SPA). In an upcoming blog I’ll detail the trials and tribulations of learning AngularJS. While learning AngularJS has left me thinking I’m quite stupid at times, the goal has been to build an application that can easily be extended to fit a wide variety of structured editing needs. It’s important that all the pieces be defined as modules that can either be swapped out for bespoke implementations or complemented with additional capabilities.

Our current aim is to have the beta version of this new editor available in time for the Summer School and Akoma Ntoso conference — so I’ll be very heads down through most of the summer.

Standard
Akoma Ntoso, LEX Summer School, Process, Standards, Track Changes, Transparency, W3C

Achieving Five Star Open Data

A couple weeks ago, I was in Ravenna, Italy at the LEX Summer School and follow-on Developer’s Workshop. There, the topic of a semantic web came up a lot. Despite cooling in the popular press in recent years, I’m still a big believer in the idea. The problem with the semantic web is that few people actually get it. At this point, it’s such an abstract idea that people invariably jump to the closest analog available today and mistake it for that.

Tim Berners-Lee (@timberners_lee), the inventor of the web and a big proponent of linked data, has suggested a five star deployment scheme for achieving open data — and what ultimately will be a semantic web. His chart can be thought of as a roadmap for how to get there.

Take a look at today’s Data.gov website. Everybody knows the problem with it — it’s a pretty wrapper around a dumping ground of open data. There are thousands and thousands of data sets available on a wide range of interesting topics. But, there is no unifying data model behind all these data dumps. Sometimes you’re directed to another pretty website that, while well-intentioned, hides the real information behind the decorations. Sometimes you can get a simple text file. If you’re lucky, you might even find the information in some more structured format such as a spreadsheet or XML file. Without any unifying model and with much of the data intended as downloads rather than as an information service, this is really still Tim’s first star of open data — even though some of the data is provided as spreadsheets or open data formats. It’s a good start, but there’s an awful long way to go.

So let’s imagine that a better solution is desired, providing information services, but keeping it all modest by using off-the-shelf technology that everyone is familiar with. Imagine that someone with the authority to do so, takes the initiative to mandate that henceforth, all government data will be produced as Excel spreadsheets. Every memo, report, regulation, piece of legislation, form that citizens fill out, and even the U.S. Code will be kept in Excel spreadsheets. Yes, you need to suspend disbelief to imagine this — the complications that would result would be incredibly tough to solve. But, imagine that all those hurdles were magically overcome.

What would it mean if all government information was stored as spreadsheets? What would be possible if all that information was available throughout the government in predictable and permanent locations? Let’s call the system that would result the Government Information Storehouse – a giant information repository for information regularized as Excel spreadsheets. (BTW, this would be the future of government publishing once paper and PDFs have become relics of the past.)

How would this information look? Think about a piece of legislation, for instance. Each section of the bill might be modeled as a single row in the spreadsheet. Every provision in that section would be it’s own spreadsheet cell (ignoring hierarchical considerations, etc.) Citations would turn into cell references or cell range references. Amending formulas, such as “Section 1234 of Title 10 is amended by…” could be expressed as a literal formula — a spreadsheet formula. It would refer to the specific cell in the appropriate U.S. Code Title and contain programmatic instructions for how to perform the amendment. In short, lots of once complex operations could be automated very efficiently and very precisely. Having the power to turn all government information into a giant spreadsheet has a certain appeal — even if it requires quite a stretch of the imagination.

Now imagine what it would mean if selected parts of this information were available to the public as these spreadsheets – in a regularized and permanent way — say Data.gov 2.0 or perhaps, more accurately, as Info.gov. Think of all the spreadsheet applications that would be built to tease out knowledge from the information that the government is providing through their information portal. Having the ability to programmatically monitor the government without having to resort to complex measures to extract the information would truly enable transparency.

At this point, while the linkages and information services give us some of the attributes of Tim’s four and five star open data solutions, but our focus on spreadsheet technology has left us with a less than desirable two star system. Besides, we all know that having the government publish everything as Excel spreadsheets is absurd. Not everything fits conveniently into a spreadsheet table to say nothing of the scalability problems that would result. I wouldn’t even want to try putting Title 42 of the U.S. Code into an Excel spreadsheet. So how do we really go about achieving this sort of open data and the efficiencies it enables — both inside and outside of government?

In order to realize true four and five star solutions, we need to quickly move on to fulfilling all the parts of Tim’s five star chart. In his chart, a three star solution replaces Excel spreadsheets with an open data format such as a comma separated file. I don’t actually care for this ordering because it sacrifices much to achieve the goal of having neutral file formats — so lets move on to full four and five star solutions. To get there, we need to become proficient in the open standards that exist and we must strive to create ones where they’re missing. That’s why we work so hard on the OASIS efforts to develop Akoma Ntoso and citations into standards for legal documents. And when we start producing real information services, we must ensure that the linkages in the information (those links and formulas I wrote about earlier), exist to the best extent possible. It shouldn’t be up to the consumer to figure out how a provision in a bill relates to a line item in some budget somewhere else — that linkage should be established from the get-go.

We’re working on a number of core pieces of technology to enable this vision and get to full five star open data. We integrating XML repositories and SQL databases into our architectures to give us the information storehouse I mentioned earlier. We’re building resolver technology that allows us to create and manage permanent linkages. These linkages can be as simple as citation references or as complex as instructions to extract from or make modifications to other information sources. Think of our resolver technology as akin to the engine in Excel than handles cell or range references, arithmetic formulas, and database lookups. And finally, we’re building editors that will resemble word processors in usage, but will allow complex sets of information to be authored and later modified. These editors will have many of the sophisticated capabilities such as track changes that you might see in a modern word processor, but underneath you will find a complex structured model rather than the ad hoc data structures of a word processor.

Building truly open data is going to be a challenging but exciting journey. The solutions that are in place today are a very primitive first step. Many new standards and technologies still need to be developed. But, we’re well on our way.

Standard
Akoma Ntoso, LEX Summer School, Standards, Track Changes

2014 LEX Summer School & Developer’s Workshop

This week I attended the 2014 LEX Summer School and the follow-on Developer’s Workshop put on by the University of Bologna in Ravenna, Italy. This is the fifth year that I have participated and the third year that we have had the developer’s extension.

It’s always interesting to me to see how the summer school has evolved from the last year and who attends. As always, the primary participation comes from Europe – as one would expect. But this year’s participants also came from as far away as the U.S., Chile, Taiwan, and Kenya. The United States had a participant from the U.S. House of Representatives this year, aside from me. In past years, we have also had U.S. participation from the Library of Congress, Lexus Nexus, and, of course, Xcential. But, I’m always disappointed that there isn’t greater U.S. participation. Why is this? It seems that this is a field where the U.S. chooses to lag behind. Perhaps most jurisdictions in the U.S. are still hoping that Open Office or Microsoft Office will be a good solution. In Europe, the legal informatics field is looking beyond office productivity tools towards all the other capabilities enabled by drafting in XML — and looking forward to a standardized model as a basis for a more cost effective and innovative industry.

As I already mentioned, this was our third developer’s workshop. It immediately followed the summer school. This year the developer’s workshop was quite excellent. The closest thing I can think of in the U.S. is NALIT, which I find to be more of a marketing-oriented show and tell. This, by comparison, is a far more cozy venue. We sit around, in a classroom setting, and have a very open and frank share and discuss meeting. Perhaps it’s because we’ve come to know one another through the years, but the discussion this year was very good and helpful.

We had presentations from the University of Bologna, the Italian Senate, the European Parliament, the European Commission, the UK National Archives, the US House of Representatives, and myself representing the work we are doing both in general and for the US House of Representatives. We closed out the session with a remote presentation from Jim Mangiafico on the work he is doing translating to Akoma Ntoso for the UK National Archives. (Jim, if you don’t already know, was the winner of the Library of Congress’ Akoma Ntoso challenge earlier this year.)

What struck me this year is how our shared experiences are influencing all our projects. There has been a marked convergence in our various projects over the last year. We all now talk about URI referencing schemes, resolvers to handle them, and web-based editors to draft legislation. And, much to my delight, this was the first year that I’m not the only one looking into change tracking. Everybody is learning that differencing isn’t always the best way to compute amendments – often you need to better craft how the changes are recorded.

I can’t wait to see the progress we make by this time next year. By then, I’m hoping that Akoma Ntoso will be well established as a standard and the first generation of tools will have started to mature. Hopefully our discussion will have evolved from how to build tools towards how to achieve higher levels of compliance with the standard.

I also hope that we will have greater participation from the U.S.

Standard
Akoma Ntoso, Standards, Transparency

Look how far legal informatics has come – in just a few years

Back in 2001 when I started in the legal informatics field, it seemed we were all alone. Certainly, we weren’t – there were many similar efforts underway around the country and around the world. But, we felt alone. All the efforts were working in isolation – making similar decisions and learning similar lessons. This was the state of the field, for the most part, for the next 6 to 8 years. Lots of isolated progress, but few opportunities to share what we had learned and build on what others knew.

In 2010, I visited the LEX Summer School, put on by the University of Bologna in Ravenna, Italy. What became apparent to me was just how isolated the various pockets of innovation had become around the world. There was lots of progress, especially in Europe, but legal informatics, as an industry, was still in a fledgling state – it was more of an academic field than a commercial industry. In fact, outside of academic circles, the term legal informatics was all but meaningless. When I wrote my first blog in 2011, I looked forward to the day when the might be a true Legal Informatics industry.

Now, just a few years later, it’s stunning how far we have come. Certainly, we still have far to travel, but now we’re all working together towards common goals rather than working alone towards the same, but isolated, goals. I thought I would spend this week’s blog to review just how far we have come.

  1. Working together
    We have come together in a number of important dimensions:

    • First of all, consider geography. This is a small field, but around the world we’re now all very much connected together. We routinely meet, share ideas, share lessons, and share expertise – no matter which continent we work and reside on.
    • Secondly, consider our viewpoints. There was once a real tension between the transparency camp, government, external industry, and academia. If you participated at the 2014 Legislative Data and Transparency conference a few weeks ago in Washington D.C., one of the striking things was how little tension remains between these various viewpoints. We’re all now working towards a common set of goals.
  2. Technology
    • I remember when we used to question whether XML was the right technology. The alternatives were to use Open Office or Microsoft Office, basing the legislative framework around office productivity tools. Others even proposed using relational database technology along with a forms-based interface. Those ideas have now generally faded away – XML is the clear choice. And faking XML by relying on the fact that the Open Document Format (ODF) or Office Open XML formats are based on XML, just isn’t credible anymore. XML means more than just relying on an internal file format that your tools happen to use – it means designing information models specifically to solve the challenges of legal informatics.
    • I remember when we used to debate how references should be managed. Should we use file paths? Should we use URNs? Should we use URLs? Today the answer is clear – we’re all settling around logical URLs with resolvers, sometimes federated, to stitch together a web of interconnected references. Along with this decision has been the basic assumption that web-based solutions are the future – desktop applications no longer have a place in a modern solution.
    • Consider database technology. We used to have three choices – use the file system, try and adapt mature but ill-fitting relational databases, or take a risk with emerging XML databases. Clearly XML databases were the future – but was it too early? Not anymore! XML database technology, along with XQuery, have come a long way in the past few years
  3. Standards
    Standards are what will create an industry. Without them, there is little opportunity to re-use – a necessary part of allowing cost-effective products to be built. After a few false starts over the years, we’re now on the cusp of having industry standards to work with . The OASIS LegalDocML (Akoma Ntoso) and LegalCiteM technical committees are hard at work on developing those standards. Certainly, it will be a number of years before we will see the all the benefits of these standards, but as they come to fruition, a real industry can emerge.
  4. Driving Forces
    Ten years ago, the motivation for using XML was to replace outdated drafting systems, often cobbled together on obsolete mainframes, that sorely needed replacement. The needs were all internal. Now, that has all changed. The end result is no longer a paper document which can be ordered from the “Bill Room” found in the basement of the Capitol building. It’s often not even a PDF rendition of that document. The new end result is information which needs to be shared in a timely and open way in order to achieve the modern transparency objectives, like the DATA Act, that have been mandated. This change in expectations is going to revolutionize how the public works with their representatives to ensure fair and open government.
  5. In the past dozen years, things sure have changed. Credit must be given to the Monica Palmirani (@MonicaPalmirani) and Fabio Vitali at the University of Bologna – an awful lot of the progress pivots around their initiatives. However, we’ve all played a part in creating an open, creative, and cooperative environment for Legal Informatics to thrive as more than just an academic curiosity – as a true industry with many participants working collaboratively and competitively to innovate and solve the challenges ahead.

Standard
Akoma Ntoso, Standards, Transparency

2014 Legislative Data and Transparency Conference

Last week, I attended the 2014 Legislative Data and Transparency Conference in Washington D.C. This one day conference was put on the by the U.S. House of Representatives and was held at the U.S. Capitol.

The conference was quite gratifying for me. A good part of the presentation related to projects my company, Xcential, and I are working on. This included Ralph Seep’s talk on the new USML format for the U.S. Code and the Phase 2 Codification System, Sandy Strokof’s mention of Legislative Lookup and Linking and the new Amendment Impact Program (which was demonstrated by Harlan Yu (@harlanyu)), Daniel Bennett’s (@cititzencontact) talk on the legal citation technical committee, and finally Monica Palmirani (@MonicaPalmirani) and Fabio Vitali, from the University of Bologna, talked about Akoma Ntoso and Legal Document ML. We’ve made an awful lot of progress over the past few years.

Other updates included:

  • Andrew Weber (@atweber) gave an update on the progress being made by the Congress.gov website over at the Library of Congress. While still in beta, this site has now essentially replaced the older Thomas site.
  • There was an update on modernization plans over at the Government Printing Office including increased reliance on XML technologies. While it is good to see the improvements planned, their plans didn’t seem to be well integrated with all the other initiatives underway. Perhaps this will be clearer when more details are revealed.
  • Kirsten Gullickson (@GullicksonK) gave an update on the developments over at the Office of the Clerk of the House.

One very interesting talk was the winner of the Library of Congress Data Challenge, Jim Mangiafico (@mangiafico), describing his work building a transform from the existing Bill XML into Akoma Ntoso.

After lunch, there were a series of flash talks on various topics:

Later in the afternoon, Ali Ahmad (@aliahmad) chaired a panel discussion/update on the DATA Act and its implications on the legislative Branch. Perhaps it’s still to really understand what the effect of the DATA act will be – it looks like it is going to have a slow rollout over the next few years.

Anne Washington chaired a panel discussion on bringing the benefits of paper retrieval to electronic records. This discussion centered around a familiar theme, making data useful to someone who is searching for it – so it can be found, and when it is found, used.

All in all, it was a very useful day spent at the nation’s Capitol.

Standard
Akoma Ntoso, HTML5, LegisPro Web, Standards, Track Changes, Transparency, Uncategorized, W3C

Legal Citations and XML Editing for Legislation

It’s been quite some time since my last blog post – almost six months. The reason is that I’ve been very busy. We are doing a lot of exciting development within Xcential. We are developing a number of quite challenging projects around the globe.

If you’ve been following my blog, you may remember that I was working on an HTML5-based XML editor. That development was two years ago now. We’ve come a long way since then. The basic editor has been stripped down, componentized, and has being rebuilt to be a far more robust, scalable, and adaptable solution. There are more details below, which I will expand upon as the editor rolls out over the next year.

    Legal Citations

It was almost a year ago since the last Legislative Data and Transparency Conference in Washington D.C. (The next one is coming up) At that time, I spoke about the need for improved citation management in published XML documents. Well, we’ve come a long way since then. Earlier this year a Technical Committee was formed within OASIS to begin developing some standards. The Legal Citation Markup Technical Committee is now hard at work defining markup models for legal citations. I am a member of that TC.

The reference management part of our HTML5-based editor has been separated out as a separate project – as a citation interpreter and reference resolver. In our development tests, it’s integrated with eXist as a local repository. We also source documents from external sources such as LII.

We now have a few citation management projects underway, using our resolver technology. These are exciting projects which will be a huge step forward in improving how citations are managed. It’s premature to talk about this in any detail, so I’ll just leave this as a teaser of stuff to come.

    XML Editing for Legislation

The OASIS Legal Document ML Technical Committee is getting ready to make a large announcement. While this progress is being made, at Xcential we’ve been hard at work refining the state-of-the-art in XML editing.

If you recall the HTML5-based editor for Akoma Ntoso from a couple of years back, you may remember that is was based around all the new HTML5 technologies that have recently been incorporated into web browsers. We learned a lot from that effort – both good and bad. While we were able to get a reasonable tagging editor, using facilities that made editing far easier, we still faced difficulties when it came to basic XML editing and scalability.

So, we’ve taken a more ambitious approach to produce a very generalized XML editing platform. Using what we learned as the basis, our new editor is far more capable. Rather than relying on the mapping of XML into an equivalent HTML5 structure, we now directly use the XML facilities that are built into the browser. This approach is both far more robust and far more scalable. But the most exciting aspect is change tracking. We’re building change tracking directly into the basic editing engine – from the outset. This means that we can track all changes – whether the changes are in the text or in the structure. With all browsers now correctly implementing the standardized DOM Range model, our change tracking model has to be very sophisticated. While it’s hellishly complex, my experience in implementing change tracking technologies over many years is really coming in handy.

If you’ve used change tracking in XMetaL, you know the limitations of their technology. XMetaL’s range selection constrains how you can select which limits the flexibility of deletion. This simplifies the problem for the XMetaL customizer, but at a serious usability price. It’s one of the biggest limiting factors of XMetaL. We’re dealing with this problem once and for all with our new approach – providing a great way to implement legislative redlining.

Redlining Take a look at the totally contrived example on the left. It’s admittedly not a real example, it comes from my stress testing of the change tracking facilities. But look at what it does. The red text is a complex deletion that spans elements with little regard to the structure. In our editor, this was done with a single “delete” operation. Try and do this with XMetaL – it takes many operations and is a real struggle – even with change tracking turned off. In fact, even Microsoft Word’s handling of this is less than satisfactory, especially in more recent versions. Behind the scenes, the editor is using the model, derived from the schema, to control this deletion process to ensure that a valid document is the result.

If you’re particularly familiar with XMetal, you will notice something else too. That deletion cuts through the structure of a table!!!! XMetaL can only track changes within the text of table cells, not the structure. We’re making great strides towards proper legislative redlining technologies, and we are excited to work with our partners and clients to put them into practice.

Standard
Akoma Ntoso, Hackathon, Standards

Sheldon’s Roommate Agreement – in Akoma Ntoso

A Legal Open Document Hackathon was held yesterday at the University of Bologna in Italy – focused on Akoma Ntoso documents. You can learn more about it here:

https://plus.google.com/u/0/events/c03pd1llrcvg7d0t0fj5sh41cbk
http://codexml.cirsfid.unibo.it/material-for-legal-open-document-dec-10/

I wasn’t able to directly participate but I had my own mini-hackathon as well. But, rather than focusing on another boring piece of legislation that nobody wants to read, I thought I would have a little fun with it. If you know me, you’ll know that I’m a huge fan of The Big Bang Theory television show. You could say I have a few Sheldon-like tendencies of my own.

sheldonsRoommateAgreement

I’ve often thought that the complex roommate agreement that Sheldon had Leonard sign would make a great example for a legal document modeled in Akoma Ntoso. Of course, it’s not a piece of legislation, but surprisingly, it has many of the attributes of legislation. It is even, much like legislation, a bit of a chaotic mess. I had to make a number of extrapolations or “fixes” in order to get a reasonably consistent and workable document. I sure hope, if Sheldon’s desire to win a Nobel prize in physics is to be realized, that he is a better theoretical physicist than he is a legal drafter. Perhaps we should offer to give him a few pointers in document theory and the logical organization of ideas – he really needs them.

Nonetheless, the example afforded me an opportunity to show a number of features Akoma Ntoso:

  1. In article 10, section 9, there is an example of conditional effectivity. The provision is only effective in the event the either roommate has a girlfriend. As Leonard has had a few on-again, off-again girlfriends, it was a bit of fun figuring out when this provision was in effect. I didn’t consider Amy to be Sheldon’s girlfriend as the pertinent issues have yet to arise.
  2. In season 5, episode 15, Sheldon wins back Leonard’s friendship by amending the agreement to add “Leonard’s Day”.
  3. There are a number of “addendums” to various articles. This isn’t something that is directly supported by Akoma Ntoso, so I used the extension facilities of Akoma Ntoso to add generic tags with @name attributes to model the extensions I needed.
  4. The agreement is a complex document made up of the main document and at least three appendices

Sheldon’s Roommate Agreement

I present to you, Sheldon’s Roommate Agreement, as much as is known to date and with a few “corrections” on my part:

<?xml version="1.0" encoding="UTF-8"?>
<akomaNtoso xmlns="http://docs.oasis-open.org/legaldocml/ns/akn/3.0/CSD05"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://docs.oasis-open.org/legaldocml/ns/akn/3.0/CSD05 akomantoso30.xsd">
   <act name="roommateAgreement" contains="multipleVersions">
      <meta>
         <identification source="#sheldon">
            <FRBRWork>
               <FRBRthis value="/us/cbs/bigBangTheory/roommateAgreement/main"/>
               <FRBRuri value="/us/usc/bigBangTheory/roommateAgreement"/>
               <FRBRdate date="2013-12-10" name="generation"/>
               <FRBRauthor href="#sheldon" as="#lessor"/>
               <FRBRcountry value="us"/>
            </FRBRWork>
            <FRBRExpression>
               <FRBRthis
                  value="/us/cbs/bigBangTheory/roommateAgreement/en@/main"/>
               <FRBRuri value="/us/cbs/bigBangTheory/roommateAgreement/en@"/>
               <FRBRdate date="2013-12-10" name="generation"/>
               <FRBRauthor href="#sheldon" as="#lessor"/>
               <FRBRlanguage language="en"/>
            </FRBRExpression>
            <FRBRManifestation>
               <FRBRthis
                  value="/us/cbs/bigBangTheory/roommateAgreement/en@/main.xml"/>
               <FRBRuri value="/us/cbs/bigBangTheory/roommateAgreement/en@.akn"/>
               <FRBRdate date="2013-12-10" name="generation"/>
               <FRBRauthor href="#vergottini" as="#marker"/>
            </FRBRManifestation>
         </identification>
         <publication name="roommateAgreement" date="2013-12-10"
            showAs="Sheldon's Roommate Agreement"/>
         <lifecycle source="#sheldon">
            <eventRef id="gen__s_1__ep_1" date="2007-09-24" 
               source="#sheldon" type="generation"/>
            <eventRef id="gen__s_1__ep_17" date="2008-05-19"
               source="#sheldon" type="generation"/>
            <eventRef id="gen__s_2__ep_1" date="2008-09-22"
               source="#sheldon" type="generation"/>
            <eventRef id="gen__s_3__ep_1" date="2009-09-21" 
               source="#sheldon" type="generation"/>
            <eventRef id="gen__s_3__ep_19" date="2010-04-12"
               source="#sheldon" type="generation"/>
            <eventRef id="gen__s_4__ep_24" date="2011-05-19"
               source="#sheldon" type="generation"/>
            <eventRef id="gen__s_5__ep_7" date="2011-10-27"
               source="#sheldon" type="generation"/>
            <eventRef id="gen__s_5__ep_14" date="2012-01-26"
               source="#sheldon" type="generation"/>
            <eventRef id="gen__s_5__ep_15" date="2012-02-02"
               source="#sheldon" type="generation"/>
            <eventRef id="amd__s_5__ep_15" date="2012-02-02"
               source="#sheldon" type="amendment"/>            
         </lifecycle>
         <analysis source="#sheldon">
            <passiveModifications>
               <textualMod type="insertion" id="adds_leonards_day" 
                  incomplete="false">
                  <source href="#s_5__ep_15"/>
                  <destination href="#add_1"/>
               </textualMod>
            </passiveModifications>
         </analysis>
         <temporalData source="#sheldon">
            <temporalGroup id="period_1">
               <timeInterval refersTo="#signed" 
                  start="#gen_s_1__ep_1"/>
            </temporalGroup>
            <temporalGroup id="period_102">
               <timeInterval refersTo="#proposed" 
                  start="#gen__s_5__ep_15"/>
            </temporalGroup>
            <temporalGroup id="period_roommate_has_girlfriend">
               <timeInterval refersTo="#datingPenny1"
                  start="#gen__s_1__ep_17" end="#airing__s_2__ep_1"/>
               <timeInterval refersTo="#datingPriya1" 
                  start="#gen__s_3__ep_1" end="#airing__s_3__ep_19"/>
               <timeInterval refersTo="#datingPriya2"
                  start="#gen__s_4__ep_24" end="#airing__s_5__ep_7"/>
               <timeInterval refersTo="#datingPenny2"
                  start="#gen__s_5__ep_14"/>
            </temporalGroup>
         </temporalData>
         <references source="#bigBangTheory">
            <TLCRole id="lessor" 
               href="/ontology/role/lessor" 
               showAs="Lessor"/>
            <TLCRole id="lessee" 
               href="/ontology/role/lessee" 
               showAs="Lessee"/>
            <TLCRole id="marker" 
               href="/ontology/role/marker" 
               showAs="Lessee"/>
            <TLCPerson id="sheldon" 
               href="/ontology/person/cast/sheldonCooper"
               showAs="Sheldon Cooper"/>
            <TLCPerson id="roommate" 
               href="/ontology/person/cast/roommate"
               showAs="Roommate"/>
            <TLCPerson id="vergottini" 
               href="/ontology/person/xcential/vergottini"
               showAs="Grant Vergottini"/>            
            <TLCEvent id="s_2__ep_6"
               href="/ontology/tvShow/bigBangTheory/season2/episode6"
               showAs="Season 2 Episode 6"/>
            <TLCEvent id="s_2__ep_10"
               href="/ontology/tvShow/bigBangTheory/season2/episode10"
               showAs="Season 2 Episode 6"/>
            <TLCEvent id="s_3__ep_15"
               href="/ontology/tvShow/bigBangTheory/season3/episode15"
               showAs="Season 3 Episode 10"/>
            <TLCEvent id="s_3__ep_21"
               href="/ontology/tvShow/bigBangTheory/season3/episode21"
               showAs="Season 3 Episode 21"/>
            <TLCEvent id="s_3__ep_22"
               href="/ontology/tvShow/bigBangTheory/season3/episode22"
               showAs="Season 3 Episode 22"/>
            <TLCEvent id="s_4__ep_2"
               href="/ontology/tvShow/bigBangTheory/season4/episode2"
               showAs="Season 4 Episode 2"/>
            <TLCEvent id="s_4__ep_21"
               href="/ontology/tvShow/bigBangTheory/season4/episode21"
               showAs="Season 4 Episode 21"/>
            <TLCEvent id="s_4__ep_24"
               href="/ontology/tvShow/bigBangTheory/season4/episode24"
               showAs="Season 4 Episode 24"/>
            <TLCEvent id="s_5__ep_15"
               href="/ontology/tvShow/bigBangTheory/season5/episode15"
               showAs="Season 5 Episode 15"/>
            <TLCEvent id="s_5__ep_18"
               href="/ontology/tvShow/bigBangTheory/season5/episode18"
               showAs="Season 5 Episode 18"/>
            <TLCEvent id="s_6__ep_15"
               href="/ontology/tvShow/bigBangTheory/season6/episode15"
               showAs="Season 6 Episode 15"/>
         </references>
      </meta>

      <preface>
         <block name="title" id="title">
            <docTitle>The Roommate Agreement</docTitle>
         </block>
      </preface>

      <body period="period__1">
         <article id="art_1">
            <num>1</num>
            <heading id="art_1__heading">Upon becoming a roommate</heading>
            <section id="art_1__sec_1">
               <num>1</num>
               <content id="art_1__content">
                  <p>A roommate gets an ID Card, a lapel pin, FAQ sheet and a
                     key. New roommates may be interested in the live webchat on
                     Tuesday nights called “Apartment Talk.”</p>
               </content>
            </section>
            <section id="art_1__sec_3">
               <num>3)</num>
               <content id="art_1__sec_3__content">
                  <p>(call for an emergency meeting)</p>
                  <p class="sourceNote">(<ref id="ref_3" href="#s_2__ep_10"
                        >Season 2 Episode 10</ref>)</p>
               </content>
            </section>
            <section id="art_1__sec_5">
               <num>5</num>
               <subsection id="art_1__sec_5__ssec_A">
                  <num>A</num>
                  <content id="art_1__sec_5__ssec_A__content">
                     <p>Roommate must drive Sheldon to and from work, the comic
                        book store, the barber shop, and the park for one hour
                        every other Sunday for fresh air.</p>
                     <p class="sourceNote">(<ref id="ref_4" href="#s_3__ep_15"
                           >Season 3 Episode 15</ref>)</p>
                  </content>
               </subsection>
               <subsection id="art_1__sec_5__ssec_B">
                  <num>B</num>
                  <content id="art_1__sec_5__ssec_B__content">
                     <p>Roommate is tasked to bring home all take out dinners. (
                        Standard orders are located in Appendix B, and are also
                        down-loadable from Sheldon’s FTP server)</p>
                  </content>
               </subsection>
            </section>
            <section id="art_1__sec_9">
               <num>9</num>
               <heading id="art_1__sec_9__heading">Miscellany</heading>
               <paragraph id="art_1__sec_9__para_1">
                  <num>[1]</num>
                  <heading id="arc_1__sec_9__para_1__heading">Flag</heading>
                  <content id="art_1__sec_9__para_1__content">
                     <p>The apartment's flag is a gold lion rampant on a field
                        of azure” and should never fly upside down—unless the
                        apartment’s in distress.</p>
                     <p class="sourceNote">(<ref id="ref_1" href="#s_3__ep_22"
                           >Season 3 Episode 22</ref>_</p>
                  </content>
               </paragraph>
               <paragraph id="art_1__para_2">
                  <num>[2]</num>
                  <content id="art_1__para_2__content">
                     <p>If one of the roommates ever invents time travel, the
                        first stop has to aim exactly five seconds after this
                        clause of the Roommate Agreement was signed.</p>
                     <p class="sourceNote">(<ref id="ref_2" href="#s_3__ep_22"
                           >Season 3 Episode 22</ref>_</p>
                  </content>
               </paragraph>
            </section>
            <section id="art_1__sec_27">
               <num>27</num>
               <paragraph id="art_1__para_5">
                  <num>5</num>
                  <content id="art_1__para_5__content">
                     <p>The roommate agreement, like the American flag, cannot
                        touch the ground.</p>
                     <p class="sourceNote">(<ref id="ref_6" href="#s_6__ep_15"
                           >Season 6 Episode 15</ref>)</p>
                  </content>
               </paragraph>
            </section>
            <section id="art_1__sec_37">
               <num>37</num>
               <subsection id="art_1__sec_37__ssec_B">
                  <num>B</num>
                  <heading id="art_1__sec_37__ssec_B__heading">Miscellaneous
                     duties</heading>
                  <content id="art_1__sec_37__ssec_B__content">
                     <p>Roommate is obligated to drive Sheldon to his various
                        appointments, such as to the dentist. Roommate must also
                        provide a "confirmation sniff" to tell if questionable
                        dairy products are edible.</p>
                     <p class="sourceNote">(<ref id="ref_7" href="#s_3__ep_15"
                           >Season 3 Episode 15</ref>)</p>
                  </content>
               </subsection>
            </section>
            <section id="art_1__sec_209">
               <num>209</num>
               <content id="art_1__sec_209__content">
                  <p>Sheldon and roommate both have the option of nullifying
                     their roommate agreement, having no responsibilities or
                     obligations toward each other, other than paying rent and
                     sharing utilities.</p>
                  <p class="sourceNote">(<ref id="ref_8" href="#s_5__ep_15"
                        >Season 5 Episode 15</ref>)</p>
               </content>
            </section>
            <section id="art_1__sec_XX">
               <num>XX</num>
               <heading id="art_1__sec_XX__heading">Settling ties</heading>
               <content id="art_1__sec_XX__content">
                  <p>All ties will be settled by Sheldon.</p>
                  <p class="sourceNote">(<ref id="ref_9" href="#s_3__ep_22"
                        >Season 3 Episode 22</ref>)</p>
               </content>
            </section>
         </article>

         <article id="art_2">
            <num>2</num>
            <heading id="art_2__heading">Co-habitation</heading>
            <section id="art_2__sec_1">
               <num>1</num>
               <subsection id="art_2__sec_1__ssec_A">
                  <num>A</num>
                  <content id="art_2__sec_1__ssec_A__content">
                     <p>No "hootennanies", sing-alongs, raucous laughter,
                        clinking of glasses, celebratory gunfire, or barbershop
                        quartets after 10.p.m.</p>
                     <p class="sourceNote">(<ref id="ref_10" href="#s_5__ep_18"
                           >Season 5 Episode 18</ref>)</p>
                  </content>
               </subsection>
               <subsection id="art_2__sec_1__ssec_B">
                  <num>B</num>
                  <content id="art_2__sec_1__ssec_B__content">
                     <p>Roommate does not now nor does intend to play percussive
                        or brass instruments.</p>
                  </content>
               </subsection>
               <subsection id="art_2__sec_1__ssec_C">
                  <num>C</num>
                  <heading id="art_2__sec_1__ssec_C__heading"
                     >Temperature</heading>
                  <content id="art_2__sec_1__ssec_C__content">
                     <p>The thermostat must be kept at 71 degrees at all
                        times.</p>
                     <p class="sourceNote">(<ref id="ref_11" href="#s_3__ep_22"
                           >Season 3 Episode 22</ref>)</p>
                  </content>
               </subsection>
            </section>
            <section id="art_2__sec_2">
               <num>2</num>
               <heading id="art_2__sec_2__heading">Television and
                  movies</heading>
               <subsection id="art_2__sec_2__ssec_B">
                  <num>B</num>
                  <content id="art_2__sec_2__ssec_B__content">
                     <p>Roommates agree that Friday nights shall be reserved for
                        watching Joss Whedon's brilliant new series Firefly.</p>
                     <p class="soruceNote">(<ref id="ref_12" href="#s_3__ep_15"
                           >Season 3 Episode 15</ref>)</p>
                  </content>
               </subsection>
            </section>
            <section id="art_2__sec_3">
               <num>3</num>
               <content id="art_2__sec_3__content">
                  <p>Roommate has the right “to allocate fifty percent of the
                     cubic footage of the common areas”, but only if Sheldon is
                     notified in advance by e-mail.</p>
                  <p class="sourceNote">(<ref id="ref_13" href="#s_3__ep_22"
                        >Season 3 Episode 22</ref>)</p>
               </content>
            </section>
            <section id="art_2__sec_4">
               <num>4</num>
               <heading id="art_2__sec_4__heading">[Pets]</heading>
               <content id="art_2__sec_4__content">
                  <p>Pets are banned under the roommate agreement, with the
                     exception of service animals, like cybernetically-enhanced
                     helper monkeys.</p>
                  <p class="sourceNote">(<ref id="ref_14" href="#s_3__ep_21"
                        >Season 3 Episode 21</ref>)</p>
               </content>
            </section>
            <section id="art_2__sec_5">
               <num>5</num>
               <heading id="art_2__sec_5__heading">[Take-out
                  restaurant]</heading>
               <content id="art_2__sec_5__content">
                  <p>The selection of a new take-out restaurant requires public
                     hearings and a 60-day comment period.</p>
                  <p class="sourceNote">(<ref id="ref_15" href="#s_4__ep_21"
                        >Season 4 Episode 21</ref>)</p>
               </content>
            </section>
            <hcontainer name="addendums" id="art_2_addendums">
               <hcontainer name="addendum" id="art_2_add_A">
                  <num>A</num>
                  <content id="art_d_add_A_content">
                     <p>Sheldon [will] ask at least once a day how roommate is
                        even if he doesn't care.</p>
                     <p class="sourceNode">(<ref id="ref_16" href="#s_3__ep_15"
                           >Season 3 Episode 15</ref>)</p>
                  </content>
               </hcontainer>
               <hcontainer name="addendum" id="art_2__add_B">
                  <num>B</num>
                  <content id="art_2__add_B__content">
                     <p>Sheldon [will] no longer stage spontaneous biohazard
                        drills after 10 p.m. </p>
                     <p class="sourceNote">(<ref id="ref_17" href="#s_3__ep_15"
                           >Season 3 Episode 15</ref>)</p>
                  </content>
               </hcontainer>
               <hcontainer name="addendum" id="art_2__add_C">
                  <num>C</num>
                  <content id="art_2__add_C__content">
                     <p>Sheldon [will] abandon his goal to master Tuvan throat
                        singing. </p>
                     <p class="sourceNote">(<ref id="ref_18" href="#s_3__ep_15"
                           >Season 3 Episode 15</ref> )</p>
                  </content>
               </hcontainer>
            </hcontainer>
         </article>

         <article id="art_3">
            <num>3</num>
            <heading id="art_3__heading">The Bathroom</heading>
            <section id="art_3__sec_1">
               <num>1</num>
               <content id="art_3__sec_1__content">
                  <p>Roommates will acknowledge and use the two pieces of tape
                     in the bathroom designated for specific purposes:</p>
                  <blockList id="art_3__sec_1__content_ul_1">
                     <item id="art_3__sec_1__content_ul_1__item_1">
                        <p>Tape A: Located in front of the sink. Person must brush
                        and floss teeth behind the line.</p>
                     </item>
                     <item id="art_3__sec_1__content_ul_1__item_2">
                        <p>Tape B: Located in front of the toilet, those who stand
                        up to pee must stand in front of it.</p>
                     </item>
                  </blockList>
               </content>
            </section>
            <section id="art_3__sec_2">
               <num>2</num>
               <content id="art_3__sec_2__content">
                  <p>Before the use of a shower, the party agrees to wash his or
                     her feet in his or her designated bucket.</p>
               </content>
            </section>
            <section id="art_3__sec_7">
               <num>7</num>
               <intro id="art_3__sec_8__intro">
                  <p>The shower can have at most one occupant, except in the
                     event of an attack by water soluble aliens.</p>
               </intro>
               <subsection id="art_3__sec_8__ssec_B">
                  <num>B</num>
                  <paragraph id="art_3__sec_8__ssec_B__para_9">
                     <num>9</num>
                     <content id="art_3__sec_8__ssec_B__para_9__content">
                        <p>The right to bathroom privacy is suspended in the
                           event of force majeure.</p>
                        <p class="sourceNote">(<ref id="ref_19"
                              href="#s_4__ep_21">Season 4 Episode 21</ref>)</p>
                     </content>
                  </paragraph>
               </subsection>
            </section>
            <hcontainer name="addendums" id="art_3__addendums">
               <hcontainer name="addendum" id="art_3__add_J">
                  <num>J</num>
                  <content id="art_d__add_J__content">
                     <p>When Sheldon showers second, any and all measures shall
                        be taken to ensure an adequate supply of hot water.</p>
                     <p class="sourceNote">(<ref id="ref_20" href="#s_4__ep_21"
                           >Season 4 Episode 21</ref>)</p>
                  </content>
               </hcontainer>
            </hcontainer>
         </article>

         <article id="art_10">
            <num>10</num>
            <heading id="art_10__heading">Visitors</heading>
            <section id="art_10__sec_8">
               <num>8</num>
               <heading id="art_10__sec_8__heading">Over-night guests</heading>
               <intro id="art_10__sec_8__intro">
                  <p>There has to be a 24 hour notice if a non-related female
                     will stay over night.</p>
                  <p>(<ref id="ref_21" href="#s_3__ep_21">Season 3 Episode
                        21</ref>)</p>
               </intro>
               <subsection id="art_10__sec_8__ssec_C">
                  <num>C</num>
                  <heading id="art_1-__sec_8__ssec_C__heading">Females</heading>
                  <paragraph id="art_10__sec_8__ssec_C__para_4">
                     <num>4</num>
                     <heading id="art_10__sec_8__ssec_C__para_4__heading"
                        >Coitus</heading>
                     <content id="art_10__sec_8__ssec_C__para_4__content">
                        <p>Roommates shall give each other 12 hours notice of
                           impending coitus.</p>
                        <p class="sourceNote">(<ref id="ref_22"
                              href="#s_3__ep_22">Season 3 Episode 22</ref>)</p>
                     </content>
                  </paragraph>
               </subsection>
            </section>
            <section id="art_10__sec_9" period="period__roommate_has_girlfriend">
               <num>9</num>
               <heading id="art_10__sec_9__heading">Cohabitation Rider</heading>
               <intro id="art_10__sec_9__content">
                  <p>[This clause is] activated when roommate starts "living
                     with" a girlfriend in the apartment.</p>
                  <p>A girlfriend shall be deemed "living with" roommate when
                     she has stayed over for A: ten consecutive nights or B: for
                     more than nine nights in a three-week period or C: all the
                     weekends of a given month plus three weeknights.</p>
                  <p class="sourceNote">(<ref id="ref_23" href="#s_2__ep_10"
                        >Season 2 Episode 10</ref>)</p>
               </intro>
               <subsection id="art_10__sec_9__ssec_A">
                  <num>A</num>
                  <content id="art_10__sec_9__ssec_A__content">
                     <p>Upon a live-in girlfriend, there shall be a change in
                        the distribution of shelves in the fridge.</p>
                     <p class="sourceNote">(<ref id="ref_24" href="#s_2__ep_10"
                           >Season 2 Episode 10</ref>)</p>
                  </content>
               </subsection>
               <subsection id="art_10__sec_9__ssec_B">
                  <num>B</num>
                  <content id="art_10__sec_9__ssec_B__content">
                     <p>Apartment vacuuming shall be increased from three to
                        four times a week to accommodate the increased
                        accumulation of dead skin cells.</p>
                     <p class="sourceNote">(<ref id="ref_25" href="#s_2__ep_10"
                           >Season 2 Episode 10</ref>)</p>
                  </content>
               </subsection>
               <subsection id="art_10__sec_9__ssec_C">
                  <num>C</num>
                  <content id="art_10__sec_9__ssec_C__content">
                     <p>A change in the bathroom schedule shall be
                        implemented.</p>
                     <p class="sourceNote">(<ref id="ref_26" href="#s_2__ep_10"
                           >Season 2 Episode 10</ref>)</p>
                  </content>
               </subsection>
               <subsection id="art_10__sec_9__ssec_D">
                  <num>D</num>
                  <content id="art_10__sec_9__ssec_D__content">
                     <p>Girlfriend does not now nor does she intend to play
                        percussive or brass instruments.</p>
                     <p class="sourceNote">(<ref id="ref_27" href="#s2__ep_10"
                           >Season 2 Episode 10</ref>)</p>
                  </content>
               </subsection>
            </section>
         </article>

         <section id="sec_XX">
            <num>XX</num>
            <heading id="sec_XX__heading">Durable power of attorney</heading>
            <content id="sec_XX__content">
               <p>The other roommate get power of attorney over you, and may
                  make end-of-life decisions for you (reciprocal).</p>
               <p class="sourceNote">(<ref id="ref_28" href="#s_4__ep_24">Season
                     4 Episode 24</ref>)</p>
            </content>
         </section>

         <hcontainer name="addendums" id="addendums" period="period__102">
            <hcontainer name="addendum" id="add_1">
               <num>1</num>
               <heading id="add_1__heading">Leonard's Day</heading>
               <content id="add_1__content">
                  <p>Once a year, Leonard and Sheldon take one day to celebrate
                     the contributions Leonard gives to Sheldon's life, both
                     real and imaginary. Leonard does not get breakfast in bed,
                     the right to sit in Sheldon's spot, or permission to alter
                     the thermostat; the only thing that Leonard gets is a
                     thank-you card. This day is called "Leonard's Day."</p>
                  <p class="sourceNote">(<ref id="ref_29" href="#s_5__ep_15"
                        >Season 5 Episode 15</ref>)</p>
               </content>
            </hcontainer>
         </hcontainer>

      </body>
      <attachments>
         <doc name="appendix">
            <meta>
               <identification source="#sheldon">
                  <FRBRWork>
                     <FRBRthis value="/us/cbs/bigBangTheory/takeOutOrders/main"/>
                     <FRBRuri value="/us/cbs/bigBangTheory/takeOutOrders"/>
                     <FRBRdate date="2013-07-26T05:14:38" name="generation"/>
                     <FRBRauthor href="#sheldon" as="#lessor"/>
                     <FRBRcountry value="us"/>
                  </FRBRWork>
                  <FRBRExpression>
                     <FRBRthis
                        value="/us/cbs/bigBangTheory/takeOutOrders/en@/main"/>
                     <FRBRuri value="/us/cbs/bigBangTheory/takeOutOrders/en@"/>
                     <FRBRdate date="2013-07-26T05:14:38" name="generation"/>
                     <FRBRauthor href="#sheldon" as="#lessor"/>
                     <FRBRlanguage language="en"/>
                  </FRBRExpression>
                  <FRBRManifestation>
                     <FRBRthis
                        value="/us/cbs/bigBangTheory/takeOutOrders/en@/main.xml"/>
                     <FRBRuri
                        value="/us/cbs/bigBangTheory/takeOutOrders/en@.akn"/>
                     <FRBRdate date="2013-07-26T05:14:38" name="generation"/>
                     <FRBRauthor href="#vergottini" as="#marker"/>
                  </FRBRManifestation>
               </identification>
            </meta>
            <preface>
               <block name="title">
                  <docNumber>Appendix B</docNumber>
                  <docTitle>Standard take-out orders</docTitle>
               </block>
            </preface>
            <mainBody>
               <clause id="app_B__cls_1"> </clause>
            </mainBody>
         </doc>
         <doc name="appendix">
            <meta>
               <identification source="#sheldon">
                  <FRBRWork>
                     <FRBRthis
                        value="/us/cbs/bigBangTheory/futureCommitments/main"/>
                     <FRBRuri value="/us/cbs/bigBangTheory/futureCommitments"/>
                     <FRBRdate date="2013-07-26T05:14:38" name="generation"/>
                     <FRBRauthor href="#sheldon" as="#lessor"/>
                     <FRBRcountry value="us"/>
                  </FRBRWork>
                  <FRBRExpression>
                     <FRBRthis
                        value="/us/cbs/bigBangTheory/futureCommitments/en@/main"/>
                     <FRBRuri
                        value="/us/cbs/bigBangTheory/futureCommitments/en@"/>
                     <FRBRdate date="2013-07-26T05:14:38" name="generation"/>
                     <FRBRauthor href="#sheldon" as="#lessor"/>
                     <FRBRlanguage language="en"/>
                  </FRBRExpression>
                  <FRBRManifestation>
                     <FRBRthis
                        value="/us/cbs/bigBangTheory/futureCommitments/en@/main.xml"/>
                     <FRBRuri
                        value="/us/cbs/bigBangTheory/futureCommitments/en@.akn"/>
                     <FRBRdate date="2013-07-26T05:14:38" name="generation"/>
                     <FRBRauthor href="#vergottini" as="#marker"/>
                  </FRBRManifestation>
               </identification>
            </meta>
            <preface>
               <block name="title">
                  <docNumber>Appendix C</docNumber>
                  <docTitle>Future commitments</docTitle>
               </block>
            </preface>
            <mainBody>
               <clause id="app_c__cls_37">
                  <num>37</num>
                  <heading id="app_c__cls_37__heading">[Large Hadron
                     Collider]</heading>
                  <content id="app_c__cls_37__content">
                     <p>In the event one friend is ever invited to visit the
                        Large Hadron Collider, now under construction in
                        Switzerland, he shall invite the other friend to
                        accompany him.</p>
                     <p>(<ref id="app_c__ref_1" href="#s_3__ep_15">Season 3
                           Episode 15</ref>)</p>
                  </content>
               </clause>
               <clause id="app_c__cls_AA">
                  <num>[AA]</num>
                  <heading id="app_c__cls_AA__heading">[Super powers]</heading>
                  <content id="app_c__cls_AA__content">
                     <p>Specifies what happens if one friend gets super powers
                        (he will name the other one as his sidekick)</p>
                     <p class="sourceNote">(<ref id="app_c__ref_2"
                           href="#s_2__ep_10">Season 2 Episode 10</ref>)</p>
                     <p class="sourceNote">(<ref id="app_c__ref_3"
                           href="#s_3__ep_15">Season 3 Episode 15</ref>)</p>
                  </content>
               </clause>
               <clause id="app_c__cls_BB">
                  <num>[BB]</num>
                  <heading id="app_c__cls_BB__heading">[Zombies]</heading>
                  <content id="app_c__cls_BB__content">
                     <p>Specifies what happens if one friend is bitten by a
                        Zombie (the other can't kill him even if he turned)</p>
                     <p class="sourceNote">(<ref id="app_c__ref_4"
                           href="#s_3__ep_15">S3 Ep15</ref>)</p>
                  </content>
               </clause>
               <clause id="app_c__cls_CC">
                  <num>[CC]</num>
                  <heading id="app_c__cls_CC__heading">[MacArthur
                     grant]</heading>
                  <content id="app_c__cls_CC__content">
                     <p>Specifies what happens if one friend wins a MacArthur
                        grant </p>
                     <p class="sourceNote">(<ref id="app_c__ref_5"
                           href="#s_3__ep_15">Season 3 Episode 15</ref>)</p>
                  </content>
               </clause>
               <clause id="app_c__cls_DD">
                  <num>[DD]</num>
                  <heading id="app_c__cls_DD__heading">[Bill Gates]</heading>
                  <content id="app_c__cls_DD__content">
                     <p>Specifies what happens if one friend gets invited to go
                        swimming at Bill Gate's house (he will take the other
                        friend to accompany him)</p>
                     <p class="sourceNote">(<ref id="app_c__ref_6"
                           href="#s_3__ep_15">Season 3 Episode 15</ref>)</p>
                  </content>
               </clause>
               <clause id="app_c__cls_EE">
                  <num>[EE]</num>
                  <heading id="app_c__cls_EE__heading">[Skynet]</heading>
                  <content id="app_c__cls_EE__content">
                     <p>Specifies what happens if one friend needs help to
                        destroy an artificial intelligence he's created and
                        that's taking over Earth.</p>
                     <p class="sourceNote">(<ref id="app_c__ref_7"
                           href="#s_2__ep_6">Season 2 Episode 6</ref>)</p>
                  </content>
               </clause>
               <clause id="app_c__cls_FF">
                  <num>[FF]</num>
                  <heading id="app_c__cls_FF__heading">[Body
                     snatchers]</heading>
                  <content id="app_c__cls_FF__content">
                     <p>Specifies what happens if one friend needs help to
                        destroy someone they know who's been replaced with an
                        alien pod.</p>
                     <p class="sourceNote">(<ref id="app_c__ref_8"
                           href="#s_2__ep_6">Season 2 Episode 6</ref>)</p>
                  </content>
               </clause>
               <clause id="app_c__cls_GG">
                  <num>[GG]</num>
                  <heading id="app_c__cls_GG__heading">[Godzilla]</heading>
                  <content id="app_c__cls_GG__content">
                     <p>Specifies what happens if someone threatens to destroy
                        Tokyo.</p>
                     <p class="sourceNote">(<ref id="app_c__ref_9"
                           href="#s_2__ep_6">Season 2 Episode 6</ref>)</p>
                  </content>
               </clause>
               <clause id="app_c__cls_74">
                  <num>74</num>
                  <subclause id="app_c__cls_74__scls_C">
                     <num>C</num>
                     <heading id="app_c__cls_74__scls_C__heading"
                        >[Robots]</heading>
                     <content id="app_c__cls_74__scls_C__content">
                        <p>The various obligations and duties of the parties in
                           the event one of them becomes a robot.</p>
                        <p class="sourceNote">(<ref id="app_c__ref_10"
                              href="#s_4__ep_2">Season 4 Episode 2</ref>)</p>
                     </content>
                  </subclause>
               </clause>
            </mainBody>
         </doc>
      </attachments>
   </act>
</akomaNtoso>
Standard
Akoma Ntoso, Standards, Transparency

The U.S. Code in Akoma Ntoso

I’m on my way to Italy this week for my annual pilgrimage to Ravenna, Italy and the LEX Summer School put on by the University of Bologna. This is my fourth trip to the class. I always find it so inspirational to be a part of the class and the activities that surround it. This year I will be talking about the many on-going projects that we have underway as well as talking, in depth, about the HTML5 editor I built for Akoma Ntoso.

Before I get to Italy, I wanted to share something I’ve been working on. It should come as absolutely no surprise to anyone that I’ve been working on producing a version of the U.S. Code in Akoma Ntoso. A few weeks ago, the U.S. Office of the Law Revision Counsel released the full U.S. Code in XML. My company, Xcential, helped them to produce that release. Now I’ve taken the obvious next step and begun work on a transform to convert that XML into Akoma Ntoso – the format currently being standardized by the OASIS Legal Document ML technical committee. I am an active member of that TC.

U.S. Code

About 18 months ago, I learned of a version of the U.S. Code that had been made available in XML. While that XML release was quite far from complete, I used to to produce a representation in Akoma Ntoso as it stood back then. My latest effort is a replacement and update of that work. The new version of XML released by the OLRC is far more accurate and complete and is a better basis for the transform than earlier release was. And besides, I have a far better understanding of the new version – having had a role in its development.

My work is still very much a work-in-progress. I believe in openly sharing my work in the hope of inspiring other to dive into this subject – so I’m releasing a partial first step in order to get some feedback. Please note that this work is a personal effort – it is not a part of our work with the OLRC. At this point I’ve written a transform to produce Akoma Ntoso XML according to the most recent schema released a few weeks ago. The transform is not finished, but it gives a pretty good rendition of the U.S. Code in Akoma Ntoso. I’m using the transform as a vehicle to identify use cases and issues which I can bring up with the OASIS TC at our weekly meetings. As a result, there are a few open issues and the resulting XML does not fully validate.

I’m making 8 Titles available now. They’re smaller Titles which are easier for me to work with as I refine the transform. Actually, I do have the first 25 Titles converted into Akoma Ntoso, but I’ll need to address some performance and space issues with my tired old development server before I can release the full set. Hopefully, over the next few months, I’ll be able to complete this work.

When you look at the XML, you will notice a “proposed” namespace prefix. This simply shows proposed aspects of Akoma Ntoso that are not yet adopted. Keep in mind that this is all development work – do not assume that the transformation I am showing is the final end result.

I’m looking for feedback. Monica, Fabio, Veronique, and anyone else – if you see anything I got wrong or could model better, please let me know. If anyone finds the way I modeled something troubling, please let me know. I’m doing this work to open up a conversation. By trying Akoma Ntoso out in different usage scenarios, we can only make it better.

Don’t forget the Library of Congress’ Legislative Data Challenge. Perhaps my transformation of the U.S. Code can inspire someone to participate in the challenge.

Standard
Akoma Ntoso, Hackathon, HTML5, LegisPro Web, Standards, Transparency, W3C

Web-Based XML Legislative Editor Update

It’s been quite a while since I gave an update on our web-based XML legislative editor – LegisProweb. But that doesn’t mean that nothing has been going on. Quite the contrary, this has been a busy year for the editor project.

Let me first recap what the editor is. It’s an XML editor, written entirely around HTML5 technologies. It was first developed last year as the centerpiece to a Hackathon that Ari Hershowitz and I staged in San Francisco and around the world. While it is designed as a general purpose XML editor and can be configured to model any XML schema, it’s primarily configured to support Akoma Ntoso.

LegisProWeb

Since then, there has been a lot of continuing interest in the editor. If you attended the 2013 Legislative Data and Transparency Conference this past May in Washington DC, you may have noticed Jim Harper of the Cato Institute demonstrating their “Deepbills” project. The editor you saw is a heavily customized early version of LegisProweb, reconfigured to handle the XML format that the US Congress publishes legislation in.

And that’s not the only place where LegisProweb has been adopted. We’re in the finishing stages of a somewhat larger implementation we did for Chile. This is an Akoma Ntoso implementation – focused on debates and debate reports rather than on legislation. One interesting point worth noting – this implementation is done in Spanish. LegisProweb is quite easily localized.

The common thread between these two implementations in the use case – they’re both implementations focused on tagging metadata within pre-existing documents rather than on creating new documents from scratch. This was the focus of the Hackathon we staged back in 2012 – little did we know how much of a market would exist for an editor focused on annotation rather than document creation. And there’s more to still come – we’ve been quite surprised in the level of interest in this particular use-case.

Of course, we’re not satisfied with an editor that can only annotate existing documents. We’ve been hard at work turning the editor into a full-featured legislative editor that works equally well at creating new documents as it does at annotating existing documents. In addition, we’ve made the editor very customizalble as well as adding capabilities to manage the comments and discussions that might revolve around a document as it is being created and annotated.

Most recently, the editor has been upgraded to the latest version of Akoma Ntoso coming out of the OASIS legal document ML technical committee where I am an active member. Along with that effort, the validator has been separated to run as a standalone Akoma Ntoso validator. I talked about that in my blog last week. I’m busy using the validator as I work frantically to complete an Akoma Ntoso project I am working on this week. I’ll talk some more about this project next week.

So where do we go from here? Well, the first big effort is to modularize the technologies found within the editor. We now have a diverse set of customers right now and they can all benefit from the various bits and pieces that make up LegisProweb. By modularizing the pieces, we’ll be able to pick and choose which parts we use when and how. Separating out the validator was the first step. We’ll also be pulling out the reference resolver, attaching it to a native XML database, and partitioning out the client-side to allow the editing component to be used without the full editing environment offered by LegisProweb.

One challenge that remains is handling redlining – managing insertions and deletions. This is a very difficult subject – and one I tackled in the work I did implementing the XML editor used by the California legislature. I took a very different approach in trying to solve the problem with LegisProweb, but I’m not happy with the result. So, I’ll be returning to the proven approach we used way back when we built the original LegisPro editor on XMetaL.

As you can tell, we’ve got our work for the next year cut out for us.

Standard
Akoma Ntoso, LegisPro Web, Standards, Transparency, W3C

Free Akoma Ntoso Validator

How are people doing with the Library of Congress’ Akoma Ntoso Challenge? Hopefully, you’re making good progress, having fun doing it, and in so doing, learning a valuable new skill with this important emerging technology.

I decided to make it easy for someone without an XML Editor to validate their Akoma Ntoso documents for free. We all know how expensive XML Editors tend to be. If you’re like me, you’ve used up all the free trials you could get. I’ve separated the validation part of our LegisProweb editor from the editing base to allow it to be used as a standalone validator. Now, all you need to do is either provide a URL to your document or, even easier, drop the text into the text area provided and then click on the “Validate” button. You don’t even need to go find a copy of the Akoma Ntoso schema or figure out how to hook it up to your document – I do all that for you.

To use the validator, simply draft your Akoma Ntoso XML document, specifying the appropriate namespace using the @xmlns namespace declaration, and then paste a copy into the validator. I’ll go and find the schema and then validate your document for you. The validation results will be shown to you conveniently inline within your XML source to help you in making fixes. Don’t worry, we don’t record anything when you use the validator – it’s completely anonymous and we keep no record of your document.

You can validate either the 2.0 version of Akoma Ntoso or the latest 3.0 version which reflects the work of the OASIS LegalDocumentML committee. Actually, there are quite a few other formats that the validator also will work with innately and, by using xsi:schemaLocation, you can point to any XML schema you wish.

Give the free Akoma Ntoso XML Validator a try. You can access it here. Please send me any feedback you might have.

Validator1Input Form Validator2Validation Results
Standard