free our bills: hardcore wonk/geek out

So what do we need to know about a parliamentary bill?

First of all, as soon as a piece of legislation is published, it has certain meta-data. Date originated; originating department; originating MP; originating house; type - primary legislation, order in council, statutory instrument; current status (pre-legislative/Green/White Paper, first reading, committee, report, second, third, Royal Assent, repealed/superseded). And, of course, a unique identifier. But they aren't isolated; they amend, supersede, or repeal other legislation, so every Bill object needs to keep this information as well.

And if it's secondary legislation, it has dependencies on at least one past Act of Parliament, so anything with the types order-in-council or statutory instrument has to track which Acts it inherits from. Similarly, a primary Bill may create possible secondary legislation.

Now we need to look at the revisions. Once the bill is published, it starts to attract changes; but it remains the same bill. So we need to have further rows which are permanently associated with the original bill, but uniquely identifiable in themselves. It's probably simplest to keep only the changes at each step, because much of the point of the whole project is to monitor the changes. It feels right to me, if nothing else, to consider all the texts of a bill to be revisions, contained within the bill wrapper.

So a revision contains the title, the text in its sections, the status of the text, the originating organisation, if possible the originating MPs, the timestamp, and the amend/supersede/repeal/inherit information, and a revision ID. At each revision stage, a new item is added, until the final version gets Royal Assent; it would make sense to sort them in reverse chronological order and make the most recent version the default that is retrieved when that bill is requested.

This gives us a reasonable database of legislation, but it's not going to be much use; for that we need some more comprehensible semantics. So each bill needs both a summary and some category tags, and both the bills and revisions will need to have users specify their own tags and notes. Add those fields as well... And we'll need links to the debates at each stage, as well. Chuck in a URI field for Hansard in each Revision.

Summing up in object oriented terms, we've got a class called Bill, which has instance methods for the various metadata we've described, and a subclass called Revision, whose instance methods provide all the fields for each revision, but which always inherits the metadata and unique identifier of the Bill that created it, and possibly a further subclass of Revision called Comment to contain user notes. Further, the Bill needs a method Amend that creates a new Revision with the amending text, which remains provisional (inheriting the amending Bill's current status) until the amending Bill is finalised. Of course, if we implemented it in something like Django the code could be precisely that.

In database terms, each Bill is a row with a primary key that uniquely identifies the bill and all its revisions and comments; each Revision and Comment is a row which has the same key as its parent Bill and a key which identifies it in the context of that Bill.

Update: Comments point out that a Comment shouldn't be a subclass of Bill, for because it's not legislation itself and it should be an is-a relationship not a has-a relationship. Good point; actually, commentary should probably be logically parallel to the actual text of legislation, but related to it - Commentary, with subclass UserComment, linked by the bill and revision IDs to the actual text.

And Dsquared tells us that the German Bundestag already has a public version control system for legislation! Here it is; it's very complete and logical, I'll say that for it, but there is no facility to annotate anything. But if you want to know precisely what the Baden-Württemburg delegation wanted to change in the law on modernisation of accounting requirements in the Federal Council's Committee stage, it gets you there in two clicks from the search page. User experience design does not mean making things pretty.