This piece will suggest a general approach to “programming” legal documents.  It is a kind of “CommonAccord for Beginners” that @mdangeard has advocated.  But it is also a  synthesis of the principles of legal draftsmanship intended to contribute to the craft of law, and suggestions for how to integrate legal text with automation.

Lawyers are not the only people who code.  Programmers (AKA coders, engineers, hackers) also code.  While there are important differences between the two kinds of coding, the overlaps are substantial and instructive.  The logistical challenges of software coding are greater than those of legal coding, so programmers have had to be more systematic.  Programmers also know how to build their own tools.  Programmers have important tools and methods that legal coding can benefit from.

Before getting into the meat of the subject, it may be useful to discuss “code as law,” which is closely related to, but different than “coding law,” and “code is law.”  This may help clarify our purpose.

“Code as law” is a powerful idea and the thrust of much discussion of smart contracts.  If the mechanics and conditions of a relationship can be programmed, then there is no need to express them in legal prose.  That avoids the inherit ambiguities of language and vicissitudes of human interpretation.  Code as law increasingly underpins transaction systems, from online merchants to stock markets.  It is to be expected to dominate systems of production and distribution, and increasingly systems of administration and justice.   It has the advantages of extremely low cost, very high reproducibility, and increasing ability to handle complexity.  Code as law has the disadvantage, so far, of weakness on edge cases, though that is changing rapidly, notably because of machines’ ability to draw conclusions from experience.  Self-driving vehicles are a leading example.  The persistence of edge cases and of unforeseen consequences, however, means that framing in legal prose remains important.  Contracts are “incomplete” (Hart and Holmström), as is our understanding of them.

“Code is law” is the famous expression of Lawrence Lessig.  At root this is the observation that infrastructure matters.  For instance, if a community’s system of communication uses a hub, then the custodian of the hub will come to play an important role.  This can be true of individual functions in the infrastructure.  How code operates shapes outcomes.  In theory, this is the same as with other infrastructure.  Railroads and railroad barons shaped nations, as did steamships and electric grids.  The difference with software code may be the speed and breadth of impact, and the complexity of the interactions.

Our subject here is “coding law.”  As compared to the other phrases, coding law is modest, conventional, incremental, prosaic.  Really no more than adopting some tools and methods of programming to handle the text of legal instruments – contracts, permits, by-laws, etc.  There is no theoretical leap, merely better efficiency.  But the current methods of handling text are so inefficient that the practical effect of efficiency will be large; the cost, delay and confusion of defining legal relationships will shrink and come to approach zero.  For those of us who think that the legal tradition includes deep, useful “experience” (Holmes) and that decentralization, difference and autonomy are important, the continuity and widely shared competence in conventional legal text are advantages.  Contracts and other legal documents already form a system of significantly decentralized governance – the “law of the parties,” party-driven legislation of very local effect.  Coding law allows this to become efficient and to compete with more technical approaches.

With that as introduction, let us dive directly and deeply into documents, beginning with contracts. To move from broad theory to a few specific observations and suggestions.

The Elements of Contract Agreements

Note that our subject here is not contract theory.  We are not concerned with offer and acceptance, calculation of damages, enforceability or the other material of law school contracts.  Our focus is on the mechanics of documents.  Nor are we attempting to catalog various approaches or styles.  Our goal is to define an efficient, extensible approach to the text of contract agreements.

Abstractly, contracts consist of:

  1. Identification of parties;
  2. A goal;
  3. Some facts;
  4. A paradigm for the transaction;
  5. Details of assumed circumstances and what ifs;
  6. Adoption by the parties.

Textually, contract agreements consist of:

  1. Header;
  2. Parties;
  3. Recitals;
  4. Provisions;
  5. Signature;
  6. Annexes.

We can “codify” this directly. Begin/  (This more complex form shows a relatively complete approach, including a variety of languages – Agt5_Languages.)

Provisions (Sec)

We will return to the other parts, but let us first look at the meat of the agreement, the provisions, or what we will call its sections.  Sections of course also have structure.  When coding, we will use the abbreviation of “Sec” to mean a section and its title.  We will use “Ti” to refer to  “sec” to mean the section without its title.  The Provisions can be understood as a list of these Sections, and each Section with the same structure.  Begin/

Notice in that example that we referenced Begin/ We can “extend” Begin/ and any other record in the system by referencing and then adding to or overriding elements.

The structure of Section Text (sec)

Sections in contracts come in a variety of organizations.  They can be a single paragraph or can have subsections. When there are subsections, there can also be a head paragraph or paragraphs introducing the subsections and perhaps a tail paragraph or paragraphs following them.  If the subsections have numbers from 1.Sec to 999.Sec then we can think of the head paragraph as 0.sec and the tail paragraph as 00.Sec.  We generalize this as follows:

  1. {Secs}


which provides:

  1. {Secs}

For example: Begin/

If there is no head paragraph, it can be eliminated by making 0.sec= or any other html string that does not produce a text effect.

If the section is just a block of text then we simply say so:

sec=The text of the section.

For example: Begin/

Subsections (Secs) and “Prefixing”

The subsections can be numbered or not numbered.  Numbering can be by 3., or C., or c., or III., or iii., any of a variety.  Unnumbered sections can be indented or can be unindented paragraphs.

As an aid for handling subsections in their great variety, we made a collection of widgets that do each of those things.  They are listed under “Z/“.  These also are used by reference.  For instance, we can expand the Miscellaneous section with five subsections, by adding “Misc.=[Z/ol/5].”  Begin/   Note that the subsections are numbered 1,2,3,4,5.  We could change that to a,b,c,d,e by referencing Misc.=[Z/ol-a/5], or to i, ii, iii, iv, v by referencing Misc.=[Z/ol-i/5].  We could eliminate the numbers with Misc.=[Z/ol-none/5].  And eliminate the intent with Misc.=[Z/paras/5], making them into normal paragraphs.  In each case, we could eliminate the titles, and have only the text by adding a small “s” in front of the number of sections – Misc.=[Z/ol-i/s5] would give us i,ii,iii,iv,v without titles.

Notice that this reference is “prefixed” with “Misc.”.  That means that each element of the outline is treated as if prefixed with “Misc.”.  For instance, in Z/ol/5, there is {Ti}, {1.Ti} and {1.sec}.  Each of these is treated as {Misc.Ti}, {Misc.1.Ti} and {Misc.1.sec}.  This allows pieces of text to be snapped together in new combinations, all based on the organization of names.

A General Theory of Contract Coding

With the basic mechanics as background, let’s turn to good document practices.  A few things seem clear, though we anticipate some contrary opinions or refinements.

  1. Defined terms used in a document should be parameterized.  That is to say, “Confidential Information subject to this Agreement ….” should read “{_Confidential_Information} subject to this {_Agreement} ….”  Note the convention of preceding the defined term with an underscore.  This makes the role as defined term clear.  It also allows us to reference a list of defined terms with a prefix of “_”, which reduces chances of “name space collision.”  The parameterized terms can be colored or highlighted, and they can be made into links that take the reader to the part of the document where the term is defined.  We can make a common list of defined terms that can be used across many different agreements – F/US/00/Agt/Base/DefinedTerms/00/
  2. Ideally, definitions should be collected into a Definitions section, instead of scattered about the document, inline.  If there is a strong reason to define them elsewhere, then the Definitions section should also have the term and link to the place where the term is defined.
  3. Sections should have headings.
  4. Sentences should be short.
  5. Sections should be ordered in a consistent way across different types of agreements.  This cannot always be respected, but there can be a great deal of harmony.
  6. Sections should be reused.  A confidentiality section, or dispute resolution, or any of the many common sections should be drawn from libraries.  This is the same principle as using defined terms – use defined sections.
  7. Re-use should be by referencing or linking, rather than copying.  Coding in CommonAccord permits both reading a document as a list of links, and as the full-text document.
  8. Links should be descriptive.
  9. We must handle the “version problem.”  This is the problem that the target of a reference or link might change.  There are a variety of ways to handle this that are manageable and not inconsistent.