Data Models

The YouVersion Bible Client uses Pydantic models for type-safe data handling and validation.

Core Models

Votd

Verse of the day model.

class Votd

day: int: Day number (1-365)

usfm: List[str]: USFM references for the verse

image_id: Optional[str]: Associated image ID

from youversion import Votd

votd = Votd(day=1, usfm=["JHN.3.16"], image_id="img123")
print(f"Day {votd.day}: {votd.usfm}")

Moment

Base model for all YouVersion moment objects.

class Moment

id: str: Unique moment identifier

kind: str: Type of moment (e.g., “highlight”, “note”, “image”)

moment_title: str: Title of the moment

time_ago: str: Human-readable time since creation

owned_by_me: bool: Whether the moment is owned by the current user

created_dt: Optional[datetime]: Creation datetime

updated_dt: Optional[datetime]: Last update datetime

user: User: User who created the moment

actions: Action: Available actions for the moment

comments: Comment: Comment information

likes: Like: Like information

avatar: str: Avatar URL

path: str: Full URL path to the moment

Highlight

Model for Bible verse highlights.

class Highlight(Moment)

references: List[Reference]: Bible verse references

text: Optional[str]: Highlighted text content

from youversion import Highlight

highlight = Highlight(
    id="123",
    kind="highlight",
    moment_title="John 3:16",
    references=[Reference(version_id=1, human="John 3:16", usfm="JHN.3.16")],
    text="For God so loved the world..."
)

Note

Model for Bible study notes.

class Note(Moment)

content: str: Note content

references: List[Reference]: Related Bible verse references

status: StatusEnum: Note status (PRIVATE, PUBLIC, etc.)

from youversion import Note, StatusEnum

note = Note(
    id="456",
    kind="note",
    moment_title="Study Notes",
    content="This verse teaches us about God's love",
    references=[Reference(version_id=1, human="John 3:16", usfm="JHN.3.16")],
    status=StatusEnum.PRIVATE
)

Image

Model for shared Bible images.

class Image(Moment)

references: List[Reference]: Related Bible verse references

body_image: str: Image URL

action_url: Optional[str]: Action URL for the image

Friendship

Model for friendship moments.

class Friendship(Moment)

friend_name: str: Friend’s name

friend_path: str: Friend’s profile path

friend_avatar: str: Friend’s avatar URL

Plan Models

PlanSegmentCompletion

Model for reading plan segment completions.

class PlanSegmentCompletion(PlanModel)

percent_complete: float: Completion percentage (0.0-1.0)

segment: int: Segment number

total_segments: int: Total segments in the plan

plan_id: int: Plan identifier

subscribed: bool: Whether the user is subscribed to the plan

PlanSubscription

Model for reading plan subscriptions.

class PlanSubscription(PlanModel)

plan_title: str: Title of the subscribed plan

plan_id: int: Plan identifier

subscribed: bool: Whether the user is subscribed to the plan

PlanCompletion

Model for completed reading plans.

class PlanCompletion(PlanModel)

plan_title: str: Title of the completed plan

plan_id: int: Plan identifier

subscribed: bool: Whether the user is subscribed to the plan

Supporting Models

Reference

Model for Bible verse references.

class Reference

version_id: Union[str, int]: Bible version identifier

human: str: Human-readable reference (e.g., “John 3:16”)

usfm: Union[str, List[str]]: USFM reference format

User

Model for YouVersion users.

class User

id: Optional[Union[str, int]]: User identifier

path: str: User profile path

user_name: Optional[str]: Username

Action

Model for moment actions.

class Action

deletable: bool: Whether the moment can be deleted

editable: bool: Whether the moment can be edited

read: bool: Whether the moment can be read

show: bool: Whether the moment should be shown

Comment

Model for comment information.

class Comment(ReactionModel)

enabled: bool: Whether comments are enabled

count: int: Number of comments

strings: Dict[str, Any]: Comment-related strings

all: List[Any]: All comment data

Like ~~~

Model for like information.

class Like(ReactionModel)

enabled: bool: Whether likes are enabled

count: int: Number of likes

strings: Dict[str, Any]: Like-related strings

all: List[Any]: All like data

is_liked: bool: Whether the current user has liked the moment

user_ids: Optional[List[int]]: List of user IDs who liked the moment

Enums

StatusEnum

Enumeration for note status values.

class StatusEnum

PRIVATE: Private note

PUBLIC: Public note

MomentKinds

Enumeration for moment types.

class MomentKinds

HIGHLIGHT: Highlight moment

NOTE: Note moment

IMAGE: Image moment

FRIENDSHIP: Friendship moment

PLAN_SEGMENT_COMPLETION: Plan segment completion

PLAN_COMPLETION: Plan completion

PLAN_SUBSCRIPTION: Plan subscription

Model Validation

All models use Pydantic for automatic validation and serialization:

from youversion import Highlight
from pydantic import ValidationError

try:
    highlight = Highlight(
        id="123",
        kind="highlight",
        moment_title="Test",
        # Missing required fields will raise ValidationError
    )
except ValidationError as e:
    print(f"Validation error: {e}")

Model Serialization

Models can be serialized to dictionaries and JSON:

from youversion import Votd

votd = Votd(day=1, usfm=["JHN.3.16"], image_id="img123")

# Convert to dictionary
data = votd.model_dump()
print(data)

# Convert to JSON
json_data = votd.model_dump_json()
print(json_data)

# Convert with exclusions
minimal_data = votd.model_dump(exclude={'image_id'})
print(minimal_data)