FOLIO Python Library

The FOLIO Python Library provides a simple and efficient way to interact with the Federated Open Legal Information Ontology (FOLIO).

This powerful library enables developers, researchers, and legal professionals to seamlessly integrate FOLIO into their Python projects, facilitating access to multiple comprehensive legal information standards through a unified interface.

By leveraging the FOLIO Python Library, organizations can accelerate their adoption of multiple interoperable legal standards, streamline data science projects in the legal domain, and enhance interoperability across various legal information systems. The library implements FOLIO’s modular and federated design principles, allowing developers to work with different legal standards while maintaining compatibility and cross-standard functionality.

Overview

The FOLIO Python Library offers the following key features:

• Load the FOLIO ontology from GitHub or a custom HTTP URL
• Conveniently access class information, including RDF(S), SKOS, and OWL properties
• Search for classes by label or definition
• Traverse taxonomy relationships like parent/ancestor and child/descendant classes
• Convert classes to JSON, JSON-LD, OWL XML, or Markdown format

Installation

You can install the FOLIO Python library using pip:

pip install folio-python

For the latest development version, you can install directly from GitHub:

pip install --upgrade https://github.com/alea-institute/folio-python/archive/refs/heads/main.zip

Quick Start

Here’s a simple example to get you started with the FOLIO Python library:

# Install: pip install folio-python
from folio import FOLIO

# Initialize the FOLIO client
folio = FOLIO()

# Search for a class by label
result, score = folio.search_by_label("southern district new york")[0]
print(f"{result.iri} (Score: {score})")
print(f"Preferred Label: {result.preferred_label}")
print(f"Synonyms: {result.alternative_labels}")
print(f"Parents: {[folio[c].label for c in result.sub_class_of]}")

# Output: 
# https://folio.openlegalstandard.org/RB8D8b89B9b18DB928b27dfe (Score: 100.0)
# Preferred Label: District Court, S.D. New York
# Synonyms: ['S.D. N.Y.', 'S.D.N.Y.', 'SDNY', 'Southern District of New York', 'NYSD']
# Parents: ['U.S. District Courts']

Key Features

Loading the Ontology

If you want to load a specific version of the ontology, or if you want to load your own modified version, you can still use the FOLIO Python library:

# Load from default GitHub repository and branch (1.0.0)
folio = FOLIO()

# Load from a custom HTTP(S) URL
folio = FOLIO(source_type="http", http_url="https://example.com/my-folio-fork/folio.owl")

# Load from acme/our-folio repository, branch 1.2.3
folio = FOLIO(github_repo_owner="acme", github_repo_name="our-folio", github_repo_branch="1.2.3")

Loading Class Information

If you know the IRI of a class, you can access its information directly:

# Get a class by IRI
folio = FOLIO()

# Access class information by IRI ID
print(folio["R1ABd0796Ff01FF7573A211f"])

# Access by shorthand namespace
print(folio["folio:R1ABd0796Ff01FF7573A211f"])

# Access by full URI
print(folio["https://folio.openlegalstandard.org/R1ABd0796Ff01FF7573A211f"])

# Output:
# OWLClass(label=Denmark, iri=https://folio.openlegalstandard.org/R1ABd0796Ff01FF7573A211f)

Legacy identifiers from lmss.sali.org are also supported transparently for backward compatibility.

Searching for Classes

You can search for classes by label or definition:

# Search by label
results = folio.search_by_label("SDNY")

# Search by definition
results = folio.search_by_definition("legal agreement")

Basic search functionality is provided using both string and token similarity measures.

More details are available in the documentation:

• search_by_label
• search_by_definition

Converting Classes

The FOLIO Python library uses Pydantic models to convert classes to and from different formats.

# Convert to JSON (wrapper around .model_dump_json()) 
json_data = contract_class.to_json()

# Convert to JSON-LD
jsonld_data = contract_class.to_jsonld()

# Convert to OWL XML
owl_xml = contract_class.to_owl_xml()

# Convert to Markdown
markdown = contract_class.to_markdown()

For example:

>>> print(folio["https://folio.openlegalstandard.org/R1ABd0796Ff01FF7573A211f"].to_jsonld())

{
  "@context": {
    ...
  },
  "@id": "https://folio.openlegalstandard.org/R1ABd0796Ff01FF7573A211f",
  "@type": "owl:Class",
  "rdfs:label": "Denmark",
  "skos:prefLabel": "Denmark",
  "skos:altLabel": [
    "DK"
  ],
  "rdfs:subClassOf": [
    {
      "@id": "https://folio.openlegalstandard.org/R5E0c679BE29e3F86383A5bc"
    }
  ],
  "skos:hiddenLabel": "DK",
  "dc:identifier": "EUR-DK"
}

Documentation

For more detailed information about using the FOLIO Python library, please refer to the full documentation on Read the Docs or source code on GitHub.

Contributing

Contributions to the FOLIO Python library are welcome! If you’d like to contribute, please follow these steps:

1. Fork the repository
2. Create a new branch for your feature or bug fix
3. Make your changes and write tests if applicable
4. Run the test suite to ensure everything is working
5. Submit a pull request with a clear description of your changes

For more information, see the contribution guidelines.

License

The FOLIO Python library is released under the MIT License. See the LICENSE file for details.

Support

If you encounter any issues or have questions about using the FOLIO Python library, please open an issue on GitHub or open a discussion topic on the FOLIO community forum.