This repository is one part of the Jurism reference manager project, a variant of Zotero that supports legal and multilingual research and writing. As outlined below, jurisdiction and court identifiers are central to the project’s objectives. The notes here are aimed at Jurism users who need to extend or improve jurisdictional coverage. In the instructions that follow the introductory notes below, it is assumed that the reader is comfortable with command-line tools and has a basic familiarity with JSON syntax.
- About legal referencing requirements
- About machine-readable identifiers
- Source files and tools
- Submitting changes
By way of background, the special requirements for citation of legal resources have long been a barrier to the development of reference managers capable of handling this category of material. Legal information has a complex structure, and for clarity and accuracy, legal material should be cited in the form familiar to professionals in the target jurisdiction. This clashes with the "one size fits all" citation rules that guides such as MLA, APA, the Chicago Manual of Style apply to (what a lawyer would refer to as) secondary resources.
Properly automating citation forms across multiple jurisdictions requires, in the first instance, a system of machine-readable identifiers for each jurisdiction and (at minimum) the courts within it. These are useful for more than generating citations, of course: a properly composed identifier can concisely express the context of a resource within a hierarchy of authority, which is useful for organizing and interpreting materials.
A standard system of machine-readable jurisdiction/court identifiers does not yet exist, so we are creating one for use in Jurism, loosely based on a draft “URN:LEX” schema proposed to the IETF by Spinosa, Francesconi & Lupo in 2009. While not an official Internet standard, the proposal defines a clear and simple structure for identifers:
jp:fukuoka;hcIn the example above:
jpidentifies the top level of an independent jurisdiction (Japan in this case);fukuokais a jurisdictional subdivision of its parent. Codes for subordinate jurisdictions are connected to their parent with a colon (:).hcis a court identifer (in this case 高等裁判所, or High Court). A court code is connected to its associated jurisdiction with a semicolon (;).- The elements of an identifer must be written in roman characters (including optionally the period (
.) and tilde (~) characters—Latin-1 and other accented or non-roman chararacters are not allowed.
Apart from the constraints listed above, identifiers can be assigned arbitrarily; but once assigned, identifiers should not be changed. Accordingly, if you make local changes to the identifier system following the instructions below, it is important to submit your changes to the Jurism project, so that they can be adopted as a (de facto) standard for all users.
Identifiers and abbreviations are closely related. Both are defined in individual country-specific source files held in the Legal Resource Registry (LRR), along with software tools used to deploy identifiers and abbreviations into the Jurism client. The LRR content is not shipped with the Jurism desktop client: it must be installed separately to manipulate Jurism’s identifier system.
To set up for editing the Jurism identifiers, you will need a GitHub account, and both git and nodejs must be installed on your local system. With those tools in place, let’s get started …
The first step in setting up is to fork the LRR project to your own GitHub account, by visiting the LRR project page and clicking on the Fork button:
After forking the project, fetch your project address from your own project page to the clipboard:
Use git with the project address to clone the project to a location of your choice:
shell> git clone https://github.com/XXXXXXX/legal-resource-registry.gitSet the original “upstream” LRR project as a remote partner to your clone. (This makes is possible to keep your clone current with any upstream changes):
shell> git remote add upstream https://github.com/Juris-M/legal-resource-registry.gitFor good measure, issue the command to pull in upstream changes. You should issue this command each time you begin work in the clone, to be sure the upstream project has not changed in the meantime:
shell> git pull upstream masterEnter the scripts subdirectory of the project folder, install dependencies, and link the maintenance script (jurisupdate) to your command environment:
shell> cd legal-resource-registry/scripts
shell> npm install
shell> npm linkAt this point, running the jurisupdate command should yield the following error:
shell> jurisupdate
ERROR: path.dataDir is undefined in /MY/HOME/DIRECTORY/.jurisUpdateThe final step in setup is to set several path names in the .jurisUpdate configuration
file shown in the error message, using a text editor. The file content will initially look
like this, with null values for the paths:
{
"path": {
"jurisSrcDir": null,
"jurisMapDir": null,
"jurisAbbrevsDir": null
}
}The paths should be set as follows:
jurisSrcDir
- Set
jurisSrcDirto the path of thesrcsubdirectory of your cloned copy of the LRR.
jurisMapDir and jurisAbbrevsDir
- If these values are left unset, compiled jurisdiction data will be written into the
juris-mapandjuris-abbrevssubdirectories of the data directory. This is normally what you want to do.
With these adjustments in place, the jurisupdate command should return the following
error message:
shell> jurisupdate
ERROR: One of -a or -j is required.If that all checks out, setup is complete and you’re ready to go.
Running the jurisupdate command with the -h option will show its help text:
shell> jurisupdate -h
Usage: index.js <options>
-a, --all
Perform requested operation on all jurisdictions.
-j <jurisdictionID>, --jurisdiction=<jurisdictionID>
Perform requested operation on the specified jurisdiction.
-c, --convert
Convert from old descriptive format to new descriptive format
-l, --list
List codes for all international organizations and countries [with their languages]
-F --force
Force overwrite of same data for descriptive-to-compact.To make changes to the Jurism identifier system, you will edit source files in the LRR, and run the following command to make your changes available when the Jurism client is (re)started:
shell> jurisupdate -aAlternatively, you can limit an update to a particular jurisdiction by setting its code with the -j option:
shell> jurisupdate -j vnJurisdiction names and abbreviations are stored in desc files, one per top-level jurisdiction,
with three top-level keys: langs, courts, and jurisdictions. Here is a minimal file,
for a jurisdiction with no courts and only one language:
juris-zz-desc.json
{
"langs": {},
"courts": {},
"jurisdictions": {
"zz": {
"name": "Atlantis"
}
}
}Here is a minimal file for a jurisdiction with one language and just one top-level court.
Note the sc key shared between courts and jurisdictions.zz.courts. This
links the court described in the former to the context of the latter.
{
"langs": {},
"courts": {
"sc": {
"name": "Supreme Court"
}
},
"jurisdictions": {
"zz": {
"name": "Atlantis",
"courts": {
"sc": {}
}
}
}
}Multiple courts and sub-jurisdictions can be expressed by adding keys
to the courts and jurisdictions objects. In the example
below, note the following:
- Keys may include a full stop (
.) as well as lowercase ASCII characters. - In
jurisdictionskeys, sub-jurisdiction elements are delimited by a colon (:). - In the
jurisdictionsobject, sub-jurisdictions should follow their parents.
Also note the following about the use of name and the abbrev
element introduced in this example:
-
In the
abbrevelement of acourtsobject, a%splaceholder may be used. When generating a court abbreviation, the placeholder is replaced with the jurisdictionabbrev(or, if that is not available, the jurisdictionname). In the sample below, the abbreviation ofzz:east;court.appealwill be E. Atl. Ct. App. -
The
namevalue is used to build menu items in a user interface. The courtnameshould therefore not contain a%splaceholder.
{
"langs": {},
"courts": {
"sc": {
"name": "Supreme Court",
"abbrev": "Sup. Ct."
},
"court.appeal": {
"name": "Court of Appeal",
"abbrev": "%s Ct. App."
}
},
"jurisdictions": {
"zz": {
"name": "Atlantis",
"courts": {
"sc": {}
}
}
"zz:east": {
"name": "East",
"abbrev": "E. Atl.","
"courts": {
"court.appeal": {}
}
},
"zz:west": {
"name": "West",
"abbrev": "W. Atl.",
"courts": {
"court.appeal": {}
}
}
}
}When a court abbrev contains a %s placeholder, the jurisdiction portion
can be omitted from the composed court abbreviation by setting an abbrev_select
element under the court in jurisdiction context, with a value of court. Alternatively,
the jurisdiction name can be used in lieu of the court name by setting the value to
jurisdiction.
With the sample below (illustrating a federal jurisdiction):
zz:sc→ Atlantis.zz:ag→ Att'y Gen..zz:lilliput:sc→ Lilliputian Sup. Ct.
{
"langs": {},
"courts": {
"sc": {
"name": "Supreme Court",
"abbrev": "%s Sup. Ct."
},
"ag": {
"name": "Attorney General",
"abbrev": "%s Att'y Gen."
}
},
"jurisdictions": {
"zz": {
"name": "Atlantis",
"courts": {
"sc": {
"abbrev_select": "jurisdiction"
},
"ag": {
"abbrev_select": "court"
}
}
}
"zz:lilliput": {
"name": "Lilliput",
"abbrev": "Lilliputian",
"courts": {
"sc": {},
"ag": {}
}
},
"zz:brobdingnag": {
"name": "Brobdingnag",
"abbrev": "Brobdingnagian",
"courts": {
"sc": {},
"ag": {}
}
}
}
}In the citation forms of some systems specify a special code to
represent a court in vendor-neutral citations. These are represented
with all-caps ABBREV elements, which apply the same composition
logic as abbrev.
With the sample below, the code for the Atlantis Supreme Court will be SC, and the codes for the Eastern and Western Courts of Appeal will be ECA and WCA respectively.
{
"langs": {},
"courts": {
"sc": {
"name": "Supreme Court",
"ABBREV": "SC"
},
"court.appeal": {
"name": "Court of Appeal",
"ABBREV": "%sCA"
}
},
"jurisdictions": {
"zz": {
"name": "Atlantis",
"courts": {
"sc": {}
}
}
"zz:east": {
"name": "East",
"ABBREV": "E","
"courts": {
"court.appeal": {}
}
},
"zz:west": {
"name": "West",
"ABBREV": "W",
"courts": {
"court.appeal": {}
}
}
}
}Language variants can be set by adding a variants object to a
court, jurisdiction, or court-in-jurisdiction object, with language
codes or nicknames as keys. The object set under each language key may
contain name, abbrev, ABBREV, and abbrev_select
elements, which override those of the default language.
The use of language variants in compiled output is controlled by flags
set against the language code under the langs element. Output is
of two types: user-interface data (ui), and citation-abbreviation
data (abbrevs). Each will be generated only when the relevant flag
is set. Otherwise the default values will be used.
The (purely hypothetical) sample below sets Sudanese court names as a variant. The following abbreviations would be generated in that language domain:
zz;sc→ Mahkamah Agungzz:east;ca→ *Pangadilan Banding Atl. W.zz:west;ca→ *Pangadilan Banding Atl. K.
With this sample, user-interface data would be compiled exclusively in
the default language, English. Adding ui to the langs.sd array
would include a Sudanese variant in user-interface data.
(Note that in this case the variant of the Supreme Court entry could
equally well be set on the courts.sc object—and actually should be
set there, for clarity.)
{
"langs": {
"sd": [
"abbrevs"
]
},
"courts": {
"sc": {
"name": "Supreme Court",
"abbrev": "Sup. Ct."
},
"court.appeal": {
"name": "Court of Appeal",
"abbrev": "%s Ct. App.",
"variants": {
"sd": {
"name": "Pangadilan Banding %s"
}
}
}
},
"jurisdictions": {
"zz": {
"name": "Atlantis",
"courts": {
"sc": {
"variants": {
"sd": {
"name": "Mahkamah Agung",
"abbrev": "Mahkamah Agung"
}
}
}
}
},
"zz:east": {
"name": "East",
"abbrev": "E. Atl.",
"courts": {
"court.appeal": {}
},
"variants": {
"sd": {
"name": "Wétan"
"abbrev": "Atl. W."
}
}
},
"zz:west": {
"name": "West",
"abbrev": "W. Atl.",
"courts": {
"court.appeal": {}
},
"variants": {
"sd": {
"name": "Kulon",
"abbrev": "Atl. K."
}
}
}
}
}Where the UI name or citation abbreviation of a court varies from the
general pattern set for it under courts, a specific override can
be set for it in the specific jurisdiction context that requires bespoke
treatment.
With the sample below, the following abbreviations would be generated:
zz:east;ca→ E. Ct. App.zz:west;ca→ W. Ct. Err.
{
"langs": {},
"courts": {
"sc": {
"name": "Supreme Court"
},
"court.appeal": {
"name": "Court of Appeal",
"abbrev": "%s Ct. App."
}
},
"jurisdictions": {
"zz": {
"name": "Atlantis",
"courts": {
"sc": {}
}
}
"zz:east": {
"name": "East",
"abbrev": "E.",
"courts": {
"court.appeal": {}
}
},
"zz:west": {
"name": "West",
"abbrev": "W.",
"courts": {
"court.appeal": {
"name": "Court of Error",
"abbrev": "%s Ct. Err"
}
}
}
}
}If you have written your changes into a git clone of the Legal Resource
Registry as described in the Setting up section above, you
can submit your changes for general use by pushing them to your GitHub
account, and then filing a “pull request” to invite their adoption.
The first step is a one-liner at the command line (possibly followed by
entry of your GitHub user ID and password):
shell> git commit -m "Update to Atlantis" -aAfter pushing your changes, visit the Legal Resource Registry project in your GitHub account, and file a pull request:
Follow the instructions to complete the request, and we’ll be in touch!
— Frank Bennett, Nisshin City near Nagoya, Japan, September 12, 2020