> ## Documentation Index > Fetch the complete documentation index at: https://docs.isaacus.com/llms.txt > Use this file to discover all available pages before exploring further. # Isaacus Legal Graph Schema (ILGS) > A formal specification of the Isaacus Legal Graph Schema (ILGS) The **Isaacus Legal Graph Schema (ILGS)** is a knowledge graph schema for representing the structure and entities referenced within legal documents. ILGS serves as the output format of our [document enrichment models](/models#enrichment) such as Kanon 2 Enricher, which convert unstructured documents into rich ILGS graphs. This specification formally defines version 1.0.0 of ILGS. If you're looking for a practical guide on how to use ILGS, check out our [enrichment documentation](/capabilities/enrichment). In the interests of supporting open legal AI and data research, this specification and ILGS in general are licensed under the [Creative Commons Attribution 4.0 International license](https://creativecommons.org/licenses/by/4.0/deed.en), which allows anyone to share and adapt ILGS for any purpose, even commercially, as long as they [cite](#citation) Isaacus. ## Overview **ILGS** is first and foremost a schema for representing information expressed in documents. Accordingly, the root of every ILGS graph is a [Document](#document) node and every other node in an ILGS graph is anchored to a Document node through [Span](#span) nodes. Span nodes are well-nested, globally laminar (ie, non-crossing) text spans representing discrete portions of content. Because Spans are well-nested and laminar, they implicitly form (after collapsing duplicates) an ordered, rooted containment tree of intervals within a document's text. This makes traversal, rendering, and reasoning over documents trivial. Depth-first search, for example, can be used to navigate Spans efficiently with linear complexity in the worst case. Further, stacks can be used to render Spans into human-readable markup languages such as HTML, XML, and Markdown. In addition to modeling the textual structure of documents through Spans, ILGS also models transtextual and non-textual entities such as [External Documents](#external-document), [Locations](#location), and [Persons](#person). These entities, although anchored to Spans, can have relationships that transcend the textual structure of a document. [Quotes](#quote), for instance, can be attributed to Persons, and Persons can, in turn, be linked to other Persons as parent entities, Locations as their places of residence, and personal information such as [Emails](#email), [Websites](#website), [Phone Numbers](#phone-number), and [ID Numbers](#id-number). ILGS' ability to simultaneously model textual structure and transtextual and non-textual entities in a single shared, document-grounded graph makes it especially useful for applications requiring one or more of the following: 1. **World modeling**: ILGS offers rich global attributes for world entities such as people, places, and times that can be linked across documents to build a knowledge graph of the world as represented through a corpus. 2. **Contextualization**: ILGS allows arbitrary slices of a document to be understood with respect to the document as a whole as well as the world at large through span-level annotations of entities and their relationships. 3. **Markup**: ILGS labels both local and global textual and hypertextual features of documents such as headings, junk text, sections, crossreferences, terms, and quotations, enabling documents to be rendered in rich human-readable formats such as HTML, DOCX, and Markdown. ## Concepts An **ILGS graph** is a graph of **nodes**, **attributes**, and **relationships** rooted in a [Document](#document) node and anchored to a Document's text through [Span](#span) nodes. There are 14 types of **nodes** representable in ILGS: 1. [Document](#document): a real-world document constituting the root of an ILGS graph under which all other nodes live. 2. [Span](#span): a well-nested and globally laminar span of Unicode code points representing a discrete portion of a Document's content. 3. [Segment](#segment): a structurally distinct section of a Document. 4. [Crossreference](#crossreference): a reference from a Span to a single Segment or span of Segments. 5. [Location](#location): a place identified in a Document. 6. [Person](#person): a legal person (eg, an individual, company, or government) identified in a Document. 7. [Email](#email): an email address identified in a Document as belonging to a Person. 8. [Website](#website): a website identified in a Document as belonging to a Person. 9. [Phone Number](#phone-number): a phone number identified in a Document as belonging to a Person. 10. [ID Number](#id-number): an ID number identified in a Document as belonging to a Person. 11. [Term](#term): a term assigned a defined meaning within a Document. 12. [External Document](#external-document): an external document referenced in a Document. 13. [Quote](#quote): a quotation in a Document. 14. [Date](#date): a date identified in a Document belonging to a [supported date type](#type-date-type). Every node has a set of required **attributes**. Attributes may take on a primitive type (eg, a string or integer), node, reference to a node, or product, union, or other combination thereof. A node may have a **relationship** with another node by either being contained within one of its attributes or containing it within an attribute (eg, Persons live under a Document's [`persons`](#persons-arrayperson) attribute) or through a reference to its ID (eg, a Quote can be attributed to a source Person through its [`source_person`](#source_person-id-|-null) attribute containing the Person's ID). ### IDs Some ILGS nodes will have **IDs**, which are unique string identifiers used to refer to nodes from other nodes. IDs are formatted as `{type_code}:{identifier}`, where `{type_code}` is a lowercase code representing the node's type (eg, `per` for Persons) and `{identifier}` is a string identifier that is unique within the node type. ### Isaacus Jurisdiction Codes (IJCs) Documents and External Documents have a special `jurisdiction` attribute formatted as an **Isaacus Jurisdiction Code (IJC)**, a unique string identifier for a legal jurisdiction. IJCs are formatted as a first-level jurisdiction code optionally followed by, where known and applicable, a hyphen and a second-level jurisdiction code. First-level jurisdiction codes are either uppercase ISO 3166-1 alpha-2 two-letter country codes or `INT` for international law or `EU` for European Union law. Second-level jurisdiction codes are either uppercase ISO 3166-2 subdivision codes or `FED` for the federal jurisdiction of a country with a federal system. `US`, `GB-ENG`, and `INT` are examples of valid IJCs, while `US-ENG`, `INT-UN`, `GB-FED`, and `AUS` are not. ## Nodes This section defines the 14 types of nodes representable in ILGS, their attributes, relationships, and constraints. ### Document A **Document** represents a real-world document and serves as the root of an ILGS graph under which all other nodes live. The attributes of Documents are provided below. #### `version (Version)` `version` is a string representing the major version of ILGS a Document conforms to in the format `{schema}@{number}`, where `{schema}` is the name of the schema (ie, `ilgs`) and `{number}` is the major version number (eg, `1`). Currently, the only possible value for this attribute is `ilgs@1`. #### `text (string)` A Document's `text` attribute represents its full, original text. #### `title (Span | null)` `title` points to a [Span](#span) corresponding to a Document's title if known and extractable, and is `null` otherwise. A `title` Span cannot overlap with a [`subtitle`](#subtitle-span-|-null) Span (ie, it cannot contain, be contained within, or be identical to a `subtitle` Span). #### `subtitle (Span | null)` `subtitle` points to a [Span](#span) corresponding to a Document's subtitle if known, extractable, and the Document has a [`title`](#title-span-|-null), and is `null` otherwise. A Document will only be considered to have a subtitle if it is clearly demarcated from the Document's title. A Document without a `title` cannot have a `subtitle`. A `subtitle` Span cannot overlap with a `title` Span. #### `type (Document Type)` `type` is a string representing a Document's type, being one of the following: * `statute`: primary legislation such as acts, bills, codes, and constitutions. * `regulation`: secondary legislation such as rules, statutory instruments, and ordinances. * `decision`: judicial or quasi-judicial decisions such as court judgments, judicial opinions, and tribunal rulings. * `contract`: agreements such as contracts and covenants. * `other`: all other types of documents that do not fit into any of the predefined types. #### `jurisdiction (IJC | null)` `jurisdiction` represents the jurisdiction of a Document formatted as an [IJC](#isaacus-jurisdiction-codes-ijcs) if known, and is `null` otherwise. #### `segments (array[Segment])` `segments` contains an array of [Segments](#segment) representing structurally distinct sections of a Document's content. #### `crossreferences (array[Crossreference])` `crossreferences` contains an array of [Crossreferences](#crossreference) representing references from [Spans](#span) to individual [Segments](#segment) or spans of Segments within a Document. #### `locations (array[Location])` `locations` contains an array of [Locations](#location) identified within a Document. #### `persons (array[Person])` `persons` contains an array of [Persons](#person) identified within a Document. #### `emails (array[Email])` `emails` contains an array of [Emails](#email) identified within a Document as belonging to [Persons](#person). #### `websites (array[Website])` `websites` contains an array of [Websites](#website) identified within a Document as belonging to [Persons](#person). #### `phone_numbers (array[Phone Number])` `phone_numbers` contains an array of [Phone Numbers](#phone-number) identified within a Document as belonging to [Persons](#person). #### `id_numbers (array[ID Number])` `id_numbers` contains an array of [ID Numbers](#id-number) identified within a Document as belonging to [Persons](#person). #### `terms (array[Term])` `terms` contains an array of [Terms](#term) assigned definite meanings within a Document. #### `external_documents (array[External Document])` `external_documents` contains an array of [External Documents](#external-document) referenced within a Document. #### `quotes (array[Quote])` `quotes` contains an array of [Quotes](#quote) within a Document. #### `dates (array[Date])` `dates` contains an array of [Dates](#date) identified within a Document belonging to a [supported date type](#type-date-type). #### `headings (array[Span])` `headings` contains an array of [Spans](#span) corresponding to headings within a Document. `headings` cannot be nested within each other. #### `junk (array[Span])` `junk` contains an array of [Spans](#span) corresponding to non-operative, non-substantive junk content such as headers, footers, page numbers, and OCR artifacts. `junk` Spans cannot be nested within each other. ### Span A **Span** is a span of Unicode code points constituting a discrete portion of a [Document](#document)'s content. Spans are used to represent references to entities (eg, pinpoints), textual attributes of entities (eg, names), and the textual structure of a Document (eg, headings), all grounded in a Document's text. The start and end of a Span are defined by its [`start`](#start-integer) and [`end`](#end-integer) attributes. Spans are zero-based. The first Unicode code point in a Document is at index $0$. Spans are half-open. The `end` of a Span is exclusive. Thus, a Span with the `start` $0$ and `end` $5$ would cover the Unicode code points at indices $0$, $1$, $2$, $3$, and $4$, but not $5$. Spans cannot be empty. The `start` index must always be less than the `end` index. The `start` index of a Span will always land on a non-whitespace character, and the index immediately preceding the `end` index of a Span will always land on a non-whitespace character. All Spans anywhere in a Document are well-nested and laminar with respect to each other. It is impossible for any two Spans to partially overlap. Spans can only be either completely disjoint or wholly contained. No two Spans of the same type (ie, representing the same attribute of the same node type) can be duplicated or have the exact same pair of `start` and `end` indices. Some Spans and groups of Spans are incapable of nesting. For example, [`headings`](#headings-arrayspan) cannot be nested within themselves, and [`title`](#title-span-|-null)s and [`subtitle`](#subtitle-span-|-null)s as a group cannot be nested. Some Span groups are also incapable of overlapping. Overlapping includes containment and duplication. Note that when using programming languages other than Python (which uses zero-based, half-open, Unicode code point-spaced string indexing), Span indices may need to be translated accordingly. For example, JavaScript slices into UTF-16 code units instead of Unicode code points. #### `start (integer)` `start` is the index of the first Unicode code point covered by a Span starting at $0$. `start` will always be less than [`end`](#end-integer) and will never land on whitespace. #### `end (integer)` `end` is the index of the first Unicode code point not covered by a Span starting at $0$. For example, a Span covering the first five Unicode code points of a [Document](#document) ($0$, $1$, $2$, $3$, and $4$) would have an `end` of $5$. `end` will always be greater than [`start`](#start-integer). The Unicode code point immediately preceding `end` will never be whitespace (ie, the actual end of a Span). ### Segment A **Segment** constitutes a structurally distinct section of a [Document](#document)'s content. Segments are used to model the structure of a Document such as its chapters, articles, clauses, paragraphs, and items. Every Segment corresponds to a single [Span](#span). Segment Spans can be nested. When a Segment contains another Segment, the former is considered the parent and the latter the child. There is no limit on the number of children a Segment can have, nor is there a maximum depth of Segment nesting. #### `id (ID)` `id` is an [ID](#ids) for a Segment formatted as `seg:{identifier}`. #### `kind (Segment Kind)` `kind` is a string representing the structural type of a Segment, being one of the following: * `container`: a structural or semantic grouping of content, such as a chapter. `container`s can contain Segments of any Kind or none at all. * `unit`: a single syntactically independent unit of text such as a paragraph. `unit`s can only contain `item`s and `figure`s. * `item`: a syntactically subordinate unit of text such as an item in a run-in list. `item`s can only contain other `item`s. `item`s are conceptually distinct from list items—it is perfectly possible to encounter list items that are syntactically independent of their surrounding items just as it is possible to encounter dependent clauses that do not appear as part of a list. * `figure`: a visually structured or tabular unit of content, such as a diagram, equation, or table. `figure`s cannot contain Segments. #### `type (Segment Type | null)` `type` is a string representing the addressable type of a Segment within a [Document](#document)'s referential scheme and hierarchy, whether defined explicitly (eg, by headings, such as "Section 2. Definitions"), implicitly (eg, by way of reference, such as "as defined in Section 2"), or by convention (eg, \[42] in a judgment often denotes a `paragraph`, independent provisions in statute are often `section`s, etc.). If a Segment's addressable type is not known, its `type` will be set to `null`. Although many Segment Types lexically coincide with syntactic constructs, they should be thought of purely as distinct formal citable units. Most paragraphs in the syntactic sense will not have the `paragraph` type, for example. That type is reserved for Segments that would formally be cited as a "Paragraph" within a Document's referential scheme. The following Segment Types are supported: * `title` * `book` * `part` * `chapter` * `subchapter` * `division` * `subdivision` * `subpart` * `subtitle` * `table_of_contents` * `article` * `section` * `regulation` * `rule` * `clause` * `paragraph` * `subarticle` * `subsection` * `subregulation` * `subrule` * `subclause` * `subparagraph` * `item` * `subitem` * `point` * `indent` * `schedule` * `annex` * `appendix` * `exhibit` * `recital` * `signature` * `note` * `figure` * `table` * `formula` The following Segment Types are exclusive to the `container` Segment Kind: * `title` * `book` * `part` * `chapter` * `subchapter` * `division` * `subdivision` * `subpart` * `subtitle` * `table_of_contents` The `figure` [Segment Kind](#kind-segment-kind) only supports the following Segment Types, which are also all exclusive to it: * `figure` * `table` * `formula` All other combinations of Segment Kinds and Segment Types are possible. #### `category (Segment Category)` `category` is a string representing the functional category of a Segment, being one of the following: * `front_matter`: non-operative contextualizing content occurring at the start of a [Document](#document) such as a preamble or recitals. * `scope`: operative content defining the application or interpretation of a Document such as definition sections and governing law clauses. * `main`: operative, non-scopal content. * `annotation`: non-operative annotative content providing explanatory or referential information such as commentary, footnotes, and endnotes. * `back_matter`: non-operative contextualizing content occurring at the end of a Document such as authority statements. * `other`: content that does not fit into any of the other categories. #### `type_name (Span | null)` `type_name` is a [Span](#span) within a Segment defining its type (for example, "Section" in "Section 2 - Definitions") or `null` if no such Span exists. The `type_name` of a Segment is conceptually distinct from its [Type](#type-segment-type-|-null). Segment Types are classifications, whereas a Segment's `type_name` may correspond to a type not currently supported by ILGS, for example, a "Volume". A Segment's `type_name` Span must occur within the bounds of the Segment's Span and cannot overlap with another `type_name`, [`code`](#code-span-|-null), or [`title`](#title-span-|-null-2) Span. #### `code (Span | null)` `code` is a [Span](#span) within a Segment defining its code, number, letter, or other designator (for example, "2" in "Section 2 - Definitions") or `null` if no such Span exists. A Segment's `code` Span must occur within the bounds of the Segment's Span and cannot overlap with another `code`, [`type_name`](#type_name-span-|-null), or [`title`](#title-span-|-null-2) Span. #### `title (Span | null)` `title` is a [Span](#span) within a Segment corresponding to its title or `null` if no such Span exists. A Segment's `title` Span must occur within the bounds of the Segment's Span and cannot overlap with another `title`, [`type_name`](#type_name-span-|-null), or [`code`](#code-span-|-null) Span. #### `parent (ID | null)` `parent` is the ID of the parent Segment immediately containing a Segment or `null` if the Segment has no parent (ie, it is a root-level Segment). Segments with the `container` and `unit` [Kinds](#kind-segment-kind) can only have Segments with the `container` Kind as parents or `null`. `item`s cannot have `figure`s as parents. `figure`s cannot have `item`s or `figure`s as parents. #### `children (array[ID])` `children` is an array of IDs of Segments immediately contained within a Segment. Segments with the `container` [Kind](#kind-segment-kind) can contain Segments of any Kind. `unit`s can only contain `item`s and `figure`s. `item`s can only contain other `item`s. `figure`s cannot contain any Segments. #### `level (integer)` `level` is a non-negative integer representing a Segment's depth within a [Document](#document)'s Segment hierarchy starting from $0$ for root-level Segments. #### `span (Span)` `span` is a [Span](#span) corresponding to the text of a Segment. ### Crossreference A **Crossreference** represents a reference within a [Document](#document) to a single [Segment](#segment) or span of Segments. #### `start (ID)` `start` is the ID of the earliest [Segment](#segment) in the [Document](#document) referenced by a Crossreference. Where a Crossreference targets a single Segment, its `start` and [`end`](#end-id) will be identical. Where a span of Segments is targeted, the `start` of a Crossreference will correspond to the Segment targeted by the span having the earliest [Span](#span) [`start`](#start-integer) index and, in cases where multiple targeted Segments share the same `start`, the largest Span [`end`](#end-integer) index (ie, the longest or shallowest targeted Segment starting at the earliest location). For example, suppose there was a Crossreference targeting "Sections 2(a)–10" and there were three Segments starting at the same place where Section 2(a) started: Sections 2, 2(a), and 2(a)(i). Even though Section 2 is the largest Segment starting at that location, it is not being targeted by the Crossreference. Accordingly, the `start` of the Crossreference would be Section 2(a), not Section 2, nor Section 2(a)(i), which would be smaller than Section 2(a). #### `end (ID)` `end` is the ID of the latest [Segment](#segment) in the [Document](#document) referenced by a Crossreference. Where a Crossreference targets a single Segment, its `end` and [`start`](#start-id) will be identical. Where a span of Segments is targeted, the `end` of a Crossreference will correspond to the Segment targeted by the span having the latest [Span](#span) [`end`](#end-integer) index and, in cases where multiple targeted Segments share the same `end`, the smallest Span [`start`](#start-integer) index (ie, the longest or shallowest targeted Segment ending at the latest location). For example, suppose there was a Crossreference targeting "Sections 2(a)–10" and there were three Segments ending at the same place where Section 10 ended: Part II, Section 10, and Section 10(f). Even though Part II is the largest Segment ending at that location, it is not being targeted by the Crossreference. Accordingly, the `end` of the Crossreference would be Section 10, not Part II, nor Section 10(f), which would be smaller than Section 10. #### `span (Span)` `span` is a [Span](#span) corresponding to the text of a Crossreference within a [Document](#document). No two Crossreference Spans can overlap. ### Location A **Location** represents a place identified within a [Document](#document). Merely referring to a place without expressly identifying it will not result in a Location. For example, the city referred to in the phrase "I will be in the city tomorrow", would not constitute a Location because the identity of the city is not known. By contrast, "New York" in "I will be in New York tomorrow" would constitute a Location. A Location can have a parent Location and any number of child Locations. Location containment is determined jurisdictionally and not geographically. For example, the United States would be the parent of Puerto Rico but would not be contained within the Americas since the Americas is not a legal jurisdiction. Because Locations will only exist in a Document where they are identified in it, it is possible for a Location to have a known parent but have no [`parent`](#parent-id-|-null) Location set and it is possible for a Location to have a `parent` Location that is not its most immediate parent but is the most immediate parent among the Locations identified in a Document. For example, in the text "Melbourne is a city in Australia", there would be two Locations, one for Melbourne and the other for Australia, and the Location corresponding to Melbourne would have its `parent` set to the ID of the Location corresponding to Australia while the Location corresponding to Australia would have its `parent` set to `null`. If the text were instead "Melbourne is a city in the state of Victoria in Australia", Melbourne's parent would become Victoria instead of Australia. #### `id (ID)` `id` is an [ID](#ids) for a Location formatted as `loc:{identifier}`. #### `name (Span)` `name` is a [Span](#span) within a [Document](#document) representing the most proper name of a Location. As an example, a Location referred to as "New York City" in two places in a Document, "NYC" in three places, and "the Big Apple" in one place would have its `name` set to whichever Span most confidently represented the proper name of the Location, being one of the "New York City" Spans. No two Location `name` Spans can overlap, nor can they overlap with any Location's [`mentions`](#mentions-arrayspan) Spans except that every Location's `name` Span will always also appear in its `mentions`. #### `type (Location Type)` `type` is a string representing the type of a Location, being one of the following, in order of least to most granular, ignoring the `other` type: * `country` * `state` * `city` * `address` * `other` Locations can only contain Location Types no less granular than their own Type unless their Type is `other`. For example, a Location with the `state` Type can only have `city`, `address`, and `other` Types as children, but not `country` Types. #### `parent (ID | null)` `parent` is the ID of whichever Location most immediately contains a Location or `null` if the Location has no ancestors identified in the [Document](#document). A `country` can only have another `country` as its parent or a Location with the `other` [Type](#type-location-type). A `state` can only have a `state` or `country` as its parent or a Location with the `other` Type. A `city` can only have a `city`, `state`, or `country` as its parent or a Location with the `other` Type. An `address` can have a Location of any Type as its parent. It is impossible for a Location to be its own ancestor at any level. #### `children (array[ID])` `children` is an array of IDs of Locations having a Location as their parent. A `country` can have Locations of any [Type](#type-location-type) as children. A `state` can have Locations with the `state`, `city`, `address`, and `other` Types as children. A `city` can have Locations with the `city`, `address`, and `other` Types as children. An `address` can have Locations with the `address` and `other` Types as children. #### `mentions (array[Span])` `mentions` is an array of [Spans](#span) corresponding to all mentions of a Location within a [Document](#document), including its `name` Span. Thus, `mentions` will always contain at least one Span. No two Spans in any Location's `mentions` can overlap with each other, nor can they overlap with any Location's [`name`](#name-span) Span except that every Location's `name` Span will always also appear in its `mentions`. ### Person A **Person** represents a legal person identified within a [Document](#document) such as an individual, company, or government. Merely referring to a legal person without expressly identifying them will not result in a Person. For example, the client referred to in the phrase "the plaintiff attacked his client", would not constitute a Person because the identity of the client is not known. By contrast, "John Doe" in "the plaintiff attacked John Doe, his client" would constitute a Person. It is possible for a Person to be identified by a legal office such as the President of the United States or Attorney-General of Australia. A Person can have a parent Person and any number of child Persons. Person parentage is determined based on whether a Person owns, controls, is owned by, or is controlled by another Person or represents another Person where they are identified only in their capacity as a representative (eg, a director) of the other Person. Because Persons will only exist in a Document where they are identified in it, it is possible for a Person to have a known parent but have no [`parent`](#parent-id-|-null) Person set and it is possible for a Person to have a `parent` Person that is not its most immediate parent but is the most immediate parent among the Persons identified in a Document. #### `id (ID)` `id` is an [ID](#ids) for a Person formatted as `per:{identifier}`. #### `name (Span)` `name` is a [Span](#span) within a [Document](#document) representing the most proper name of a Person. As an example, a Person referred to as "Jonathan A. Doe" in two places in a Document, "John Doe" in three places, and "Mr. Doe" in one place would have their `name` set to whichever Span most confidently represented the proper name of the Person, being one of the "Jonathan A. Doe" Spans. No two Person `name` Spans can overlap nor can they overlap with any Person's [`mentions`](#mentions-arrayspan-2) Spans except that every Person's `name` Span will always also appear in its `mentions`. #### `type (Person Type)` `type` is a string representing the type of a Person, being one of the following: * `natural`: a human being in their capacity as a natural legal person, including when representing unincorporated entities such as partnerships and trusts. * `corporate`: a body corporate such as a company, incorporated partnership, or statutory corporation. * `politic`: a body politic, political entity, or part thereof such as a court, state, government, or intergovernmental organization. #### `role (Person Role | null)` `role` is a string representing the role of a Person within a [Document](#document). Supported Person Roles are documented in the table below. | | | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `plaintiff` | A party initiating the case that is the subject of a Document. | | `petitioner` | A party initiating the petition that is the subject of a Document. | | `applicant` | A party initiating the application that is the subject of a Document. | | `appellant` | A party appealing the decision that is the subject of a Document. | | `appellee` | A party responding to the appeal that is the subject of a Document if they are explicitly referred to as an "appellee". | | `claimant` | A party making a claim in the case that is the subject of a Document. | | `complainant` | A party making a complaint in the case that is the subject of a Document. | | `defendant` | A party defending against the case that is the subject of a Document. | | `respondent` | A party responding to the petition, appeal, or application that is the subject of a Document. | | `prior_authority` | An authority (eg, judge, tribunal, court) that made a prior decision in the case that is the subject of a Document. Both individual judges and courts should be annotated with this role where applicable. This is not to be used for authorities cited as precedent, only for those that made prior decisions in the same case. | | `prosecutor` | A lawyer prosecuting the case that is the subject of a Document. | | `defense_counsel` | A lawyer defending the case that is the subject of a Document. | | `amicus` | A party filing an amicus curiae brief in the case that is the subject of a Document. | | `intervener` | A party attempting to or that has intervened in the case that is the subject of a Document. | | `borrower` | A party borrowing money or other assets under the agreement that is the subject of a Document, including "mortgagors" and "debtors". | | `lender` | A party lending money or other assets under the agreement that is the subject of a Document, including "mortgagees" and "creditors". | | `guarantor` | A party guaranteeing obligations under the agreement that is the subject of a Document, including "sureties". | | `lessee` | A party leasing goods or services under the agreement that is the subject of a Document, including "tenants". | | `lessor` | A party leasing goods or services under the agreement that is the subject of a Document, including "landlords". | | `employer` | A party employing personnel under the agreement that is the subject of a Document. | | `employee` | A party employed under the agreement that is the subject of a Document. | | `licensor` | A party licensing intellectual property or other rights under the agreement that are the subject of a Document. | | `licensee` | A party licensed to use intellectual property or other rights under the agreement that are the subject of a Document. | | `franchisor` | A party granting a franchise under the agreement that is the subject of a Document. | | `franchisee` | A party granted a franchise under the agreement that is the subject of a Document. | | `buyer` | A party purchasing goods or services under the agreement that is the subject of a Document, including "purchasers", "customers", and "clients". | | `seller` | A party selling or providing goods or services under the agreement that is the subject of a Document, including "Vendors", "Suppliers", and "Service Providers" (where such parties are actually providing goods or services under the agreement). | | `contractor` | A party contracted to perform work or services under the agreement that is the subject of a Document, including "consultants". | | `shareholder` | A party holding shares or equity under the agreement that is the subject of a Document. | | `joint_venturer` | A party participating in a joint venture under the agreement that is the subject of a Document. | | `investor` | A party investing money or assets under the agreement that is the subject of a Document. | | `insurer` | A party providing insurance under the agreement that is the subject of a Document. | | `insured` | A party insured under the agreement that is the subject of a Document. | | `settlor` | A party establishing the trust that is the subject of a Document. | | `trustee` | A party managing the trust that is the subject of a Document. | | `beneficiary` | A party benefiting from the trust that is the subject of a Document. | | `enacting_authority` | An authority (eg, legislature, regulator, Minister/Secretary, President/Prime Minister, tribunal, court, judge) giving legal effect to or authorizing a Document. All relevant individuals and bodies should be annotated with this role where applicable. | | `empowered_authority` | An authority (eg, government agency, regulator, Minister/Secretary, President/Prime Minister, tribunal, court) empowered by a Document to carry out functions or duties. | | `debater` | A person participating in the debate that is the subject of a Document. | | `governing_jurisdiction` | The jurisdiction whose laws govern a Document. | | `director` | A director or other officer of a corporate legal person mentioned in a Document. | | `clerk` | A clerk, notary, or other official certifying, witnessing, filing, recording, registering, or otherwise administering a Document. | | `witness` | A witness witnessing the signing of a Document, or whose testimony is part of the case that is the subject of a Document. | | `other` | A party to the case, agreement, legislation, or regulation that is the subject of a Document that does not fit into any of the other roles. | | `non_party` | A legal person mentioned in a Document that is not a party to the case, agreement, legislation, or regulation that is the subject of a Document. | #### `parent (ID | null)` `parent` is the ID of whichever Person most immediately owns, controls, is owned by, or is controlled by a Person or represents the Person, or `null` if the Person has no known ancestor Person. It is impossible for a Person to be its own ancestor at any level. #### `children (array[ID])` `children` is an array of IDs of Persons having a Person as their parent. #### `residence (ID | null)` `residence` is the ID of a [Location](#location) corresponding to a Person's residence if known, and is `null` otherwise. #### `mentions (array[Span])` `mentions` is an array of [Spans](#span) corresponding to all mentions of a Person within a [Document](#document), including its `name` Span. Thus, `mentions` will always contain at least one Span. No two Spans in any Person's `mentions` can overlap with each other, nor can they overlap with any Person's [`name`](#name-span-2) Span except that every Person's `name` Span will always also appear in its `mentions`. ### Website A **Website** represents a website identified within a [Document](#document) as belonging to a [Person](#person). A website is conceptually distinct from a web page. `https://isaacus.com/` is both a website and a web page, whereas `https://isaacus.com/startups` is just a web page. Different web pages can constitute mentions of the same Website. Websites mentioned in a Document that are not attributable to a Person will not qualify as Website nodes. #### `url (string)` `url` is a string representing the normalized URL of a Website in the format `https://{host}/`. #### `person (ID)` `person` is the ID of the [Person](#person) to which a Website belongs. #### `mentions (array[Span])` `mentions` is an array of [Spans](#span) corresponding to all mentions of a Website within a [Document](#document) including paths and slugs that are not part of a Website's normalized URL. Website `mentions` cannot overlap with each other, nor can they overlap with the `mentions` of [Emails](#email), [Phone Numbers](#phone-number), or [ID Numbers](#id-number). ### Email An **Email** represents an email address identified within a [Document](#document) as belonging to a [Person](#person). Email addresses mentioned in a Document that are not attributable to a Person will not qualify as Email nodes. #### `address (string)` `address` is a string representing the normalized email address of an Email in the format `{local_part}@{domain}`. #### `person (ID)` `person` is the ID of a [Person](#person) to which an Email belongs. #### `mentions (array[Span])` `mentions` is an array of [Spans](#span) corresponding to all mentions of an Email within a [Document](#document). Email `mentions` cannot overlap with each other, nor can they overlap with the `mentions` of [Websites](#website), [Phone Numbers](#phone-number), or [ID Numbers](#id-number). ### Phone Number A **Phone Number** represents a phone number identified within a [Document](#document) as belonging to a [Person](#person). Phone numbers mentioned in a Document that are not attributable to a Person will not qualify as Phone Number nodes. #### `number (string)` `number` is a string representing the normalized phone number of a Phone Number in E.123 international notation conforming with local conventions on the use of spaces and hyphens as separators. #### `person (ID)` `person` is the ID of a [Person](#person) to which a Phone Number belongs. #### `mentions (array[Span])` `mentions` is an array of [Spans](#span) corresponding to all mentions of a Phone Number within a [Document](#document). Phone Number `mentions` cannot overlap with each other, nor can they overlap with the `mentions` of [Websites](#website), [Emails](#email), or [ID Numbers](#id-number). ### ID Number An **ID Number** represents an identification number identified within a [Document](#document) as belonging to a [Person](#person). ID numbers mentioned in a Document that are not attributable to a Person will not qualify as ID Number nodes. #### `number (string)` `number` is a string representing an ID number. #### `person (ID)` `person` is the ID of a [Person](#person) to which an ID Number belongs. #### `mentions (array[Span])` `mentions` is an array of [Spans](#span) corresponding to all mentions of an ID Number within a [Document](#document). ID Number `mentions` cannot overlap with each other, nor can they overlap with the `mentions` of [Websites](#website), [Emails](#email), or [Phone Numbers](#phone-number). ### Term A **Term** represents a term assigned a definite meaning within a [Document](#document). #### `id (ID)` `id` is an [ID](#ids) for a Term formatted as `term:{identifier}`. #### `name (Span)` `name` is a [Span](#span) within a [Document](#document) defining a Term's name. For example, in the phrase "'Agreement' means this contract between the parties", the defined Term's `name` would be the Span covering "Agreement". Term `name`s are distinct from references to a Term elsewhere in a Document in that references are not used to define the meaning of a Term for the first time. Unlike the `name`s of Locations and Persons, the `name` of a Term will never overlap with any of its [`mentions`](#mentions-arrayspan-7), though they may overlap with the `mentions` of other Terms. Term `name`s cannot overlap with each other. #### `meaning (Span)` `meaning` is a [Span](#span) corresponding to the meaning of a Term within a [Document](#document). For example, in the phrase "'Agreement' means this contract between the parties", the defined Term's `meaning` would be the Span covering "this contract between the parties". The `meaning` of one Term can be contained within the `meaning` of another. #### `mentions (array[Span])` `mentions` is an array of [Spans](#span) corresponding to all references to a Term within a [Document](#document) excluding its [`name`](#name-span-3) Span. Thus, `mentions` can be empty if a Term is defined but never referenced elsewhere in a Document. No two Spans in any Term's `mentions` can overlap with each other. The `mentions` of a particular Term also cannot overlap with that Term's `name` Span, though they may overlap with the `name`s of other Terms. ### External Document An **External Document** represents an external document referenced within a [Document](#document). An external document must be identified expressly for it to constitute an External Document. For example, the statute referred to in the phrase "the statute provides many defenses", would not constitute an External Document because the statute is not named. #### `id (ID)` `id` is an [ID](#ids) for an External Document formatted as `exd:{identifier}`. #### `name (Span)` `name` is a [Span](#span) representing the most proper name of an External Document of all the names by which it is referred to in a [Document](#document). As an example, an External Document referred to as the "Constitution of the United States of America" in two places in a Document, the "U.S. Constitution" in three places, and the "Constitution" in one place would have its `name` set to whichever Span most confidently represented the proper name of the External Document, being one of the "Constitution of the United States of America" Spans. #### `type (Document Type)` `type` is a string representing the type of an External Document, being one of the following: * `statute`: primary legislation such as acts, bills, codes, and constitutions. * `regulation`: secondary legislation such as rules, statutory instruments, and ordinances. * `decision`: judicial or quasi-judicial decisions such as court judgments, judicial opinions, and tribunal rulings. * `contract`: contracts, covenants, and agreements. * `other`: all other types of documents that do not fit into any of the predefined types. #### `jurisdiction (IJC | null)` `jurisdiction` represents the jurisdiction of an External Document formatted as an [IJC](#isaacus-jurisdiction-codes-ijcs) if known, and is `null` otherwise. #### `reception (External Document Reception)` `reception` represents the sentiment of a [Document](#document) towards an External Document, being one of the following: * `positive`: indicating that a Document expresses a favorable view of an External Document whether by endorsing or approving it. * `mixed`: indicating that a Document expresses both favorable and unfavorable views of an External Document, for example, by affirming some parts of it and disapproving others. * `negative`: indicating that a Document expresses an unfavorable view of an External Document whether by criticizing, repealing, overruling, or explicitly contradicting it. * `neutral`: indicating that a Document references an External Document without expressing any particular sentiment towards it. #### `mentions (array[Span])` `mentions` is an array of [Spans](#span) corresponding to all mentions of an External Document by its name. `mentions` will always contain an External Document's [`name`](#name-span-4) thus it can never be empty. `mentions` are distinct from [`pinpoints`](#pinpoints-arrayspan) which are references to sections within an External Document. For example, in the phrase "Section 6 of the Australian Constitution", "Section 6" would constitute a pinpoint reference, and "Australian Constitution" would constitute a mention. No two Spans in any External Document's `mentions` and `pinpoints` can overlap with each other, nor can they overlap with any External Document's `name` Span except that every External Document's `name` Span will always also appear in its `mentions`. #### `pinpoints (array[Span])` `pinpoints` is an array of [Spans](#span) corresponding to all references to sections within an External Document. It is possible for `pinpoints` to be empty if there are no such references. `pinpoints` are distinct from [`mentions`](#mentions-arrayspan-8) which are mentions of an External Document by name. For example, in the phrase "Section 6 of the Australian Constitution", "Section 6" would constitute a pinpoint reference, and "Australian Constitution" would constitute a mention. No two Spans in any External Document's `pinpoints` and `mentions` can overlap with each other, nor can they overlap with any External Document's [`name`](#name-span-4) Span except that every External Document's `name` Span will always also appear in its `mentions`. ### Quote A **Quote** is a quotation within a [Document](#document). Quotes can be attributed to [Persons](#person), [Segments](#segment), and [External Documents](#external-document). They cannot, however, be simultaneously attributed to both a Segment and an External Document. They can also be attributed to nothing. #### `source_segment (ID | null)` `source_segment` is the [ID](#ids) of the [Segment](#segment) that is the origin of a Quote or `null` if the Quote is not from a Segment. `source_segment` and [`source_document`](#source_document-id-|-null) cannot both be set. #### `source_document (ID | null)` `source_document` is the [ID](#ids) of the [External Document](#external-document) that is the origin of a Quote or `null` if the Quote is not from an External Document or the external document it is from is not known. `source_document` and [`source_segment`](#source_segment-id-|-null) cannot both be set. #### `source_person (ID | null)` `source_person` is the [ID](#ids) of the [Person](#person) from which a Quote originates or `null` if the Quote is not from a Person or the person it is from is not known. #### `amending (boolean)` `amending` is a boolean indicating whether a Quote is being used to amend or modify content, typically in [External Documents](#external-document), for example, "(b) Insert into Section 4 of the Act, '...'". #### `span (Span)` `span` is the [Span](#span) where a Quote occurs in the [Document](#document). ### Date A **Date** is a date within a [Document](#document) belonging to a [supported date type](#type-date-type). Dates not fitting into a supported date type will not result in a Date node. #### `value (string)` `value` is a string representing the date of a Date in ISO 8601 format (`YYYY-MM-DD`). It is possible for multiple Dates in a Document to have the same `value` if they are different types or are the same type but linked to different [Persons](#person). #### `type (Date Type)` `type` is a string representing the type of a Date, being one of the following: * `creation`: the date when a [Document](#document) was created or last updated. There may only be one `creation` Date per Document. * `signature`: a date when a Document was signed. * `effective`: a date when a Document or a part thereof comes into effect (eg, commencement or enactment dates). * `expiry`: a date when a Document or a part thereof is no longer in effect. * `delivery`: a date when goods or services are to be delivered under a Document. * `renewal`: a date when one or more of a Document's terms are to be renewed. * `payment`: a date when payment is to be made under a Document. * `birth`: the birth date of a natural person or establishment (eg, incorporation) date of a non-natural legal person identified in a Document. There can only be one `birth` Date linked to a single [Person](#person) and all `birth` Dates must be linked to a Person. A Person's `birth` Date will never be after their `death` Date. * `death`: the death date of a natural person or dissolution date of a non-natural legal person identified in a Document. There can only be one `death` Date linked to a single Person and all `death` Dates must be linked to a Person. A Person's `death` Date will never be before their `birth` Date. #### `person (ID | null)` `person` is the ID of the [Person](#person) linked to a Date or `null` if there is no known association between a Person and a Date. Dates with the `birth` or `death` [Type](#type-date-type) will always have a linked `person`. #### `mentions (array[Span])` `mentions` is an array of [Spans](#span) mentioning a Date. `mentions` will never be empty. No two Spans in any Date's `mentions` can overlap with each other. ## Citation If you've relied on the Isaacus Legal Graph Schema (ILGS) in your work, please consider citing it as follows: ```bibtex theme={null} @manual{butler_ilgs, title = {Isaacus Legal Graph Schema (ILGS)}, author = {Umar Butler and Abdur-Rahman Butler}, organization = {Isaacus}, publisher = {Isaacus}, edition = {1.0.0}, year = {2026}, url = {https://docs.isaacus.com/ilgs}, } ```