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
Akoma Ntoso, LegisPro Web, Standards, Transparency

Akoma Ntoso Challenge by the Library of Congress

As many of you may have already read, the U.S. Library of Congress has announced a data challenge using Akoma Ntoso. The challenge lasts for three months and offers a $5,000 prize to the winner.

In this challenge, participants are asked to mark up four Congressional bills, provided as raw text, into Akoma Ntoso.

If you have the time to participate in this challenge and can fulfill all the eligibility rules, then I encourage you to step up to the challenge. This is a good opportunity to give Akoma Ntoso a try – to both learn the new model and to help us to identify any changes or adaptations that must be made to make Akoma Ntoso suitable for use with Congressional legislation.

You are asked, as part of you submission, to identify gaps in Akoma Ntoso’s design along with documenting the methodology you used to construct your solution to the four bills. You’re also encouraged to use any of the available open-source editors that are currently available for editing Akoma Ntoso and to provide feedback on their suitability to the task.

I would like to point out that I also provide an Akoma Ntoso editor at http://legisproweb.com. It is free to use on the web along with full access to all the information you need to customize the editor. However, while our customers do get an unrestricted internal license to the source code, our product is not open source. At the end of the day, I must still make a living. Nonetheless, I believe that you can use any editor you wish to create your four Akoma Ntoso documents – it’s just that the sponsors of the competition aren’t looking for feedback on commercial tools. If you do choose to use my editor, I’ll be there to provide any support you might need in terms of features and bug fixes to help speed you on your way.

Standard
Akoma Ntoso, Standards, Transparency

Legislative Data: The Book

Last week, as I was boarding the train at Admiralty station in Hong Kong to head back to the office, I learned that I am writing a book. +Ari made the announcement on his blog. It seems that Ari has found the key to getting me to commit to something – put me in a situation where not doing it is no longer an option. Oh well…

Nonetheless, there are many good reasons why now is a good time to write a book. In the past year we have experienced a marked increase in interest in the subject of legislative data. I think that a number of factors are driving this. First, there is renewed interest in driving towards a worldwide standard – especially the work being done by the OASIS LegalDocumentML technical committee. Secondly, the push for greater transparency, especially in the USA, is driving governments to investigate opening up their databases to the outside world. Third, many first generation XML systems are now coming due for replacement or modernization.

I find myself in a somewhat fortuitous position of being able to view these developments from an excellent vantage point. From my base in San Diego, I get to work with and travel to legislatures around the world on a regular basis. This allows me to see the different ways people are solving the challenges of implementing modern legislative information managements systems. What I also see, is how many jurisdictions struggle to set aside obsolete paper-based models for how legislative data should be managed. In too many cases, the physical limitations of paper are used to define the criteria for how digital systems should work. Not only do these limitations hinder the implementation of modern designs, they also create barriers that will prevent fulfilling the expectations that come as people adapt to receiving their information online rather than by paper.

The purpose of our book will be to propose a vision for the future of legislative data. We will share some of our experiences around the world – focusing on the successes some legislatures have had as they’ve broken legacy models for how things must work. In some cases the changes involve simply better separating the physical limitations of the published form from the content and structure. In other cases, we’ll explain how different procedures and conventions can not only facilitate the legislative process, but also make it more open and transparent.

We hope that by producing a book on the subject, we can help clear the path for the development of a true industry to serve this somewhat laggard field. This will create the conditions that will allow a standard, such as Akoma Ntoso, to thrive which, in turn, will allow interchangeable products to be built to serve legislatures around the world. Achieving this goal will reduce the costs and the risks of implementing legislative information management systems and will allow the IT departments of legislatures to meet both the internal and external requirements being placed upon them.

Ari extended an open invitation to everyone to propose suggestions for topics for us to cover. We’ve already received a lot of good interest. Please keep your ideas coming.

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

2013 Legislative Data and Transparency Conference

Last week I participated in the 2013 Legislative and Transparency Conference put on by the U.S. House of Representatives in Washington D.C.

It was a one day event that featured numerous speakers both within the U.S. government and in the surrounding transparency community around D.C. My role, at the end of the day, was to speak as a panelist along with Josh Tauberer of GovTrack.us and Anne Washington of The George Washington University on Under-Digitized Legislative Data. It was a fun experience for me and allowed me to have a friendly debate with Josh on API’s versus bulk downloads of XML data. In the end, while we both fundamentally agree, he favors bulk downloads while I favor APIs. It’s a simple matter of how we use the data.

The morning sessions were all about the government reporting the progress they have made over the past year relating to their transparency initiatives. There has been substantial progress this year and this was evident in the various talks. Particularly exciting was the progress that the Library of Congress is making in developing the new congress.gov website. Eventually this website will expand to replace THOMAS entirely.

The afternoon sessions were kicked off by Gherardo Casini of the UN-DESA Global Centre for ICT in Parliament in Rome, Italy. He gave an overview of the progress, or lack thereof, of XML in various parliaments and legislatures around the world. He also gave a brief mention of the progress in the LegalDocumentML Technical Committee at OASIS which is working towards the standardization of Akoma Ntoso. I am a member of that technical committee.

The next panel was a good discussion on extending XML. The panelists were Eric Mill at the Sunlight Foundation who, among other things, talked about the HTML transformation work he has been exploring in recent weeks. I mentioned his efforts in my blog last week. Following him was Jim Harper at the Cato Institute. He talked about the Cato Institute’s Deepbills project. Finally, Daniel Bennett gave a talk on HTML and microdata. His interest in this subject was also mentioned in my blog last week.

One particularly fun aspect of the conference was walking into the entrance and noticing the Cato Institute’s Deepbills editor running on the table at the entrance. The reason it was fun for me is that their editor is actually a customization of an early version of the HTML5-based LegisPro Web editor which I have spent much of the past year developing. We have developed this editor to be an open and customizable platform for legislative editing. The Cato Project is one of four different implementations which now exist – two are Akoma Ntoso based and two are not. More news will come on this development in the not-too-distant future. I had not expected the Cato Institute to be demonstrating anything and it was quite a nice surprise to see software I had written up on the display.

If there was any recurring theme throughout the day, it was the call for better linked data. While there has been significant progress over the past year towards getting the data out there, now it is time to start linking it all together. Luckily for me, this was the topic I had chosen to focus on in my talk at the end of the day. It will be interesting to see the progress that is made towards this objective this time next year.

All in all, it was a very successful and productive day. I didn’t have a single moment to myself all day. There were so many interesting people to meet that I didn’t get a chance to chat with nearly as many as I would have liked to.

For an amusing yet still informative take on the conference, check out Ari Hershowitz’s Tabulaw blog. He reveals a little bit more about some of the many projects we have been up to over the past year.

https://cha.house.gov/2013-legislative-data-and-transparency-conference

Standard
Akoma Ntoso, HTML5, Standards, Transparency, W3C

XML, HTML, JSON – Choosing the Right Format for Legislative Text

I find I’m often talking about an information model and XML as if they’re the same thing. However, there is no reason to tie these two things together as one. Instead, we should look at the information model in terms of the information it represents and let the manner in which we express that information be a separate concern. In the last few weeks I have found myself discussing alternative forms of representing legislative information with three people – chatting with Eric Mill at the Sunlight Foundation about HTML microformats (look for a blog from him on this topic soon), Daniel Bennett regarding microdata, and Ari Hershowitz regarding JSON.

I thought I would try and open up a discussion on this topic by shedding some light on it. If we can strip away the discussion of the information model and instead focus on the representation, perhaps we can agree on which formats are better for which applications. Is a format a good storage format, a good transport format, a good analysis/programming format, or a good all-around format?

1) XML:

I’ll start with a simple example of a bill section using Akoma Ntoso:

<section xmlns="http://docs.oasis-open.org/legaldocml/ns/akn/3.0/CSD03" 
       id="{GUID}" evolvingId="s1">
    <num>§1.</num>
    <heading>Commencement </heading>
    <content> <p>This act will go into effect on 
       <date name=”effectiveDate” date="2013-01-01">January 1, 2013</date&gt;. 
    </p> </content>
</section> 

Of course, I am partial to XML. It’s a good all-around format. It’s clear, concise, and well supported. It works well as a good storage format, a good transport format, as well as being a good format of analysis and other uses. But it does bring with it a lot of complexity that is quite unnecessary for many uses.

2) HTML as Plain Text

For developers looking to parse out legislative text, plain text embedded in HTML using a <pre> element has long been the most useful format.

   <pre>
   §1. Commencement
   This act will go into effect on January 1, 2013.
   </pre>

It is a simple and flexible represenation. Even when an HTML represenation is provided that is more highly decorated, I have always invariably removed the decorations to leave behind this format.

However, in recent years, as governments open up their internal XML formats as part of their transparency intiatives, it’s becoming less necessary to write your own parsers. Still, raw text is a very useful base format.

3) HTML/HTML5 using microformats:

<div class="section" id="{GUID}" data-evolvingId="s1">
   <div>
      <span class="num">§1.</span> 
      <span class=”heading”>Commencement </span>
   </div>
   <div class="content"><p>This act will go into effect on 
   <time name="effectiveDate" datetime="2013-01-01">January 1, 2013 <time>. 
   </p></div>
</div>

As you can see, using HTML with microformats is a simple way of mapping XML into HTML. Currently, many legislative data sources that offer HTML content either offer bill text as plain text as I showed in the previous example or they decorate it in a way that masks much of the semantic meaning. This is largely because web developers are building the output to an appearance specification rather than to an information specification. The result is class names that better describe the appearance of the text than the underlying semantics. Using microformats preserves much of the semantic meaning through the use of the class attribute and other key attributes.

I personally think that using HTML with microformats is a good way to transport legislative data to consumers that don’t need the full capabilities of the XML representation and are more interested in presenting the data rather than analyzing or processing it. A simple transform could be used to take the stored XML and to then translate it into this form for delivery to a requestor seeking an easy-to-consume solution.

[Note: HTML5 now offers a <section> element as well as an <article> element. However, they’re not a perfect match to the legislative semantics of a section and an article so I prefer not to use them.]

4) HTML5 Microdata:

<div itemscope 
      itemtype="http://docs.oasis-open.org/legaldocml/ns/akn/3.0/CSD03#section" 
      itemid="urn:xcential:guid:{GUID}">
   <data itemprop="evolvingId" value="s1"/>
   <div>
      <span itemprop="num">§1.</span>
      <span itemprop="heading">Commencement </span>
   </div>
   <div itemprop="content"> <p>This act will go into effect on 
      <time itemprop="effectiveDate" time="2013-01-01">January 1, 2013 </time>.
   </p> </div>
</div>

Using microdata, we see more formalization of the annotation convention than microformats offers – which brings along additional complexity and requires some sort of naming authority which I can’t say I either really understand or see how it will happen. But it’s a more formalized approach and is part of the HTML5 umbrella. I doubt that microdata is a good way to represetn a full document. Rather, I see microdata better fitting in to the role of annotating specific parts of a document with metadata. Much like microformats, microdata is a good solution as a transport format to a consumer not interested in dealing with the full XML representation. The result is a format that is rich in semantic information and is also easily rendered to the user. However, it strikes me that the effort to more robustly handle namespaces only reinvents one of XMLs more confusing aspects, namely namespaces, in just a different way.

5) JSON

{
   "type": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0/CSD03#section",
   "id": "{GUID}",
   "evolvindId": "s1",
    "num" : {
      "type": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0/CSD03#num",
      "text": "§1."
   },
   "heading":  {
      "type": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0/CSD03#heading",
      "text": "Commencement"
   },
   "content": {
      "type": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0/CSD03#content",
      "text1": "This act will go into effect on "
      "date": {
         "type": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0/CSD03#date",
         "date": "2013-01-01",
         "text": "January 1, 2013"
      }
      "text2": "."
   }
}

Quite obviously, JSON is great if you’re looking to easily load the information into your programmatic data structures and aren’t looking to present the information as-is to the user. This is a programmatic format primarily. Representing the full document in JSON might be overkill. Perhaps the role of JSON is for key parts of extracted metadata than the full document.

There are still other formats I could have brought up like RDFa, but I think my point has been made. There are many different ways of representing the same legislative model – each with its own strength and weaknesses. Different consumers have different needs. While XML is a good all-around format, it also brings with it some degree of sophistication and complexity that many information consumers simply don’t need to tackle. It should be possible, as a consumer, to specify the form of the information that most closely fits my need and have the legislative data source deliver it to me in that format.

[Note: In Akoma Ntoso, the format is called the “manifestation.” and is specified as part of the referencing specification.]

What do you think?

Standard
Akoma Ntoso, Standards, Transparency

Legal Reference Resolvers

After my last blog post I received a lot of feedback. Thanks to everyone who contacted me with questions and comments. After all the interest in the subject, I think I will devote a few more blog posts to the subject of legal references. It is quite possibly the most important subject that needs to be tackled anyway. (And yes, Harlan, I will try and blog more often.)

Many of the questions I received asked how I envision the resolver working. I thought I would dive into this aspect some more by defining the role of the resolver:

The role of a reference resolver is to receive a reference to a document or a fragment thereof and to do whatever it takes to resolve it, returning the requested data to the requestor.

That definition defines the role of a resolver in pretty broad terms. Let’s break the role down into some discrete functions:

  1. Simple Redirection – Perhaps the most basic service to provide will be that of a reference redirector. This service will convert a standardized virtual reference into a non-standard URL that is understood by a proprietary repository available elsewhere on the web that can supply the data for the request. The redirection service allows a legacy repository to provide access to documents following its own proprietary referencing mechanism without having to adopt the standard referencing nomenclature. In this case, the reference redirector will serve as a front to the legacy repository, mapping the standard references into non-standard ones.

  2. Reference Canonicalization – There are often a number of different ways in which a reference to a legal document can be composed. This is partly because the manner in which legal documents are typically structured sometimes encourages both a flat and a hierarchical view of the same data. For instance, one tends to think of section in a flat model because sections are usually sequentially numbered. Often however, those sections are arranged in a hierarchical structure which allows an alternate hierarchical model to also be valid. Another reason for alternate references is the simple fact that there are all sorts of different ways of abbreviating the same thing – and it is impossible to get everyone around the world to standardize on abbreviations. So “section1”, “sec1”, “s1”, and the even more exotic “§1” need to be treated synonymously. Also, let’s not forget about time. The requestor might be interested in the law as it existed on a particular date. The resulting reference will be formulated in a manner in which it starts being more of a document query rather than a document identifier. For instance, imagine a version of a section that became operational January 1, 2013. A request for the section that was in operation on February 1, 2013 will return that January 1 version if that version was still in operation on February 1 even though the operational date of the version is not February 1. (Akoma Ntoso calls the query case a virtual expression and differentiates it from the case where the date is part of the identifier)

    The canonicalization service will take any reference, perhaps vague or malformed, and will return one or more standardized references that precisely represent the documents that could be identified by the original reference – possibly along with a measure of confidence. I would imagine that official data services, providing authoritative legal documents, will most likely provide the canonicalization service.

  3. Repository Service – A legal library might provide both access to a document repository and an accompanying resolution service through which to access the repository. When this is the case, the resolver acts as an HTTP interface to the library, converting a virtual URL to an address of sorts in the document repository. This could simply involve converting the URL to a file path or it could involve something more exotic, requiring document extraction from a database or something similar.

    There are two separate use cases I can think of for the repository. The basic case is the repository as a read-only library. In this case, references are simply resolved, returning documents or fragments as requested. The second case is somewhat more complex and will exist within organizations tasked with developing legal resources – such as the organizations that draft legislation within the government. In this case, a more sophisticated read/write mechanism will require the resolver to work with technologies such as WebDAV which front for the database. This is a more advanced version of the solution we developed for use internally by the State of California.

  4. Resolver Routing – The most complex, and perhaps most difficult to achieve aspect, will be resolver routing. There is never going to exist a single resolver that can resolve every single legal reference in the world. There are simply too many jurisdictions to cover – in every country, state/province, county/parish, city/town, and every other body that produces legal documents. What if, instead, there was a way for resolvers to work together to return the document requested? While a resolver might handle some subset of all the references it receives on its own, for the cases it doesn’t know about, it might have some means to negotiate or pass on the request to other resolvers it knows about in order to return the requested data.

Not all resolvers will necessarily provide all the functions listed. How resolvers are discovered, how they reveal the functions they support, and how resolvers are tied together are all topics which will take efforts far larger than my simple blog to work out. But just imagine how many problems could be resolved if we could implement a resolving protocol that would allow legal references around the world to be resolved in a uniform way.

In my next blog, I’m going to return to the reference itself and take a look at the various different referencing mechanisms and services I have discovered in recent weeks. Some of the services implement some of the functions I have described above. I also want to discuss the difference between an absolute reference (including the domain name) and a relative reference (omitting the domain name) and why it is important that references stored in the document be relative.

Standard