API Reference

This page catalogs the public API surface of the folio package: the FOLIO class, the OWLClass and OWLObjectProperty Pydantic models, FOLIOConfiguration, plus module constants and the FOLIOTypes enum. For tutorial-style usage, see the topical sub-pages linked at the bottom.

Module exports

The top-level folio package re-exports a small, stable surface from its submodules. These are the only names guaranteed by __all__.

The package also exposes standard dunder metadata:

Everything else (FOLIOConfiguration, DEFAULT_* constants, get_logger) lives in folio.config, folio.graph, and folio.logger, and must be imported from those submodules directly.

class FOLIO

The main entry point. from folio import FOLIO. Instantiating a FOLIO() loads the ontology (from cache if available, otherwise from GitHub), parses it into Pydantic models, and builds the in-memory indices used by every lookup, search, and traversal method.

Constructor

FOLIO(
    source_type: str = "github",
    http_url: Optional[str] = None,
    github_repo_owner: str = "alea-institute",
    github_repo_name: str = "FOLIO",
    github_repo_branch: str = "2.0.0",
    use_cache: bool = True,
    llm: Optional[BaseAIModel] = None,
    llm_kwargs: Optional[dict] = None,
    effort: Optional[str] = None,
    tier: Optional[str] = None,
) -> None

FOLIO(branch="main") raises TypeError. The parameter is github_repo_branch. The same full names apply to github_repo_owner and github_repo_name — there is no short form.

Public attributes

All attributes below are set up during __init__ and parse_owl. Everything prefixed with _ (e.g. _cached_triples, _label_trie, _prefix_cache) is internal and may change without notice.

There is no classes_by_iri attribute. To look up a class by IRI use f[iri] (recommended) or f.classes[f.iri_to_index[iri]]. To check membership, use iri in f (invokes __contains__).

Loading and lifecycle

These are mostly staticmethods you call on the class itself (FOLIO.load_owl(...)), plus refresh() and the parse helpers which operate on an instance.

Class access (dunder + helper)

IRI lookups accept any of the supported formats: short ID (R8BD30978Ccbc4C2f0f8459f), prefixed (folio:R8BD…), full URI (https://folio.openlegalstandard.org/R8BD…), or legacy soli: / http://lmss.sali.org/ forms. All are normalized via normalize_iri.

Search

Lexical and semantic search. All methods return OWLClass instances (or tuples of class + score). search_by_prefix is synchronous; search_by_llm and parallel_search_by_llm are async and must be awaited.

Structured queries

Composable text and structural filters. Both query and query_properties share a match_mode control that accepts "substring" (default), "exact", "regex", or "fuzzy" — the "fuzzy" mode requires the [search] extra and uses partial_ratio >= 70 as the cutoff.

f.query(
    label: Optional[str] = None,
    definition: Optional[str] = None,
    alt_label: Optional[str] = None,
    example: Optional[str] = None,
    any_text: Optional[str] = None,
    branch: Optional[str] = None,
    parent_iri: Optional[str] = None,
    has_children: Optional[bool] = None,
    deprecated: bool = False,
    country: Optional[str] = None,
    match_mode: str = "substring",
    limit: int = 20,
) -> List[OWLClass]

f.query_properties(
    label: Optional[str] = None,
    definition: Optional[str] = None,
    domain_iri: Optional[str] = None,
    range_iri: Optional[str] = None,
    has_inverse: Optional[bool] = None,
    match_mode: str = "substring",
    limit: int = 20,
) -> List[OWLObjectProperty]

domain_iri and range_iri are normalized via normalize_iri and matched against the property’s domain / range lists (set membership). has_inverse filters on the presence of inverse_of.

Taxonomy helpers

Twenty-four branch helpers, one per member of FOLIOTypes. Every helper shares the signature (max_depth: int = DEFAULT_MAX_DEPTH) -> List[OWLClass] (where DEFAULT_MAX_DEPTH = 16) and delegates to get_children(FOLIO_TYPE_IRIS[branch], max_depth=max_depth). The default-depth class counts are against the FOLIO 2.0.0 ontology on the 2.0.0 branch.

Plus the meta helper:

f.get_folio_branches(max_depth: int = DEFAULT_MAX_DEPTH) -> Dict[FOLIOTypes, List[OWLClass]]

get_folio_branches returns a dict keyed by FOLIOTypes with every branch expanded in parallel, not a flat list. The docstring on the method itself says “list” — the return type is actually Dict[FOLIOTypes, List[OWLClass]] with 24 keys.

Traversal

Three primitives for walking the class hierarchy by IRI. All three accept a max_depth second argument (default 16) and accept any IRI form (normalized internally).

Object properties

Methods for working with owl:ObjectProperty instances — the predicates that connect classes in the ontology graph.

Triples

The parsed triple store exposes the full RDF content of the ontology. The triples attribute holds all of them; the three get_triples_by_* methods filter by subject, predicate, or object.

There are 35 unique predicates in the 2.0.0 ontology — see the Properties sub-page for the full list.

Utilities

Mostly internal, but useful for advanced users building their own IRI handling or namespace logic.

class OWLClass

from folio import OWLClass. A Pydantic v2 BaseModel representing an OWL class with every field the FOLIO ontology populates. Each field maps one-to-one onto a specific OWL, RDFS, SKOS, Dublin Core, or MADS property.

Fields

parent_class_of is misnamed. Despite the sub_class_of echo in its docstring, it actually holds children IRIs — the classes for which this class is the parent. FOLIO populates it in the reverse-edge pass of parse_owl. sub_class_of is the direction that matches OWL semantics (your own parents); parent_class_of is the reverse adjacency (your own children).

Methods

There is no to_owl_ttl method. The available serializers are OWL/XML, JSON-LD (as a dict), Markdown, and Pydantic JSON. There is no Turtle, N-Triples, or N-Quads output. If you need Turtle, serialize via to_owl_xml() and convert with a library like rdflib.

class OWLObjectProperty

from folio import OWLObjectProperty. A Pydantic v2 BaseModel representing an owl:ObjectProperty — the predicates that connect FOLIO classes (e.g. folio:observed, folio:hasFigure).

Fields

Methods

Only two: is_valid() -> bool (true when label is set) and __str__() -> str. There are no to_owl_element, to_owl_xml, to_markdown, to_json, or to_jsonld methods on OWLObjectProperty — those exist on OWLClass only. To serialize an object property, call Pydantic’s prop.model_dump_json() or prop.model_dump() directly.

class FOLIOConfiguration

from folio.config import FOLIOConfiguration. A Pydantic v2 model for describing a FOLIO source in a JSON config file. Used by FOLIOConfiguration.load_config() to hydrate settings from ~/.folio/config.json.

Fields

FOLIOConfiguration() with no arguments raises pydantic.ValidationError because source is required. Only use_cache=True has a populated default. The DEFAULT_GITHUB_REPO_OWNER, DEFAULT_GITHUB_REPO_NAME, and DEFAULT_GITHUB_REPO_BRANCH values in folio.config are module-level constants, not field defaults — FOLIOConfiguration.load_config() pulls them in as fallbacks when reading ~/.folio/config.json, but the model itself has no such defaults.

The field name is source, not source_type. The FOLIO() constructor uses source_type as its parameter name for historical reasons. This asymmetry is real, and you’ll see it if you try to pass a hydrated FOLIOConfiguration straight into FOLIO() — you’ll need to rename fields.

Methods

There is no save_config, to_json, or from_json on FOLIOConfiguration. To write a config file, call config.model_dump_json(indent=2) yourself and write the result to disk — Pydantic gives you everything you need.

Constants

FOLIOTypes

from folio import FOLIOTypes. An enum.Enum with 24 members. Each member’s .value is the human-readable branch name exactly as it appears in rdfs:label on the branch root class.

FOLIO_TYPE_IRIS

from folio import FOLIO_TYPE_IRIS. A Dict[FOLIOTypes, str] mapping every branch to its short IRI (the trailing segment after https://folio.openlegalstandard.org/).

Values are short IDs. Prefix https://folio.openlegalstandard.org/ to get the full IRI — or just pass the short form directly to f[iri], which normalizes both forms.

NSMAP

from folio import NSMAP. The lxml namespace map used by to_owl_element, to_jsonld, and all of the get_ns_tag calls during parsing. Ten entries, including a None key for the default namespace.

NSMAP = {
    None:    "https://folio.openlegalstandard.org/",
    "dc":    "http://purl.org/dc/elements/1.1/",
    "v1":    "http://www.loc.gov/mads/rdf/v1#",
    "owl":   "http://www.w3.org/2002/07/owl#",
    "rdf":   "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
    "xsd":   "http://www.w3.org/2001/XMLSchema#",
    "folio": "https://folio.openlegalstandard.org/",
    "rdfs":  "http://www.w3.org/2000/01/rdf-schema#",
    "skos":  "http://www.w3.org/2004/02/skos/core#",
    "xml":   "http://www.w3.org/XML/1998/namespace",
}

The None key is the lxml convention for the default namespace in element construction. It also appears in OWLClass.to_jsonld() output’s @context — downstream JSON-LD consumers that can’t handle a null key must strip it before parsing.

Module-level constants

From folio.graph:

From folio.config:

These are plain module-level names, not FOLIOConfiguration field defaults. Import them directly: from folio.config import DEFAULT_GITHUB_REPO_BRANCH.

Logger

from folio.logger import get_logger. Returns a standard logging.Logger configured at WARNING level by default. The library uses it internally for load/parse timing messages, cache hits, and LLM failures. To surface those messages in your own app, attach a handler or set the level:

import logging
from folio.logger import get_logger

logger = get_logger("folio")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler())

Every submodule (folio.graph, folio.config, folio.models) calls get_logger(__name__), so setting the level on the parent "folio" logger will cascade to all of them.

See also

Every section above has a narrative sub-page with worked examples. Start with Getting Started to install and load the ontology, then follow Searching and Querying for lookup patterns, Taxonomy for branch helpers and traversal, Properties & Relationships for object properties and the triples API, Serialization for to_* output formats, and LLM Integration for search_by_llm and parallel_search_by_llm.