size_categories:1M<n<10M language:en license:cc0-1.0 united states law legal court opinions region:us
---
license: cc0-1.0
language:
- en
tags:
- united states
- law
- legal
- court
- opinions
size_categories:
- 1M<n<10M
viewer: true
configs:
- config_name: jsonl
  data_files: "cold.jsonl/*"
- config_name: parquet
  data_files: "cold.parquet/*"
  default: true
---

<a href="https://huggingface.co/datasets/harvard-lil/cold-cases/resolve/main/coldcases.png"><img src="https://huggingface.co/datasets/harvard-lil/cold-cases/resolve/main/coldcases-banner.webp"/></a>

# Collaborative Open Legal Data (COLD) - Cases

COLD Cases is a dataset of 8.3 million United States legal decisions with text and metadata, formatted as one JSON object per decision.
The total dataset size is approximately 104GB of uncompressed JSON.

This dataset exists to support the open legal movement exemplified by projects like
[Pile of Law](https://huggingface.co/datasets/pile-of-law/pile-of-law) and 
[LegalBench](https://hazyresearch.stanford.edu/legalbench/).
A key input to legal understanding projects is caselaw -- the published, precedential decisions of judges deciding legal disputes and explaining their reasoning.
United States caselaw is collected and published as open data by [CourtListener](https://www.courtlistener.com/), which maintains scrapers to aggregate data from
a wide range of public sources.

COLD Cases reformats CourtListener's [bulk data](https://www.courtlistener.com/help/api/bulk-data) so that all of the semantic information about each legal decision 
(the authors and text of majority and dissenting opinions; head matter; and substantive metadata) is encoded in a single JSON object per decision, 
with extraneous data removed. Serving in the traditional role of libraries as a standardization steward, the Harvard Library Innovation Lab is maintaining
this [open source](https://github.com/harvard-lil/cold-cases-export) pipeline to consolidate the data engineering for preprocessing caselaw so downstream machine
learning and natural language processing projects can use consistent, high quality representations of cases for legal understanding tasks.

Prepared by the [Harvard Library Innovation Lab](https://lil.law.harvard.edu) in collaboration with the [Free Law Project](https://free.law/).

---

## Links
- [Data nutrition label](https://datanutrition.org/labels/v3/?id=c29976b2-858c-4f4e-b7d0-c8ef12ce7dbe) (DRAFT). ([Archive](https://perma.cc/YV5P-B8JL)).
- [Pipeline source code](https://github.com/harvard-lil/cold-cases-export)

---

## Summary
- [Formats](#formats)
- [File structure](#file-structure)
- [Data dictionary](#data-dictionary)
- [Notes on appropriate use](#appropriate-use)

---

## Formats

We've released this data in two different formats:

### JSON-L or JSON Lines

This format consists of a JSON document for every row in the dataset, one per line. This makes it easy to sample a selection of the data or split it out into multiple files for parallel processing using ordinary command line tools such as `head`, `split` and `jq`. 

Just about any language you can think of has a ready way  to parse JSON data, which makes this version of the dataset more compatible. 

See: https://jsonlines.org/

### Apache Parquet

Parquet is binary format that makes filtering and retrieving the data quicker because it lays out the data in columns, which means columns that are unnecessary to satisfy a given query or workflow don't need to be read. 

Parquet has more limited support outside the Python and JVM ecosystems, however.

See: https://parquet.apache.org/

[☝️ Go back to Summary](#summary)

---

## File structure

Both of these datasets were exported by the same system based on [Apache Spark](https://spark.apache.org/), so within each subdirectory, you'll find a similar list of files:

- **_SUCCESS**: This indicates that the job that built the dataset ran successfully and therefore this is a complete dataset.
- **.json.gz or .gz.parquet**: Each of these is a slice of the full dataset, encoded in JSON-L or Parquet, and compressed with [GZip](https://www.gnu.org/software/gzip/).
- **Hidden `.crc` files**: These can be used to verify that the data transferred correctly and otherwise ignored.

[☝️ Go back to Summary](#summary)

---

## Data dictionary

Partial glossary of the fields in the data.

| Field name | Description |
| --- | --- |
| `judges` |  Names of judges presiding over the case, extracted from the text. |
| `date_filed` |  Date the case was filed. Formatted in ISO Date format. |
| `date_filed_is_approximate` |  Boolean representing whether the `date_filed` value is precise to the day. |
| `slug` |  Short, human-readable unique string nickname for the case. |
| `case_name_short` |  Short name for the case. |
| `case_name` |  Fuller name for the case. |
| `case_name_full` |  Full, formal name for the case. |
| `attorneys` |  Names of attorneys arguing the case, extracted from the text. |
| `nature_of_suit` |  Free text representinng type of suit, such as Civil, Tort, etc. |
| `syllabus` |  Summary of the questions addressed in the decision, if provided by the reporter of decisions. |
| `headnotes` |  Textual headnotes of the case |
| `summary` |  Textual summary of the case |
| `disposition` |  How the court disposed of the case in their final ruling. |
| `history` |  Textual information about what happened to this case in later decisions. |
| `other_dates` |  Other dates related to the case in free text. |
| `cross_reference` |  Citations to related cases. |
| `citation_count` |  Number of cases that cite this one. |
| `precedential_status` |  Constrainted to the values "Published", "Unknown", "Errata", "Unpublished", "Relating-to", "Separate", "In-chambers" |
| `citations` |  Cases that cite this case. |
| `court_short_name` |  Short name of court presiding over case. |
| `court_full_name` |  Full name of court presiding over case. |
| `court_jurisdiction` | Code for type of court that presided over the case. See: [court_jurisdiction field values](#court_jurisdiction-field-values) |
| `opinions` |  An array of subrecords. |
| `opinions.author_str` | Name of the author of an individual opinion. |
| `opinions.per_curiam` | Boolean representing whether the opinion was delivered by an entire court or a single judge. |
| `opinions.type` | One of `"010combined"`, `"015unamimous"`, `"020lead"`, `"025plurality"`, `"030concurrence"`, `"035concurrenceinpart"`, `"040dissent"`, `"050addendum"`, `"060remittitur"`, `"070rehearing"`, `"080onthemerits"`, `"090onmotiontostrike"`. |
| `opinions.opinion_text` | Actual full text of the opinion. |
| `opinions.ocr` | Whether the opinion was captured via optical character recognition or born-digital text. |

### court_jurisdiction field values
| Value | Description |
| --- | --- |
| F | Federal Appellate |
| FD | Federal District |
| FB | Federal Bankruptcy |
| FBP | Federal Bankruptcy Panel |
| FS | Federal Special |
| S | State Supreme |
| SA | State Appellate |
| ST | State Trial |
| SS | State Special |
| TRS | Tribal Supreme |
| TRA | Tribal Appellate |
| TRT | Tribal Trial |
| TRX | Tribal Special |
| TS | Territory Supreme |
| TA | Territory Appellate |
| TT | Territory Trial |
| TSP  | Territory Special |
| SAG | State Attorney General |
| MA | Military Appellate |
| MT | Military Trial |
| C | Committee |
| I | International |
| T | Testing |

[☝️ Go back to Summary](#summary)

## Notes on appropriate use

When using this data, please keep in mind:

* All documents in this dataset are public information, published by courts within the United States to inform the public about the law. **You have a right to access them.**
* Nevertheless, **public court decisions frequently contain statements about individuals that are not true**. Court decisions often contain claims that are disputed,
 or false claims taken as true based on a legal technicality, or claims taken as true but later found to be false. Legal decisions are designed to inform you about the law -- they are not
 designed to inform you about individuals, and should not be used in place of credit databases, criminal records databases, news articles, or other sources intended
 to provide factual personal information. Applications should carefully consider whether use of this data will inform about the law, or mislead about individuals.
* **Court decisions are not up-to-date statements of law**. Each decision provides a given judge's best understanding of the law as applied to the stated facts
 at the time of the decision. Use of this data to generate statements about the law requires integration of a large amount of context --
 the skill typically provided by lawyers -- rather than simple data retrieval.

To mitigate privacy risks, we have filtered out cases [blocked or deindexed by CourtListener](https://www.courtlistener.com/terms/#removal). Researchers who
require access to the full dataset without that filter may rerun our pipeline on CourtListener's raw data.

[☝️ Go back to Summary](#summary)