Base Models

API reference for the base model classes. Case-specific models (like EU Models) inherit from these and add domain fields. For a conceptual overview, see the Model Guide.

Entity

The abstract base class all models inherit from. Provides multi-scheme identifiers, source metadata storage (_raw), and extra="allow" for domain-specific attributes.

Overview

Bases: BaseModel

Base class for all entities.

Provides multi-scheme identifiers and extra="allow" for domain-specific attributes. Core fields are declared on subclasses. Domain-specific fields are passed as extra kwargs and accessible directly on the instance.

Source metadata is stored in _raw (PrivateAttr, excluded from serialization).

Configuration:

  • extra="allow": accepts fields beyond those declared on the model. Case-specific and adapter-provided attributes are stored as extra fields and accessible directly on the instance (e.g., proc.procedure_type).
  • validate_assignment=True: field values are validated when set after construction, not just during __init__.
  • arbitrary_types_allowed=True: permits non-standard types like MultiLangText and Identifiers as field types.

Access patterns:

entity.title                # core field (declared)
entity.procedure_type       # domain-specific (extra)
entity.model_fields         # Pydantic: declared fields
entity.model_extra          # Pydantic: extra fields as dict
entity._raw                 # source metadata (excluded from serialization)

Config:

  • arbitrary_types_allowed: True
  • validate_assignment: True
  • extra: allow

Fields:

Fields

entity.title                # core field (declared)
entity.procedure_type       # domain-specific (extra)
entity.model_fields         # Pydantic: declared fields
entity.model_extra          # Pydantic: extra fields as dict
entity._raw                 # source metadata (excluded from serialization)

identifiers pydantic-field

Multi-scheme identifiers for this entity (e.g., CELEX, ELI, Cellar, etc. in the EU case).

Legislative models

The three substantive model classes representing a legislative process.

Procedure

Overview

Bases: Entity

A legislative procedure.

Top-level container holding events and metadata about a legislative process. Documents live under events, reflecting their role in specific stages of the procedure.

Core fields are system-agnostic. Domain-specific attributes are accessible directly as extra fields.

Subclasses for specific legislative systems (EU, US, etc.) should override the following properties with domain-specific logic:

  • start_event -- the event that initiated the procedure
  • adoption_event -- the event where the text was formally adopted
  • end_event -- the terminal event (adoption, withdrawal, etc.)
  • status -- procedure status (ongoing, adopted, withdrawn, etc.)

Base defaults use chronological heuristics where possible and return None where domain knowledge is required.

Fields:

Fields and properties

title = None pydantic-field

Procedure title, potentially in multiple languages.

events pydantic-field

Events in this legislative procedure.

start_event property

Event that initiated this procedure.

Base default: earliest event by date. Subclasses should override to identify the domain-specific start event (e.g. proposal event).

start_date property

Date when this procedure started.

adoption_event property

Event where the legislative text was formally adopted.

Returns None on the base model. Subclasses should override to identify the domain-specific adoption event (e.g. formal Council adoption in the EU, presidential signature in the US).

adoption_date property

Date when the legislative text was adopted, or None.

end_event property

Terminal event that concluded this procedure.

Base default: the adoption event. Subclasses should override to include other terminal events (e.g. withdrawal).

end_date property

Date when this procedure concluded, or None if still ongoing.

status property

Procedure status.

Base default: "adopted" if an adoption event exists, "ongoing" otherwise. Subclasses should override with domain-specific logic (e.g. distinguishing withdrawn, rejected, lapsed procedures).

duration(reference_date=None)

Number of days between start and end of this procedure.

For concluded procedures, returns days between start_date and end_date. For ongoing procedures, uses reference_date as the end point. If reference_date is None, defaults to today.

Returns None if start_date is missing.

Note: in the future, reference_date could default to a collection/download date once that field is implemented.

get_all_documents()

Collect all documents from all events in this procedure.

Event

Overview

Bases: Entity

An event within a legislative process.

Core fields are system-agnostic (date, title, type, documents). Domain-specific attributes are accessible directly as extra fields.

Fields:

Fields

date = None pydantic-field

Date when this event occurred (ISO 8601).

title = None pydantic-field

Event title, potentially in multiple languages.

type = None pydantic-field

Event type code.

documents pydantic-field

Documents associated with this event.

Document

Overview

Bases: Entity

A document within a legislative process.

Core fields are system-agnostic (title, date). Domain-specific attributes are accessible directly as extra fields.

Fields:

Fields

title = None pydantic-field

Document title, potentially in multiple languages.

date = None pydantic-field

Date associated with this document (ISO 8601).

Data types

Types used as fields throughout the legislative models.

MultiLangText

Dict-like container mapping language codes to text strings.

Stores multilingual text as {lang_code: text}. A plain string without language information is stored under the key "_".

from_value(value, default_lang='_') classmethod

Build from a dict[str, str], a plain str, or None.

  • dict[str, str] -> stored directly
  • str -> stored under key default_lang (default "_")
  • None -> returns None

Identifiers

Collection of identifiers for an entity, with lookup by scheme.

Identifier

Bases: BaseModel

A single identifier in a named scheme.

Config:

  • frozen: True

Fields:

  • scheme (str)
  • value (str)

Raw metadata (_raw)

The _raw private attribute on every entity stores source metadata that does not belong in the typed model. It is excluded from model_dump() and serialization.

proc._raw["_rdf_types"]     # Original RDF type URIs
proc._raw["_same_as"]       # owl:sameAs alias URIs
proc._raw["_raw_triples"]   # Unconsumed RDF triples

Field metadata and codebooks

Case models use field metadata annotations and codebook extraction to document their domain-specific properties. See Fields and Codebooks.