vcon package

Module contents

The package root re-exports the classes and functions most code needs.

exception vcon.AlgorithmNotPermittedError[source]

Bases: ValueError

A JWS used alg “none” (forbidden by core-05) or an unsupported algorithm.

class vcon.Dialog(type: str, start: datetime | str, parties: List[int], mediatype: str | None = None, filename: str | None = None, body: str | None = None, encoding: str | None = None, url: str | None = None, disposition: str | None = None, campaign: str | None = None, interaction: str | None = None, skill: str | None = None, duration: float | None = None, meta: dict | None = None, metadata: Dict[str, Any] | None = None, signaling: Dict[str, Any] | None = None, resolution: str | None = None, frame_rate: float | None = None, codec: str | None = None, bitrate: int | None = None, thumbnail: str | None = None, session_id: Dict[str, str] | List[Dict[str, str]] | None = None, content_hash: str | None = None, application: str | None = None, message_id: str | None = None, redacted_segments: List[Dict[str, Any]] | None = None, **kwargs)[source]

Bases: object

A class representing a dialog segment in a vCon conversation.

A dialog represents a piece of conversation content, which can be: - text: Text-based communication (email, chat, SMS) - recording: Audio/video recording of the conversation - incomplete: Failed or incomplete conversation setup

"audio" and "video" are accepted as deprecated aliases for recording.

Dialog content can be stored inline or referenced externally: - Inline: Content stored directly in the body field - External: Content referenced via URL with content_hash for integrity

Media support: - Audio formats: WAV, MP3, MP4, OGG, WebM, AAC - Video formats: MP4, WebM, AVI, MKV, MOV, FLV, 3GP - Text formats: Plain text, multipart messages - Images: JPEG, TIFF, PDF

Changes in vCon 0.5.0 (draft-ietf-vcon-vcon-core-05):

  • parties lists the contributors only. The receivers are in the parties of the Session Object that references the dialog.

  • originator moved to the Session Object.

  • party_history was replaced by Event Objects (vcon.event.Event).

  • The transfer and recording-set dialog types were removed. Transfers are Events; a recording set is a Session.

  • An empty Dialog Object (Dialog.placeholder(), serialized as {}) holds a position in the dialog array so that indices do not change.

  • redacted_segments was added.

MIME_TYPES = ['text/plain', 'audio/x-wav', 'audio/wav', 'audio/wave', 'audio/mpeg', 'audio/mp3', 'audio/x-mp3', 'audio/x-mp4', 'audio/ogg', 'audio/webm', 'audio/x-m4a', 'audio/aac', 'video/x-mp4', 'video/ogg', 'video/mp4', 'video/quicktime', 'video/webm', 'video/x-msvideo', 'video/x-matroska', 'video/mpeg', 'video/x-flv', 'video/3gpp', 'video/x-m4v', 'multipart/mixed', 'message/rfc822', 'image/jpeg', 'image/tiff', 'application/pdf', 'application/json']
VALID_DISPOSITIONS = ['no-answer', 'congestion', 'failed', 'busy', 'hung-up', 'voicemail-no-message']
VALID_TYPES = ['recording', 'text', 'incomplete', 'audio', 'video']
__init__(type: str, start: datetime | str, parties: List[int], mediatype: str | None = None, filename: str | None = None, body: str | None = None, encoding: str | None = None, url: str | None = None, disposition: str | None = None, campaign: str | None = None, interaction: str | None = None, skill: str | None = None, duration: float | None = None, meta: dict | None = None, metadata: Dict[str, Any] | None = None, signaling: Dict[str, Any] | None = None, resolution: str | None = None, frame_rate: float | None = None, codec: str | None = None, bitrate: int | None = None, thumbnail: str | None = None, session_id: Dict[str, str] | List[Dict[str, str]] | None = None, content_hash: str | None = None, application: str | None = None, message_id: str | None = None, redacted_segments: List[Dict[str, Any]] | None = None, **kwargs) → None[source]

Initialize a Dialog object. :param type: the type of the dialog (e.g. “text”, “recording”, “incomplete”, “video”) :type type: str :param start: the start time of the dialog :type start: datetime :param parties: the parties that contributed to the dialog (the receivers are in the Session Object) :type parties: List[int] :param mediatype: the MIME type of the dialog body :type mediatype: str or None :param filename: the filename of the dialog body :type filename: str or None :param body: the body of the dialog :type body: str or None :param encoding: the encoding of the dialog body :type encoding: str or None :param url: the URL of the dialog :type url: str or None :param disposition: the disposition of the dialog :type disposition: str or None :param campaign: the campaign that the dialog is associated with :type campaign: str or None :param interaction: the interaction that the dialog is associated with :type interaction: str or None :param skill: the skill that the dialog is associated with :type skill: str or None :param duration: the duration of the dialog :type duration: float or None :param meta: additional metadata for the dialog :type meta: dict or None :param metadata: structured metadata for the dialog (newer format) :type metadata: dict or None :param signaling: signaling-specific information :type signaling: dict or None :param resolution: video resolution (e.g., “1920x1080”) :type resolution: str or None :param frame_rate: video frame rate in fps :type frame_rate: float or None :param codec: video codec (e.g., “H.264”, “H.265”) :type codec: str or None :param bitrate: video bitrate in kbps :type bitrate: int or None :param thumbnail: base64-encoded thumbnail image :type thumbnail: str or None :param session_id: Session identifier :type session_id: str or None :param content_hash: Hash for externally referenced files (replaces alg and signature) :type content_hash: str or None :param application: Application identifier for the dialog :type application: str or None :param message_id: Message identifier for email/text dialogs :type message_id: str or None :param redacted_segments: Redacted_segments Objects (start, end, optional parties) :type redacted_segments: list or None :param kwargs: Additional attributes to be set on the dialog

add_external_data(url: str, filename: str, mediatype: str) → None[source]

Add external data to the dialog.

Parameters:

url (str) – the URL of the external data

Returns:

None

Return type:

None

add_image_data(image_path: str, mediatype: str | None = None) → None[source]

Add image data to the dialog from a local file.

Parameters:
  • image_path (str) – Path to the image file

  • mediatype (str or None) – MIME type of the image (optional, auto-detected if not provided)

Returns:

None

Return type:

None

add_inline_data(body: str | bytes, filename: str, mediatype: str) → None[source]

Add inline data to the dialog.

The Dialog is written with encoding: "base64url". Pass raw bytes and they are encoded; a str is taken to be base64url already. The content_hash is over the decoded content.

Parameters:
  • body (bytes or str) – the content as bytes, or as a base64url string

  • filename (str) – the filename of the inline data

  • mediatype (str) – the mediatype of the inline data

Returns:

None

Return type:

None

add_streaming_video_reference(reference_id, mediatype, metadata=None) → None[source]

Add a reference to a streamable video.

Parameters:
  • reference_id – Unique identifier for the streamable video

  • mediatype – MIME type of the video

  • metadata – Optional video metadata

Returns:

None

add_video_data(video_data, filename=None, mediatype=None, inline=True, metadata=None) → None[source]

Add video data to the dialog.

Parameters:
  • video_data – Binary video data or URL to video

  • filename – Name of the video file

  • mediatype – MIME type of the video, or auto-detected from filename if None

  • inline – Whether to include the video as inline content (True) or external reference (False)

  • metadata – Optional video metadata to include

Returns:

None

add_video_with_optimal_storage(video_data, filename, mediatype=None, size_threshold_mb=10) → None[source]

Add video with the optimal storage method based on size.

Parameters:
  • video_data – Binary video data or URL

  • filename – Name of the video file

  • mediatype – MIME type of the video (optional)

  • size_threshold_mb – Size threshold in MB for inline vs external storage

Returns:

None

calculate_content_hash(algorithm: str = 'sha512') → str[source]

Calculate the content hash for the dialog body.

The hash covers the content itself: for a base64url body that is the decoded bytes, so the value matches a hash of the original file (what add_image_data() stores). Other bodies are hashed as UTF-8.

The returned value is spec-formatted as "<algorithm>-<base64url>" with no base64 padding (draft-ietf-vcon-vcon-core-02), e.g. "sha512-GLy6IPa...".

Parameters:

algorithm (str) – The hash algorithm to use (default: "sha512"). "sha256" is also supported for backwards compatibility.

Returns:

The calculated hash value, prefixed with the algorithm name

Return type:

str

Raises:

ValueError – if there is no body to hash, or algorithm is not a supported algorithm

extract_image_metadata(image_data: bytes, mediatype: str) → None[source]

Extract metadata from image data and add it to the dialog metadata.

Parameters:
  • image_data (bytes) – Raw image data

  • mediatype (str) – MIME type of the image

Returns:

None

Return type:

None

extract_video_metadata(video_path=None) → dict[source]

Extract comprehensive metadata from video content using FFmpeg.

Parameters:

video_path – Optional path to video file. If None, uses the dialog’s content.

Returns:

Dictionary containing detailed video metadata

generate_image_thumbnail(max_size: Tuple[int, int] = (200, 200)) → str | None[source]

Generate a thumbnail for the image and return it as a base64-encoded string.

Parameters:

max_size (Tuple[int, int]) – Maximum thumbnail dimensions (width, height)

Returns:

Base64-encoded thumbnail or None if generation fails

Return type:

str or None

generate_thumbnail(*args, **kwargs)[source]

Generate a thumbnail for an image or a video Dialog.

For an image this calls generate_image_thumbnail() (max_size, returns a base64url string or None). For a video it calls generate_video_thumbnail() (timestamp, width, height, quality; returns JPEG bytes).

generate_video_thumbnail(timestamp=0.0, width=320, height=240, quality=90) → bytes[source]

Generate a high-quality thumbnail from the video at the specified timestamp.

Parameters:
  • timestamp – Time in seconds at which to extract the thumbnail frame

  • width – Desired width of the thumbnail in pixels

  • height – Desired height of the thumbnail in pixels

  • quality – JPEG quality (1-100)

Returns:

Binary thumbnail data in JPEG format

get_content_hash() → str | None[source]

Get the content hash for externally referenced files.

Returns:

The content hash if set, None otherwise

Return type:

str or None

get_session_id() → Dict[str, str] | List[Dict[str, str]] | None[source]

Get the session identifier for this dialog.

Returns:

The session identifier if set, None otherwise

Return type:

str or None

get_video_format_from_mediatype(mediatype: str | None = None) → str[source]

Get the video format name from a MIME type.

Parameters:

mediatype – MIME type of the video (default: this Dialog’s mediatype)

Returns:

Format name (mp4, mov, etc.)

has_thumbnail() → bool[source]

Check if the video has a thumbnail.

Returns:

True if the video has a thumbnail, False otherwise

is_audio() → bool[source]

Check if the dialog has audio content. :return: True if the dialog has audio content, False otherwise :rtype: bool

is_email() → bool[source]

Check if the dialog is an email dialog. :return: True if the dialog is an email dialog, False otherwise :rtype: bool

is_external_data() → bool[source]

Check if the dialog is an external data dialog.

Returns:

True if the dialog is an external data dialog, False otherwise

Return type:

bool

is_external_data_changed() → bool[source]

Check to see if it’s an external data dialog and verify the content hash.

Returns:

True if the dialog is an external data dialog and the contents are valid, False otherwise

Return type:

bool

is_image() → bool[source]

Check if the dialog has image content.

Returns:

True if the dialog has image content, False otherwise

Return type:

bool

is_incomplete() → bool[source]

Check if the dialog is an incomplete dialog. :return: True if the dialog is an incomplete dialog, False otherwise :rtype: bool

is_inline_data() → bool[source]

Check if the dialog is an inline data dialog.

Returns:

True if the dialog is an inline data dialog, False otherwise

Return type:

bool

is_pdf() → bool[source]

Check if the dialog has PDF content.

Returns:

True if the dialog has PDF content, False otherwise

Return type:

bool

is_placeholder() → bool[source]

Check if the dialog is an empty placeholder Dialog Object ({}).

is_recording() → bool[source]

Check if the dialog is a recording dialog. :return: True if the dialog is a recording dialog, False otherwise :rtype: bool

is_text() → bool[source]

Check if the dialog is a text dialog. :return: True if the dialog is a text dialog, False otherwise :rtype: bool

is_transfer() → bool[source]

Deprecated: core-05 has no transfer Dialog type, so this is always False.

is_video(content_type=None) → bool[source]

Check if the dialog has video content.

Parameters:

content_type – Optional content type to check. If None, use the dialog’s mediatype.

Returns:

True if the content is a video format, False otherwise

classmethod placeholder() → Dialog[source]

Create an empty Dialog Object (core-05 section 4.5.1).

It has no parameters and no meaning; it holds a position in the dialog array so that the indices of the other Dialog Objects, and the references to them, do not change. It serializes as {}.

set_content_hash(content_hash: str) → None[source]

Set the content hash for externally referenced files.

Parameters:

content_hash (str) – The content hash value

Returns:

None

Return type:

None

set_session_id(session_id: Dict[str, str] | List[Dict[str, str]]) → None[source]

Set the session identifier for this dialog.

Parameters:

session_id (dict or list) – The session identifier (SessionId or list of SessionId)

Returns:

None

Return type:

None

to_dict()[source]

Returns a dictionary representation of the Dialog object.

Returns:

a dictionary containing all non-None Dialog object attributes

Return type:

dict

to_inline_data() → None[source]

Convert the dialog from an external data dialog to an inline data dialog by reading the contents from the URL then adding the contents to the body.

Returns:

None

Return type:

None

transcode_video(target_format, codec=None, bit_rate=None, width=None, height=None) → None[source]

Transcode the video to a different format or with different encoding parameters.

Parameters:
  • target_format – Target video format (mp4, webm, etc.)

  • codec – Video codec to use (h264, vp9, etc.)

  • bit_rate – Target bitrate in bits per second

  • width – Target width (if resizing)

  • height – Target height (if resizing)

Returns:

None - updates the dialog’s content in place

verify_content_hash(expected_hash: str, algorithm: str | None = None) → bool[source]

Verify the content hash against the expected value.

The algorithm is inferred from the expected_hash prefix ("sha512-" or "sha256-") so values produced by either this or older releases of the library verify correctly. A legacy unprefixed hash is treated as the padded base64url SHA-256 that vcon-lib emitted prior to the algorithm-prefixed format.

Parameters:
  • expected_hash (str) – The expected hash value

  • algorithm (str or None) – Optional explicit algorithm override; when omitted the algorithm is taken from the expected_hash prefix

Returns:

True if the hash matches, False otherwise

Return type:

bool

class vcon.Event(type: str, time: datetime | str, sessions: int | List[int] | None = None, party: int | None = None, dialog: int | List[int] | None = None, channel: int | None = None, contributors: int | List[int] | None = None, button: str | None = None, transferee: int | None = None, transfer_target: int | None = None, consultation: int | None = None, target_session: int | None = None, validate: bool = True, **extra: Any)[source]

Bases: object

An Event Object (core-05 section 4.3).

Parameters:
  • type – Event type token, for example "join" or "blind-transfer".

  • time – When the event occurred (datetime or ISO 8601 string).

  • sessions – Session index or list of indices (not for channel-contributors).

  • party – Party index (not for channel-contributors).

  • dialog – Dialog index (channel-contributors; SHOULD NOT be used otherwise).

  • channel – Channel index (channel-contributors only).

  • contributors – Party index, list of indices, or None (channel-contributors only).

  • button – DTMF digit or key label (keydown and keyup only).

  • transferee – Party indices (transfer types).

  • transfer_target – Party indices (transfer types).

  • consultation – Session indices (transfer types).

  • target_session – Session indices (transfer types).

  • validate – Apply the parameter applicability table and raise ValueError on an M/X violation (default True).

  • **extra – Parameters defined by a vCon extension.

classmethod from_dict(data: Dict[str, Any], validate: bool = False) → Event[source]
to_dict() → Dict[str, Any][source]

Serialize, omitting parameters that are None.

exception vcon.MigrationError[source]

Bases: ValueError

The vCon cannot be migrated (or, in strict mode, a MUST field has no source).

class vcon.MigrationReport(source_version: str | None = None, target_version: str = '0.5.0', strict: bool = False, resign_required: bool = False, entries: ~typing.List[~vcon.migration.ReportEntry] = <factory>, removed_dialogs: ~typing.Dict[int, ~typing.Dict[str, ~typing.Any]] = <factory>, steps_run: ~typing.List[str] = <factory>)[source]

Bases: object

What a migration did that the draft did not dictate.

add(step: str, kind: str, message: str, code: str | None = None, **details: Any) → None[source]
entries: List[ReportEntry]
property fallbacks: List[ReportEntry]
property inferred: List[ReportEntry]
property notes: List[ReportEntry]
removed_dialogs: Dict[int, Dict[str, Any]]

Original content of every Dialog replaced by {}, keyed by its (unchanged) index.

resign_required: bool = False

the signature is dropped and the result is unsigned.

Type:

True when the input was signed

source_version: str | None = None
steps_run: List[str]

Steps that ran, in order.

strict: bool = False
summary() → str[source]
target_version: str = '0.5.0'
to_dict() → Dict[str, Any][source]
property unresolved: List[ReportEntry]
class vcon.MigrationResult(vcon: Dict[str, Any], report: MigrationReport)[source]

Bases: NamedTuple

Result of a migration. Unpacks as (vcon, report).

report: MigrationReport

Alias for field number 1

vcon: Dict[str, Any]

Alias for field number 0

class vcon.Session(start: str | datetime | None = None, duration: int | float | None = None, parties: List[int] | None = None, originator: int | None = None, session_id: Dict[str, str] | None = None, sessions: List[SessionReference | Dict[str, Any]] | None = None, dialog: List[int] | None = None)[source]

Bases: object

A Session Object.

Parameters:
  • start – Session start (datetime or ISO 8601 string). SHOULD be present.

  • duration – Session duration in seconds. Absent means the session has no end.

  • parties – Indices of the receivers. The first one is the implied originator.

  • originator – Index of the originator, only when it is not the first party.

  • session_id – A SessionId Object ({"local": ..., "remote": ...}).

  • sessions – Relationships to other Sessions (SessionReference or dicts).

  • dialog – Indices of the Dialog Objects that are part of the session.

to_dict() → Dict[str, Any][source]

Serialize, omitting parameters that are None. An empty Session is {}.

class vcon.SessionReference(session: int, type: str, description: str | None = None)[source]

Bases: object

Session_Reference Object: how another Session relates to this one.

to_dict() → Dict[str, Any][source]
class vcon.Vcon(vcon_dict: Dict[str, Any] = None, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False)[source]

Bases: object

A class representing a vCon (Virtual Conversation) object according to the vCon specification.

A vCon is a standardized format for representing conversations and related metadata. It includes information about participants (parties), dialog content, attachments, and analysis data.

The vCon format supports features such as:

  • Unique identification via UUID

  • The vcon syntax version (written as "0.5.0")

  • Timestamps for creation and updates

  • Party information with contact details (tel, name, sip, did, jCard, timezone)

  • Dialog content with media types and session information

  • Attachments for ancillary documents

  • Analysis data for conversation insights

  • Digital signatures and encryption

  • Extensions and critical for extensibility

  • Civic address information for location data

  • Sessions (sessions) grouping dialog and events, and Events (events) for joins, drops, holds, key presses and transfers

New in vCon 0.5.0 (draft-ietf-vcon-vcon-core-05):

  • sessions and events arrays; Session and Event classes

  • redacted_from and amended_from replace redacted and amended

  • Attachments need party and dialog or session

  • extensions MUST list every extension in use; alg: "none" is rejected

  • Dialog parties are contributors only; empty {} Dialog placeholders

  • 0.4.0 input is migrated on load (see migrate_0_4_0_to_0_5_0)

vcon_dict

The underlying dictionary containing all vCon data

Type:

Dict

property_handling

How non-standard properties are handled

Type:

str

WTF_SCHEMA_URL = 'https://datatracker.ietf.org/doc/html/draft-howe-vcon-wtf-extension'
__init__(vcon_dict: Dict[str, Any] = None, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) → None[source]

Initialize a Vcon object from a dictionary.

A dict that declares "vcon": "0.4.0" is migrated to 0.5.0 here, using migrate_0_4_0_to_0_5_0. The report is kept in self.migration_report. A signed vCon whose payload is 0.4.0 is NOT migrated on load, because migrating drops the signature: verify it, then call Vcon.migrate_0_4_0_to_0_5_0(). An unmigrated 0.4.0 dict (signed, or migrate_legacy=False) is kept as is; property_handling is not applied to it. A dict with any other (or no) vcon value is taken as is.

Parameters:
  • vcon_dict – A dictionary representing a vCon. Defaults to an empty dict.

  • property_handling – How to handle non-standard properties. Options are: - “default”: Keep non-standard properties (default) - “strict”: Remove non-standard properties - “meta”: Move non-standard properties to meta object

  • migrate_legacy – Migrate 0.4.0 input to 0.5.0 (default True). When False the 0.4.0 dict is kept untouched and is_valid() will report it as not 0.5.0.

  • strict_migration – Passed to the migration as strict; raises MigrationError when a required field has no source.

Example

>>> vcon = Vcon({"uuid": "123", "custom_field": "value"})
>>> strict_vcon = Vcon({"uuid": "123", "custom_field": "value"}, property_handling="strict")
>>> meta_vcon = Vcon({"uuid": "123", "custom_field": "value"}, property_handling="meta")
add_analysis(*, type: str, vendor: str, body: Dict[str, Any] | List[Any] | str, dialog: int | List[int] | None = None, sessions: int | List[int] | None = None, attachment: int | List[int] | None = None, analysis: int | List[int] | None = None, encoding: str = 'none', mediatype: str | None = None, filename: str | None = None, product: str | None = None, url: str | None = None, content_hash: str | None = None, schema: Dict[str, Any] | None = None, meta: Dict[str, Any] | None = None, **extra) → None[source]

Add analysis data to the vCon.

This method adds analysis data with the specified parameters to the vCon’s analysis list. Analysis data can be associated with one or more dialog entries and includes metadata about the vendor who performed the analysis.

Parameters:
  • type – The type of analysis

  • dialog – Index or list of indices of the associated dialog entries (optional)

  • sessions – Index or list of indices of the Sessions analysed (optional)

  • attachment – Index or list of indices of the attachments analysed (optional)

  • analysis – Index or list of indices of other Analysis Objects used (optional)

  • vendor – The name of the vendor who performed the analysis

  • body – The analysis data

  • encoding – The encoding format of the body (default: “none”)

  • mediatype – Optional media type of the analysis content

  • filename – Optional filename for the analysis content

  • product – Optional product name of the vendor

  • url – Optional URL for external analysis content

  • content_hash – Optional content hash for external analysis content

  • schema – Optional schema information about the analysis (default: None)

  • meta – Optional metadata about the analysis (default: None)

  • **extra – Additional key-value pairs to include in the analysis

Raises:

Exception – If the encoding is invalid or if the body format is invalid for the specified encoding

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_analysis(
...     type="sentiment",
...     dialog=[0],
...     vendor="acme",
...     body={"score": 0.8},
...     encoding="json",
...     schema={"version": "1.0"},
...     meta={"confidence": "high"}
... )
add_attachment(purpose: str, body: Any = None, encoding: str = 'none', mediatype: str | None = None, filename: str | None = None, url: str | None = None, content_hash: str | None = None, start: str | None = None, party: int | None = None, dialog: int | None = None, session: int | List[int] | None = None) → Attachment[source]

Add an attachment to the vCon.

This method creates a new attachment with the specified type, body, and encoding and adds it to the vCon’s attachments list.

Core-05 needs party plus dialog or session. party defaults to 0. If neither dialog nor session is given, the attachment is scoped to the only Session when the vCon has exactly one; otherwise ValueError is raised rather than inventing a scope.

Parameters:
  • purpose – The purpose of the attachment

  • body – The content of the attachment

  • encoding – The encoding format for the body (default: “none”)

  • mediatype – Optional media type of the attachment

  • filename – Optional file name of the attachment

  • url – Optional URL for external attachments

  • content_hash – Optional content hash for external attachments

  • start – Optional timestamp for the attachment

  • party – Optional party index (default 0)

  • dialog – Optional dialog index

  • session – Optional Session index or list of indices

Returns:

The created Attachment object

Raises:

ValueError – If the specified encoding is not supported

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Alice"))
>>> vcon.add_session()
>>> attachment = vcon.add_attachment("metadata", {"version": "1.0"}, "json")
>>> print(attachment.purpose)  # Prints "metadata"
add_critical(extension: str) → None[source]

Add an extension to the critical list.

Parameters:

extension – The name of the extension that must be supported

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_critical("encryption")
>>> vcon.add_critical("video")
add_dialog(dialog: Dialog, session: int | None = None) → int[source]

Add a dialog entry to the vCon.

This method adds a Dialog object to the vCon’s dialog list. A dialog entry represents a segment of the conversation with its associated metadata. Use Dialog.placeholder() to add an empty Dialog Object ({}) that holds an array position.

Parameters:
  • dialog – The Dialog object to add

  • session – Optional index of an existing Session; the new Dialog’s index is appended to that Session’s dialog list. Core-05 requires at least one Session when the vCon has Dialogs, so add Sessions with add_session().

Returns:

The index of the new Dialog in the dialog array.

Example

>>> vcon = Vcon.build_new()
>>> dialog = Dialog(type="text", start="2023-01-01T00:00:00Z", parties=[0])
>>> index = vcon.add_dialog(dialog)
add_event(event: Event | Dict[str, Any]) → int[source]

Add an Event Object and return its index in the events array.

An Event is checked against the per-type parameter table when it is built; a plain dict is checked by is_valid().

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_event(Event(type="join", time="2023-01-01T00:00:00Z", sessions=0, party=0))
add_extension(extension: str) → None[source]

Add an extension to the vCon.

Parameters:

extension – The name of the extension to add

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_extension("video")
>>> vcon.add_extension("encryption")
add_image(image_path: str, purpose: str = 'image', party: int | None = None, dialog: int | None = None, session: int | List[int] | None = None) → Attachment[source]

Add an image attachment to the vCon.

This method creates a new attachment with the specified image and adds it to the vCon’s attachments list.

Parameters:
  • image_path – Path to the image file

  • purpose – The purpose of the attachment (default: “image”)

  • party – Party index (default 0)

  • dialog – Dialog index

  • session – Session index or list of indices. With neither dialog nor session, the only Session is used when the vCon has exactly one, as in add_attachment().

Returns:

The created Attachment object

Raises:
  • FileNotFoundError – If the image file cannot be found

  • ValueError – If the image format is not supported, or no dialog/session is given and the vCon does not have exactly one Session

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_session()
>>> attachment = vcon.add_image("document.pdf", "identification")
>>> print(attachment.mediatype)  # Prints "application/pdf"
add_incomplete_dialog(start: str | datetime, disposition: str, details: Dict[str, Any] | None = None, parties: List[int] = None, metadata: Dict[str, Any] | None = None, session: int | None = None) → int[source]

Add an incomplete dialog entry to the vCon.

This method creates a dialog entry of type “incomplete” for conversations that failed to be set up. Under core-05 an incomplete Dialog has no content (no body, mediatype, filename, encoding, url or content_hash), and its parties is the party that attempted the call, the originator. details is kept under metadata["details"].

Parameters:
  • start – When the attempt occurred (ISO 8601 string or datetime)

  • disposition – Reason for the incomplete conversation (for example “no-answer”)

  • details – Additional details about the failure (optional)

  • parties – The party (or parties) that attempted the conversation (optional)

  • metadata – Additional metadata (optional)

  • session – Optional Session index to add the Dialog to

Returns:

The index of the new Dialog.

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_incomplete_dialog(
...     start="2023-01-20T14:00:00Z",
...     disposition="no-answer",
...     details={"ringDuration": 45000},
...     parties=[0]
... )
add_lawful_basis_attachment(lawful_basis: str, expiration: str, purpose_grants: list, party_index: int | None = None, dialog_index: int | None = None, session_index: int | List[int] | None = None, **kwargs) → None[source]

Add a lawful basis attachment to the vCon.

The attachment has purpose "lawful_basis". Under core-05 it is scoped with party plus session: pass session_index (and party_index, the party that records the basis). The scope is never widened or invented: dialog_index alone gives a dialog-only scope (a warning is logged, because 0.5.0 scopes a basis to Sessions), and with neither index the only Session is used when the vCon has exactly one; otherwise ValueError is raised. party defaults to 0 with a warning. The lawful_basis extension name is added to extensions.

Parameters:
  • lawful_basis – The lawful basis type (consent, contract, etc.)

  • expiration – ISO 8601 timestamp when the lawful basis expires

  • purpose_grants – List of purpose grant dictionaries

  • party_index – Index of the party that records the basis (default 0)

  • dialog_index – Index of the dialog this applies to (optional)

  • session_index – Session index or list of indices this applies to (optional)

  • **kwargs – Additional lawful basis parameters

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Alice"))
>>> vcon.add_session()
>>> vcon.add_lawful_basis_attachment(
...     lawful_basis="consent",
...     expiration="2026-01-01T00:00:00Z",
...     purpose_grants=[
...         {"purpose": "recording", "granted": True, "granted_at": "2025-01-01T00:00:00Z"}
...     ]
... )
add_party(party: Party) → None[source]

Add a party to the vCon.

This method adds a party object to the vCon’s parties list. A party represents a participant in the conversation.

Parameters:

party – The Party object to add

Example

>>> vcon = Vcon.build_new()
>>> party = Party(type="person", name="John Doe")
>>> vcon.add_party(party)
add_session(session: Session | Dict[str, Any] | None = None) → int[source]

Add a Session Object and return its index in the sessions array.

With no argument an empty placeholder Session ({}) is added, which core-05 permits.

Example

>>> vcon = Vcon.build_new()
>>> s = vcon.add_session(Session(start="2023-01-01T00:00:00Z", parties=[0, 1]))
add_tag(tag_name: str, tag_value: str, party: int | None = None) → None[source]

Add a tag to the vCon.

This method adds a tag with the specified name and value to the vCon’s tags attachment. If no tags attachment exists, it creates one.

Core-05 requires the attachment’s party to be a valid party index (the party that adds the tags). It defaults to 0. On a vCon with no parties this still writes party 0 but warns (DeprecationWarning), because the result fails is_valid(); from vcon 1.1 it will raise.

Parameters:
  • tag_name – The name of the tag

  • tag_value – The value to associate with the tag

  • party – Party index for a new tags attachment (default 0)

Raises:

ValueError – If party is given (or the vCon has parties) and it is not a valid party index

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Acme Corp"))
>>> vcon.add_tag("category", "meeting")
>>> vcon.add_tag("priority", "high")
add_transfer_dialog(*args: Any, **kwargs: Any) → None[source]

Removed: core-05 has no transfer Dialog type.

Raises NotImplementedError with the replacement: a transfer is one or two transfer Events (blind-transfer, consultation-start plus consultative-transfer, or transfer-abandoned) added with add_event(Event(...)), whose sessions/consultation/ target_session reference Sessions for the calls involved.

add_wtf_transcription_analysis(transcript: Dict[str, Any], segments: List[Dict[str, Any]], metadata: Dict[str, Any], dialog_index: int | None = None, session_index: int | List[int] | None = None, **kwargs) → None[source]

Add a WTF transcription as an analysis entry (vs. an attachment).

This is the placement draft-howe-vcon-wtf-extension requires (section 6.1: transcription results MUST be stored as analysis). add_wtf_transcription_attachment writes to attachments[] and is deprecated.

Emits the analysis entry defined by draft-howe-vcon-wtf-extension (section 5.3): type="wtf_transcription", vendor and product taken from metadata["provider"] / metadata["model"], schema set to the WTF draft URL, encoding="json", and body as the WTF document itself (a JSON value, not a serialized string).

Parameters:
  • transcript – Transcript information dictionary

  • segments – List of segment dictionaries

  • metadata – Metadata dictionary; provider and model keys map to vendor and product on the analysis entry

  • dialog_index – Index of the dialog this transcription applies to

  • session_index – Session index or indices this transcription applies to

  • **kwargs – Additional WTF parameters (words, speakers, quality, etc.)

add_wtf_transcription_attachment(transcript: Dict[str, Any], segments: List[Dict[str, Any]], metadata: Dict[str, Any], party_index: int | None = None, dialog_index: int | None = None, session_index: int | List[int] | None = None, **kwargs) → None[source]

Add a WTF transcription attachment to the vCon.

Deprecated: draft-howe-vcon-wtf-extension stores transcriptions as analysis (section 6.1). Use add_wtf_transcription_analysis().

Scoped by dialog_index and/or session_index as given; with neither, the only Session when the vCon has exactly one, else ValueError (see add_attachment).

Parameters:
  • transcript – Transcript information dictionary

  • segments – List of segment dictionaries

  • metadata – Metadata dictionary

  • party_index – Index of the party this applies to (optional)

  • dialog_index – Index of the dialog this applies to (optional)

  • session_index – Session index or list of indices (optional)

  • **kwargs – Additional WTF parameters

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Alice"))
>>> vcon.add_session()
>>> vcon.add_wtf_transcription_attachment(
...     transcript={"text": "Hello world", "language": "en", "duration": 2.0, "confidence": 0.95},
...     segments=[{"id": 0, "start": 0.0, "end": 2.0, "text": "Hello world", "confidence": 0.95}],
...     metadata={"created_at": "2025-01-01T00:00:00Z", "processed_at": "2025-01-01T00:00:01Z",
...              "provider": "whisper", "model": "whisper-1"}
... )
property amended

Deprecated 0.4.0 name; returns amended_from.

property amended_from
property analysis: List[Dict[str, Any]]

Get the list of analysis entries in the vCon.

Returns:

A list of analysis dictionaries

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_analysis(type="sentiment", dialog=[0], vendor="acme", body={"score": 0.8})
>>> analysis = vcon.analysis
>>> print(analysis[0]["type"])  # Prints "sentiment"
property attachments: List[Dict[str, Any]]

Get the list of attachments in the vCon.

Returns:

A list of attachment dictionaries

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Alice"))
>>> vcon.add_session()
>>> vcon.add_attachment("metadata", {"version": "1.0"})
>>> attachments = vcon.attachments
>>> print(attachments[0]["purpose"])  # Prints "metadata"
classmethod build_from_json(json_string: str, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) → Vcon[source]

Initialize a Vcon object from a JSON string.

This method parses a JSON string representation of a vCon and creates a new Vcon object from it.

Parameters:
  • json_string – A JSON string representing a vCon

  • property_handling – How to handle non-standard properties.

Returns:

A new Vcon object initialized with the parsed JSON data

Raises:

json.JSONDecodeError – If the JSON string is invalid

Example

>>> json_str = '{"uuid": "123"}'
>>> vcon = Vcon.build_from_json(json_str)
classmethod build_new(created_at: str | datetime = None, property_handling: str = 'default') → Vcon[source]

Initialize a new Vcon object with default values.

This method creates a new vCon with a generated UUID and initialized with empty arrays for groups, parties, dialog, attachments, and analysis.

Parameters:
  • created_at (Union[str, datetime], optional) – The timestamp to set for creation, either as a string in ISO format or as a datetime object. Defaults to current time.

  • property_handling – How to handle non-standard properties.

Returns:

A new Vcon object with default values

Example

>>> vcon = Vcon.build_new()
>>> print(vcon.uuid)  # Prints a new UUID8
check_lawful_basis_permission(purpose: str, party_index: int | None = None) → bool[source]

Check if permission is granted for a specific purpose.

Parameters:
  • purpose – The purpose to check permission for

  • party_index – Index of the party to check (optional)

Returns:

True if permission is granted, False otherwise

property created_at
static decoded_body(entry: Dict[str, Any] | None) → Any[source]

Return the decoded body of an attachment, analysis, or dialog entry.

Under draft-ietf-vcon-vcon-core-04, a "json"-encoded body is the JSON value itself, not a json.dumps string. This accepts both that shape and the JSON-string bodies written under -02 conventions (or by this library prior to 0.10.0), so callers don’t need to special-case legacy vCons.

Parameters:

entry – An attachment, analysis, or dialog dictionary

Returns:

The decoded body, or None if there is no body

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Alice"))
>>> vcon.add_session()
>>> vcon.add_tag("category", "meeting")
>>> Vcon.decoded_body(vcon.tags)  # ["category:meeting"]
property dialog: List[Dict[str, Any]]

Get the list of dialog entries in the vCon.

Returns:

A list of dialog dictionaries representing the conversation content. These are mutable references to the internal data structure, allowing in-place modifications.

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_dialog(Dialog(type="text", start="2023-01-01T00:00:00Z", parties=[0]))
>>> dialog = vcon.dialog
>>> print(dialog[0]["type"])  # Prints "text"
>>> dialog[0]["body"] = "Modified content"  # In-place modification works
>>> print(vcon.dialog[0]["body"])  # Prints "Modified content"
dumps() → str[source]

Alias for to_json().

This method is an alias for to_json() and converts the vCon object to a JSON string representation.

Returns:

A JSON string representation of the vCon

Example

>>> vcon = Vcon.build_new()
>>> json_str = vcon.dumps()
>>> print(type(json_str))  # Prints "<class 'str'>"
property events: List[Dict[str, Any]]

The events array (Event Objects).

find_analysis_by_type(type: str) → Dict[str, Any] | None[source]

Find an analysis entry in the vCon by its type.

This method searches through the vCon’s analysis entries and returns the first one matching the specified type.

Parameters:

type – The type of analysis to find

Returns:

The matching analysis dictionary if found, None otherwise

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_analysis(type="sentiment", dialog=[0], vendor="acme", body={"score": 0.8})
>>> sentiment = vcon.find_analysis_by_type("sentiment")
find_attachment_by_purpose(purpose: str) → Dict[str, Any] | None[source]

Find an attachment in the vCon by its purpose.

This method searches through the vCon’s attachments and returns the first attachment matching the specified type.

Parameters:

purpose – The purpose of attachment to find

Returns:

The matching attachment dictionary if found, None otherwise

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Alice"))
>>> vcon.add_session()
>>> vcon.add_attachment("metadata", {"version": "1.0"})
>>> metadata = vcon.find_attachment_by_purpose("metadata")
find_dialog(by: str, val: str) → Dialog | None[source]

Find a dialog entry in the vCon by a key-value pair.

This method searches through the dialog list and returns the first dialog entry that matches the specified key-value pair, converted to a Dialog object.

Parameters:
  • by – The key to search by (e.g., “type”, “start”)

  • val – The value to match

Returns:

A Dialog object if found, None otherwise

Example

>>> vcon = Vcon.build_new()
>>> dialog = Dialog(type="text", start="2023-01-01T00:00:00Z", parties=[0])
>>> vcon.add_dialog(dialog)
>>> found = vcon.find_dialog("type", "text")
>>> print(found.type)  # Prints "text"
find_dialogs_by_type(type: str) → List[Dict[str, Any]][source]

Find all dialog entries in the vCon by type. This method searches through the dialog list and returns all dialog entries matching the specified type. :param type: The type of dialogs to find

Returns:

A list of matching dialog dictionaries

Example

>>> vcon = Vcon.build_new()
>>> incomplete = vcon.find_dialogs_by_type("incomplete")
find_lawful_basis_attachments(party_index: int | None = None) → List[Dict[str, Any]][source]

Find lawful basis attachments in the vCon.

Parameters:

party_index – Filter by party index (optional)

Returns:

List of lawful basis attachment dictionaries

find_party_index(by: str, val: str) → int | None[source]

Find the index of a party in the vCon’s parties list.

This method searches through the parties list and returns the index of the first party that matches the specified key-value pair.

Parameters:
  • by – The key to search by (e.g., “name”, “type”)

  • val – The value to match

Returns:

The index of the matching party if found, None otherwise

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(type="person", name="John Doe"))
>>> index = vcon.find_party_index("name", "John Doe")
>>> print(index)  # Prints 0
find_wtf_attachments(party_index: int | None = None) → List[Dict[str, Any]][source]

Find WTF transcription attachments in the vCon.

Parameters:

party_index – Filter by party index (optional)

Returns:

List of WTF attachment dictionaries

classmethod generate_key_pair() → Tuple[RSAPrivateKey, RSAPublicKey][source]

Generate a new RSA key pair for signing vCons.

This method generates a new RSA key pair that can be used for signing and verifying vCons.

Returns:

A tuple containing the private key and public key

Example

>>> private_key, public_key = Vcon.generate_key_pair()
>>> vcon = Vcon.build_new()
>>> vcon.sign(private_key)
>>> is_valid = vcon.verify(public_key)
get_critical() → List[str][source]

Get the list of critical extensions that must be supported.

Returns:

List of extension names that must be supported, empty list if none are defined

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_critical("encryption")
>>> critical = vcon.get_critical()
>>> print(critical)  # Prints ["encryption"]
get_extensions() → List[str][source]

Get the list of extensions used in this vCon.

Returns:

List of extension names, empty list if none are defined

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_extension("video")
>>> extensions = vcon.get_extensions()
>>> print(extensions)  # Prints ["video"]
get_party_objects() → List[Party][source]

Get the list of parties as Party objects.

This method creates Party objects from the underlying dictionary data. Use this when you need Party objects instead of raw dictionaries.

Returns:

A list of Party objects representing all participants in the conversation

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(type="person", name="John Doe"))
>>> party_objects = vcon.get_party_objects()
>>> print(party_objects[0].name)  # Prints "John Doe"
get_tag(tag_name: str) → str | None[source]

Get the value of a specific tag by name.

Parameters:

tag_name – The name of the tag to retrieve

Returns:

The value of the tag if found, None otherwise

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Alice"))
>>> vcon.add_session()
>>> vcon.add_tag("category", "meeting")
>>> value = vcon.get_tag("category")
>>> print(value)  # Prints "meeting"
get_validation_warnings() → List[str][source]

SHOULD-level findings (for example SHOULD NOT parameters on Events).

property group
is_valid() → Tuple[bool, List[str]][source]

Validate the vCon against the core-05 rules.

Checks required fields and types, that vcon (if present) is “0.5.0”, that Sessions, Events, Dialogs, attachments and analysis reference existing objects, the per-event-type parameter table, that at least one Session exists when there are Dialogs or Events, that attachments have party and dialog or session, that redacted_from and amended_from are exclusive, that extensions lists every extension in use (and every critical entry), that every __REDACTED_REF_# has a redacted_strings entry, that every url has a content_hash and every content_hash is well formed, and the body of every lawful_basis attachment.

SHOULD-level findings are not errors; see get_validation_warnings().

Returns:

A tuple where the first element is True if the vCon is valid and False otherwise, and the second element is a list of error messages.

Return type:

Tuple[bool, List[str]]

classmethod load(source: str, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) → Vcon[source]

Load a vCon from either a file path or URL.

Parameters:
  • source – File path or URL to load the vCon from

  • property_handling – How to handle non-standard properties. Options are “default”, “strict”, or “meta”

Returns:

A Vcon object

Raises:
  • ValueError – If the source is invalid or cannot be loaded

  • requests.RequestException – If there is an error fetching from URL

  • json.JSONDecodeError – If the source contains invalid JSON

classmethod load_from_file(file_path: str, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) → Vcon[source]

Load a vCon from a file.

Parameters:
  • file_path – Path to the vCon JSON file

  • property_handling – How to handle non-standard properties. Options are “default”, “strict”, or “meta”

Returns:

A Vcon object

Raises:
  • FileNotFoundError – If the file does not exist

  • json.JSONDecodeError – If the file contains invalid JSON

classmethod load_from_url(url: str, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) → Vcon[source]

Load a vCon from a URL.

Parameters:
  • url – URL to fetch the vCon JSON from

  • property_handling – How to handle non-standard properties. Options are “default”, “strict”, or “meta”

Returns:

A Vcon object

Raises:
  • requests.RequestException – If there is an error fetching from URL

  • json.JSONDecodeError – If the response contains invalid JSON

property meta
classmethod migrate_0_4_0_to_0_5_0(source: str | Dict[str, Any], strict: bool = False, property_handling: str = 'default') → Vcon[source]

Explicitly migrate a 0.4.0 vCon (dict or JSON string) and return a Vcon.

The migration report is available as vcon.migration_report. Unlike the implicit migration on load, this also accepts input with no vcon parameter. See vcon.migration.migrate_0_4_0_to_0_5_0().

migration_report: MigrationReport | None

MigrationReport when the input was migrated from 0.4.0, else None.

property parties: List[Dict[str, Any]]

Get the list of parties in the vCon.

Returns:

A list of party dictionaries representing all participants in the conversation. These are mutable references to the internal data structure, allowing in-place modifications.

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(type="person", name="John Doe"))
>>> parties = vcon.parties
>>> print(parties[0]["name"])  # Prints "John Doe"
>>> parties[0]["name"] = "Jane Doe"  # In-place modification works
>>> print(vcon.parties[0]["name"])  # Prints "Jane Doe"
post_to_url(url: str, headers: Dict[str, str] | None = None) → Response[source]

Post the vCon as JSON to a URL with optional headers.

Parameters:
  • url (str) – The URL to post the vCon to

  • headers (Optional[Dict[str, str]]) – Optional dictionary of HTTP headers (e.g., {‘x-conserver-api-token’: ‘token123’})

Returns:

The HTTP response from the server

Return type:

requests.Response

Raises:

requests.RequestException – If there is an error making the HTTP request

Example

>>> vcon = Vcon.build_new()
>>> response = vcon.post_to_url(
...     'https://api.example.com/vcons',
...     headers={'x-conserver-api-token': 'your-token-here'}
... )
>>> print(response.status_code)  # Prints HTTP status code (e.g., 200 for success)
process_extensions() → Dict[str, Any][source]

Process all extensions in the vCon.

Returns:

Dictionary with processing results for each extension

property redacted

Deprecated 0.4.0 name; returns redacted_from.

property redacted_from
property redacted_strings: List[Dict[str, Any]]
remove_critical(extension: str) → None[source]

Remove an extension from the critical list.

Parameters:

extension – The name of the extension to remove from critical

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_critical("encryption")
>>> vcon.remove_critical("encryption")
remove_extension(extension: str) → None[source]

Remove an extension from the vCon.

Parameters:

extension – The name of the extension to remove

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_extension("video")
>>> vcon.remove_extension("video")
save_to_file(file_path: str) → None[source]

Save the vCon to a JSON file.

Parameters:

file_path (str) – Path where the vCon JSON should be saved

Raises:

IOError – If there is an error writing to the file

property sessions: List[Dict[str, Any]]

The sessions array (Session Objects).

set_created_at(created_at: str | datetime) → None[source]

Set the created_at field in the vCon.

Parameters:

created_at (Union[str, datetime]) – The timestamp to set, either as a string in ISO format or as a datetime object.

set_updated_at(timestamp: str | datetime) → None[source]

Set the updated_at timestamp.

Args: timestamp: The timestamp to set, either as ISO 8601 string or datetime object

Example: >>> vcon = Vcon.build_new() >>> vcon.set_updated_at(datetime.now(timezone.utc)) >>> vcon.set_updated_at(“2025-02-18T12:00:00Z”)

sign(private_key: RSAPrivateKey | bytes, alg: str = 'RS256') → None[source]

Sign the vCon using JWS (JSON Web Signature).

This method signs the vCon using the provided private key, adding the signature information to the vCon. The signature can later be verified using the corresponding public key.

Parameters:
  • private_key – The RSA private key or its PEM representation

  • alg – JWS algorithm (default “RS256”, the value core-05 says SHOULD be used). “none” is rejected (6.2.2).

Raises:
  • AlgorithmNotPermittedError – If alg is “none” (any case) or is not a permitted algorithm.

  • Exception – If there is an error during the signing process

Example

>>> from cryptography.hazmat.primitives.asymmetric import rsa
>>> private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
>>> vcon = Vcon.build_new()
>>> vcon.sign(private_key)
property subject: str | None
property tags: Dict[str, Any] | None

Get the tags attachment from the vCon.

Returns:

The tags attachment dictionary if it exists, None otherwise

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Alice"))
>>> vcon.add_session()
>>> vcon.add_tag("category", "meeting")
>>> tags = vcon.tags
>>> print(tags["body"])  # Prints ["category:meeting"]
to_dict() → Dict[str, Any][source]

Convert the vCon to a dictionary.

This method returns a dictionary representation of the vCon object, which can be used for direct manipulation or inspection.

Returns:

A dictionary representation of the vCon

Example

>>> vcon = Vcon.build_new()
>>> vcon_dict = vcon.to_dict()
>>> print(vcon_dict["vcon"])  # Prints "0.5.0"
to_json() → str[source]

Serialize the vCon to a JSON string.

This method converts the entire vCon object to a JSON string representation, which can be used for storage or transmission.

Returns:

A JSON string representation of the vCon

Example

>>> vcon = Vcon.build_new()
>>> json_str = vcon.to_json()
>>> print(type(json_str))  # Prints "<class 'str'>"
property updated_at
property uuid: str
static uuid8_domain_name(domain_name: str) → str[source]
static uuid8_time(custom_c_62_bits: int) → str[source]
validate_extensions() → Dict[str, Any][source]

Validate all extensions in the vCon.

Returns:

Dictionary with validation results for each extension

static validate_file(file_path: str) → tuple[bool, list[str]][source]

Validate a vCon file at the given path.

Parameters:

file_path (str) – Path to the vCon JSON file

Returns:

A tuple containing (is_valid, list_of_errors)

Return type:

tuple[bool, list[str]]

static validate_json(json_str: str) → tuple[bool, list[str]][source]

Validate a vCon from a JSON string.

Parameters:

json_str (str) – JSON string representing a vCon

Returns:

A tuple containing (is_valid, list_of_errors)

Return type:

tuple[bool, list[str]]

property vcon: str | None
verify(public_key: RSAPublicKey | bytes) → bool[source]

Verify the JWS signature of the vCon.

This method verifies the vCon’s signature using the provided public key. The vCon must have been previously signed using the corresponding private key.

Parameters:

public_key – The RSA public key or its PEM representation

Returns:

True if the signature is valid, False otherwise

Raises:
  • ValueError – If the vCon is not signed

  • AlgorithmNotPermittedError – If the signature declares alg “none” (in the protected header or the signature’s header), which core-05 forbids. Verification is refused rather than skipped.

Example

>>> private_key, public_key = Vcon.generate_key_pair()
>>> vcon = Vcon.build_new()
>>> vcon.sign(private_key)
>>> is_valid = vcon.verify(public_key)
>>> print(is_valid)  # Prints True
vcon.compute_content_hash(data: bytes, algorithm: str = 'sha512') → str[source]

Compute a spec-formatted content hash for raw bytes.

Returns "<algorithm>-<base64url-no-padding>" as required by draft-ietf-vcon-vcon-core-02 (e.g. "sha512-GLy6IPa...").

Parameters:
  • data (bytes) – the raw bytes to hash

  • algorithm (str) – the hash algorithm to use (default: "sha512"); "sha256" is also supported for backwards compatibility

Returns:

the algorithm-prefixed, unpadded base64url content hash

Return type:

str

Raises:

ValueError – if algorithm is not a supported algorithm

vcon.migrate_0_4_0_to_0_5_0(vcon: Any, *, strict: bool = False) → MigrationResult[source]

Migrate a 0.4.0 vCon dict (or JSON string) to 0.5.0.

Parameters:
  • vcon – The 0.4.0 vCon as a dict or JSON string. A signed vCon (JWS general form) is migrated as its unsigned payload. The input is not modified.

  • strict – When True, raise MigrationError instead of using a fallback for a MUST field that cannot be sourced from the input.

Returns:

the 0.5.0 dict and the MigrationReport listing every inferred value, fallback and unresolved item.

Return type:

MigrationResult(vcon, report)

Raises:

MigrationError – the input is not a 0.4.0 vCon, is encrypted, or (strict) a required field has no source.

vcon.parse_content_hash_algorithm(content_hash: str) → str | None[source]

Return the algorithm prefix of content_hash.

Parameters:

content_hash (str) – a content hash value, optionally prefixed

Returns:

"sha512" or "sha256" for a prefixed value, or None for a legacy unprefixed hash (which this library historically emitted as a padded base64url SHA-256 digest)

Return type:

str or None

vcon.body module

Helpers for decoding vCon attachment/analysis/dialog bodies.

Under draft-ietf-vcon-vcon-core-04 section 2.3.2, when encoding is "json" the body field is the JSON value itself (object, array, string, number, bool, or null) rather than a json.dumps-serialized string. Earlier drafts (and adapters/generators written against them, plus some helpers in this library prior to 0.10.0) instead stored the JSON representation of the value as a string body.

decode_body lets every reader in this library – and callers of it – accept either shape without special-casing each call site. It is exported both as a module-level function and as Vcon.decoded_body for discoverability.

vcon.body.decode_body(entry: Dict[str, Any] | None) → Any[source]

Return the decoded body of an attachment, analysis, or dialog entry.

If encoding is "json" (or absent – structured bodies were most commonly written without an explicit encoding under -02 conventions) and body is a string, the string is parsed as JSON and the resulting value is returned. This accepts both:

  • vCons written under -02 conventions (or by this library prior to 0.10.0), where a JSON body was serialized to a string, and

  • -04-conformant vCons, where body is already the decoded value.

Any other shape – an already-decoded value, a base64url/none encoded body, or a string that fails to parse as JSON – is returned unchanged.

Parameters:

entry (dict or None) – an attachment, analysis, or dialog dict, or None

Returns:

the decoded body, or None if there is no body to decode

Return type:

Any

vcon.civic_address module

class vcon.civic_address.CivicAddress(country: str | None = None, a1: str | None = None, a2: str | None = None, a3: str | None = None, a4: str | None = None, a5: str | None = None, a6: str | None = None, prd: str | None = None, pod: str | None = None, sts: str | None = None, hno: str | None = None, hns: str | None = None, lmk: str | None = None, loc: str | None = None, flr: str | None = None, nam: str | None = None, pc: str | None = None)[source]

Bases: object

A class representing civic address information according to GEOPRIV specification.

This class supports all civic address fields defined in RFC 4776 (GEOPRIV) and is used within vCon Party objects to provide location information.

Administrative areas (a1-a6): - a1: Administrative area 1 (e.g., state or province) - a2: Administrative area 2 (e.g., county or municipality) - a3: Administrative area 3 (e.g., city or town) - a4: Administrative area 4 (e.g., neighborhood or district) - a5: Administrative area 5 (e.g., postal code) - a6: Administrative area 6 (e.g., building or floor)

Street and building information: - sts: Street name - hno: House number - hns: House name - prd: Premier (e.g., department or suite number) - flr: Floor

Location and identification: - country: Country code (ISO 3166-1 alpha-2) - pc: Postal code - nam: Name of the location - lmk: Landmark name - loc: Location name - pod: Post office box identifier

All fields are optional and follow the GEOPRIV specification format. Field names are in lowercase as required by the vCon specification.

__init__(country: str | None = None, a1: str | None = None, a2: str | None = None, a3: str | None = None, a4: str | None = None, a5: str | None = None, a6: str | None = None, prd: str | None = None, pod: str | None = None, sts: str | None = None, hno: str | None = None, hns: str | None = None, lmk: str | None = None, loc: str | None = None, flr: str | None = None, nam: str | None = None, pc: str | None = None)[source]

Initialize a new CivicAddress object.

Parameters:
  • country (str) – Country code (ISO 3166-1 alpha-2)

  • a1 (str) – Administrative area 1 (e.g. state or province)

  • a2 (str) – Administrative area 2 (e.g. county or municipality)

  • a3 (str) – Administrative area 3 (e.g. city or town)

  • a4 (str) – Administrative area 4 (e.g. neighborhood or district)

  • a5 (str) – Administrative area 5 (e.g. postal code)

  • a6 (str) – Administrative area 6 (e.g. building or floor)

  • prd (str) – Premier (e.g. department or suite number)

  • pod (str) – Post office box identifier

  • sts (str) – Street name

  • hno (str) – House number

  • hns (str) – House name

  • lmk (str) – Landmark name

  • loc (str) – Location name

  • flr (str) – Floor

  • nam (str) – Name of the location

  • pc (str) – Postal code

to_dict() → dict[str, Optional[str]][source]

Convert the CivicAddress object to a dictionary.

The dictionary keys are the attribute names of the object, and the values are the attribute values.

Returns:

A dictionary of the object’s attributes

Return type:

dict[str, Optional[str]]

vcon.dialog module

class vcon.dialog.Dialog(type: str, start: datetime | str, parties: List[int], mediatype: str | None = None, filename: str | None = None, body: str | None = None, encoding: str | None = None, url: str | None = None, disposition: str | None = None, campaign: str | None = None, interaction: str | None = None, skill: str | None = None, duration: float | None = None, meta: dict | None = None, metadata: Dict[str, Any] | None = None, signaling: Dict[str, Any] | None = None, resolution: str | None = None, frame_rate: float | None = None, codec: str | None = None, bitrate: int | None = None, thumbnail: str | None = None, session_id: Dict[str, str] | List[Dict[str, str]] | None = None, content_hash: str | None = None, application: str | None = None, message_id: str | None = None, redacted_segments: List[Dict[str, Any]] | None = None, **kwargs)[source]

Bases: object

A class representing a dialog segment in a vCon conversation.

A dialog represents a piece of conversation content, which can be: - text: Text-based communication (email, chat, SMS) - recording: Audio/video recording of the conversation - incomplete: Failed or incomplete conversation setup

"audio" and "video" are accepted as deprecated aliases for recording.

Dialog content can be stored inline or referenced externally: - Inline: Content stored directly in the body field - External: Content referenced via URL with content_hash for integrity

Media support: - Audio formats: WAV, MP3, MP4, OGG, WebM, AAC - Video formats: MP4, WebM, AVI, MKV, MOV, FLV, 3GP - Text formats: Plain text, multipart messages - Images: JPEG, TIFF, PDF

Changes in vCon 0.5.0 (draft-ietf-vcon-vcon-core-05):

  • parties lists the contributors only. The receivers are in the parties of the Session Object that references the dialog.

  • originator moved to the Session Object.

  • party_history was replaced by Event Objects (vcon.event.Event).

  • The transfer and recording-set dialog types were removed. Transfers are Events; a recording set is a Session.

  • An empty Dialog Object (Dialog.placeholder(), serialized as {}) holds a position in the dialog array so that indices do not change.

  • redacted_segments was added.

MIME_TYPES = ['text/plain', 'audio/x-wav', 'audio/wav', 'audio/wave', 'audio/mpeg', 'audio/mp3', 'audio/x-mp3', 'audio/x-mp4', 'audio/ogg', 'audio/webm', 'audio/x-m4a', 'audio/aac', 'video/x-mp4', 'video/ogg', 'video/mp4', 'video/quicktime', 'video/webm', 'video/x-msvideo', 'video/x-matroska', 'video/mpeg', 'video/x-flv', 'video/3gpp', 'video/x-m4v', 'multipart/mixed', 'message/rfc822', 'image/jpeg', 'image/tiff', 'application/pdf', 'application/json']
VALID_DISPOSITIONS = ['no-answer', 'congestion', 'failed', 'busy', 'hung-up', 'voicemail-no-message']
VALID_TYPES = ['recording', 'text', 'incomplete', 'audio', 'video']
__init__(type: str, start: datetime | str, parties: List[int], mediatype: str | None = None, filename: str | None = None, body: str | None = None, encoding: str | None = None, url: str | None = None, disposition: str | None = None, campaign: str | None = None, interaction: str | None = None, skill: str | None = None, duration: float | None = None, meta: dict | None = None, metadata: Dict[str, Any] | None = None, signaling: Dict[str, Any] | None = None, resolution: str | None = None, frame_rate: float | None = None, codec: str | None = None, bitrate: int | None = None, thumbnail: str | None = None, session_id: Dict[str, str] | List[Dict[str, str]] | None = None, content_hash: str | None = None, application: str | None = None, message_id: str | None = None, redacted_segments: List[Dict[str, Any]] | None = None, **kwargs) → None[source]

Initialize a Dialog object. :param type: the type of the dialog (e.g. “text”, “recording”, “incomplete”, “video”) :type type: str :param start: the start time of the dialog :type start: datetime :param parties: the parties that contributed to the dialog (the receivers are in the Session Object) :type parties: List[int] :param mediatype: the MIME type of the dialog body :type mediatype: str or None :param filename: the filename of the dialog body :type filename: str or None :param body: the body of the dialog :type body: str or None :param encoding: the encoding of the dialog body :type encoding: str or None :param url: the URL of the dialog :type url: str or None :param disposition: the disposition of the dialog :type disposition: str or None :param campaign: the campaign that the dialog is associated with :type campaign: str or None :param interaction: the interaction that the dialog is associated with :type interaction: str or None :param skill: the skill that the dialog is associated with :type skill: str or None :param duration: the duration of the dialog :type duration: float or None :param meta: additional metadata for the dialog :type meta: dict or None :param metadata: structured metadata for the dialog (newer format) :type metadata: dict or None :param signaling: signaling-specific information :type signaling: dict or None :param resolution: video resolution (e.g., “1920x1080”) :type resolution: str or None :param frame_rate: video frame rate in fps :type frame_rate: float or None :param codec: video codec (e.g., “H.264”, “H.265”) :type codec: str or None :param bitrate: video bitrate in kbps :type bitrate: int or None :param thumbnail: base64-encoded thumbnail image :type thumbnail: str or None :param session_id: Session identifier :type session_id: str or None :param content_hash: Hash for externally referenced files (replaces alg and signature) :type content_hash: str or None :param application: Application identifier for the dialog :type application: str or None :param message_id: Message identifier for email/text dialogs :type message_id: str or None :param redacted_segments: Redacted_segments Objects (start, end, optional parties) :type redacted_segments: list or None :param kwargs: Additional attributes to be set on the dialog

add_external_data(url: str, filename: str, mediatype: str) → None[source]

Add external data to the dialog.

Parameters:

url (str) – the URL of the external data

Returns:

None

Return type:

None

add_image_data(image_path: str, mediatype: str | None = None) → None[source]

Add image data to the dialog from a local file.

Parameters:
  • image_path (str) – Path to the image file

  • mediatype (str or None) – MIME type of the image (optional, auto-detected if not provided)

Returns:

None

Return type:

None

add_inline_data(body: str | bytes, filename: str, mediatype: str) → None[source]

Add inline data to the dialog.

The Dialog is written with encoding: "base64url". Pass raw bytes and they are encoded; a str is taken to be base64url already. The content_hash is over the decoded content.

Parameters:
  • body (bytes or str) – the content as bytes, or as a base64url string

  • filename (str) – the filename of the inline data

  • mediatype (str) – the mediatype of the inline data

Returns:

None

Return type:

None

add_streaming_video_reference(reference_id, mediatype, metadata=None) → None[source]

Add a reference to a streamable video.

Parameters:
  • reference_id – Unique identifier for the streamable video

  • mediatype – MIME type of the video

  • metadata – Optional video metadata

Returns:

None

add_video_data(video_data, filename=None, mediatype=None, inline=True, metadata=None) → None[source]

Add video data to the dialog.

Parameters:
  • video_data – Binary video data or URL to video

  • filename – Name of the video file

  • mediatype – MIME type of the video, or auto-detected from filename if None

  • inline – Whether to include the video as inline content (True) or external reference (False)

  • metadata – Optional video metadata to include

Returns:

None

add_video_with_optimal_storage(video_data, filename, mediatype=None, size_threshold_mb=10) → None[source]

Add video with the optimal storage method based on size.

Parameters:
  • video_data – Binary video data or URL

  • filename – Name of the video file

  • mediatype – MIME type of the video (optional)

  • size_threshold_mb – Size threshold in MB for inline vs external storage

Returns:

None

calculate_content_hash(algorithm: str = 'sha512') → str[source]

Calculate the content hash for the dialog body.

The hash covers the content itself: for a base64url body that is the decoded bytes, so the value matches a hash of the original file (what add_image_data() stores). Other bodies are hashed as UTF-8.

The returned value is spec-formatted as "<algorithm>-<base64url>" with no base64 padding (draft-ietf-vcon-vcon-core-02), e.g. "sha512-GLy6IPa...".

Parameters:

algorithm (str) – The hash algorithm to use (default: "sha512"). "sha256" is also supported for backwards compatibility.

Returns:

The calculated hash value, prefixed with the algorithm name

Return type:

str

Raises:

ValueError – if there is no body to hash, or algorithm is not a supported algorithm

extract_image_metadata(image_data: bytes, mediatype: str) → None[source]

Extract metadata from image data and add it to the dialog metadata.

Parameters:
  • image_data (bytes) – Raw image data

  • mediatype (str) – MIME type of the image

Returns:

None

Return type:

None

extract_video_metadata(video_path=None) → dict[source]

Extract comprehensive metadata from video content using FFmpeg.

Parameters:

video_path – Optional path to video file. If None, uses the dialog’s content.

Returns:

Dictionary containing detailed video metadata

generate_image_thumbnail(max_size: Tuple[int, int] = (200, 200)) → str | None[source]

Generate a thumbnail for the image and return it as a base64-encoded string.

Parameters:

max_size (Tuple[int, int]) – Maximum thumbnail dimensions (width, height)

Returns:

Base64-encoded thumbnail or None if generation fails

Return type:

str or None

generate_thumbnail(*args, **kwargs)[source]

Generate a thumbnail for an image or a video Dialog.

For an image this calls generate_image_thumbnail() (max_size, returns a base64url string or None). For a video it calls generate_video_thumbnail() (timestamp, width, height, quality; returns JPEG bytes).

generate_video_thumbnail(timestamp=0.0, width=320, height=240, quality=90) → bytes[source]

Generate a high-quality thumbnail from the video at the specified timestamp.

Parameters:
  • timestamp – Time in seconds at which to extract the thumbnail frame

  • width – Desired width of the thumbnail in pixels

  • height – Desired height of the thumbnail in pixels

  • quality – JPEG quality (1-100)

Returns:

Binary thumbnail data in JPEG format

get_content_hash() → str | None[source]

Get the content hash for externally referenced files.

Returns:

The content hash if set, None otherwise

Return type:

str or None

get_session_id() → Dict[str, str] | List[Dict[str, str]] | None[source]

Get the session identifier for this dialog.

Returns:

The session identifier if set, None otherwise

Return type:

str or None

get_video_format_from_mediatype(mediatype: str | None = None) → str[source]

Get the video format name from a MIME type.

Parameters:

mediatype – MIME type of the video (default: this Dialog’s mediatype)

Returns:

Format name (mp4, mov, etc.)

has_thumbnail() → bool[source]

Check if the video has a thumbnail.

Returns:

True if the video has a thumbnail, False otherwise

is_audio() → bool[source]

Check if the dialog has audio content. :return: True if the dialog has audio content, False otherwise :rtype: bool

is_email() → bool[source]

Check if the dialog is an email dialog. :return: True if the dialog is an email dialog, False otherwise :rtype: bool

is_external_data() → bool[source]

Check if the dialog is an external data dialog.

Returns:

True if the dialog is an external data dialog, False otherwise

Return type:

bool

is_external_data_changed() → bool[source]

Check to see if it’s an external data dialog and verify the content hash.

Returns:

True if the dialog is an external data dialog and the contents are valid, False otherwise

Return type:

bool

is_image() → bool[source]

Check if the dialog has image content.

Returns:

True if the dialog has image content, False otherwise

Return type:

bool

is_incomplete() → bool[source]

Check if the dialog is an incomplete dialog. :return: True if the dialog is an incomplete dialog, False otherwise :rtype: bool

is_inline_data() → bool[source]

Check if the dialog is an inline data dialog.

Returns:

True if the dialog is an inline data dialog, False otherwise

Return type:

bool

is_pdf() → bool[source]

Check if the dialog has PDF content.

Returns:

True if the dialog has PDF content, False otherwise

Return type:

bool

is_placeholder() → bool[source]

Check if the dialog is an empty placeholder Dialog Object ({}).

is_recording() → bool[source]

Check if the dialog is a recording dialog. :return: True if the dialog is a recording dialog, False otherwise :rtype: bool

is_text() → bool[source]

Check if the dialog is a text dialog. :return: True if the dialog is a text dialog, False otherwise :rtype: bool

is_transfer() → bool[source]

Deprecated: core-05 has no transfer Dialog type, so this is always False.

is_video(content_type=None) → bool[source]

Check if the dialog has video content.

Parameters:

content_type – Optional content type to check. If None, use the dialog’s mediatype.

Returns:

True if the content is a video format, False otherwise

classmethod placeholder() → Dialog[source]

Create an empty Dialog Object (core-05 section 4.5.1).

It has no parameters and no meaning; it holds a position in the dialog array so that the indices of the other Dialog Objects, and the references to them, do not change. It serializes as {}.

set_content_hash(content_hash: str) → None[source]

Set the content hash for externally referenced files.

Parameters:

content_hash (str) – The content hash value

Returns:

None

Return type:

None

set_session_id(session_id: Dict[str, str] | List[Dict[str, str]]) → None[source]

Set the session identifier for this dialog.

Parameters:

session_id (dict or list) – The session identifier (SessionId or list of SessionId)

Returns:

None

Return type:

None

to_dict()[source]

Returns a dictionary representation of the Dialog object.

Returns:

a dictionary containing all non-None Dialog object attributes

Return type:

dict

to_inline_data() → None[source]

Convert the dialog from an external data dialog to an inline data dialog by reading the contents from the URL then adding the contents to the body.

Returns:

None

Return type:

None

transcode_video(target_format, codec=None, bit_rate=None, width=None, height=None) → None[source]

Transcode the video to a different format or with different encoding parameters.

Parameters:
  • target_format – Target video format (mp4, webm, etc.)

  • codec – Video codec to use (h264, vp9, etc.)

  • bit_rate – Target bitrate in bits per second

  • width – Target width (if resizing)

  • height – Target height (if resizing)

Returns:

None - updates the dialog’s content in place

verify_content_hash(expected_hash: str, algorithm: str | None = None) → bool[source]

Verify the content hash against the expected value.

The algorithm is inferred from the expected_hash prefix ("sha512-" or "sha256-") so values produced by either this or older releases of the library verify correctly. A legacy unprefixed hash is treated as the padded base64url SHA-256 that vcon-lib emitted prior to the algorithm-prefixed format.

Parameters:
  • expected_hash (str) – The expected hash value

  • algorithm (str or None) – Optional explicit algorithm override; when omitted the algorithm is taken from the expected_hash prefix

Returns:

True if the hash matches, False otherwise

Return type:

bool

vcon.dialog.LEGACY_MEDIA_DIALOG_TYPES = ('audio', 'video')

Accepted on input for backward compatibility, normalized to “recording”.

vcon.dialog.b64url_decode(value: str | bytes) → bytes[source]

Base64url-decode value, accepting padded or unpadded input.

base64.urlsafe_b64decode requires exact padding, which rejects the unpadded strings this library (and -04-conformant producers) now emits. This re-pads before decoding so both padded (legacy) and unpadded (spec-conformant) base64url bodies decode correctly.

Parameters:

value (str or bytes) – the base64url string (or bytes) to decode

Returns:

the decoded raw bytes

Return type:

bytes

vcon.dialog.b64url_encode(data: bytes) → str[source]

Base64url-encode data without padding.

draft-ietf-vcon-vcon-core-04 follows the JWS/RFC 7515 base64url convention: no trailing = padding. Use this (instead of calling base64.urlsafe_b64encode directly) whenever the library writes an inline base64url-encoded dialog or attachment body.

Parameters:

data (bytes) – the raw bytes to encode

Returns:

the unpadded base64url-encoded string

Return type:

str

vcon.dialog.compute_content_hash(data: bytes, algorithm: str = 'sha512') → str[source]

Compute a spec-formatted content hash for raw bytes.

Returns "<algorithm>-<base64url-no-padding>" as required by draft-ietf-vcon-vcon-core-02 (e.g. "sha512-GLy6IPa...").

Parameters:
  • data (bytes) – the raw bytes to hash

  • algorithm (str) – the hash algorithm to use (default: "sha512"); "sha256" is also supported for backwards compatibility

Returns:

the algorithm-prefixed, unpadded base64url content hash

Return type:

str

Raises:

ValueError – if algorithm is not a supported algorithm

vcon.dialog.parse_content_hash_algorithm(content_hash: str) → str | None[source]

Return the algorithm prefix of content_hash.

Parameters:

content_hash (str) – a content hash value, optionally prefixed

Returns:

"sha512" or "sha256" for a prefixed value, or None for a legacy unprefixed hash (which this library historically emitted as a padded base64url SHA-256 digest)

Return type:

str or None

vcon.event module

Event Object (draft-ietf-vcon-vcon-core-05, section 4.3) and the events array.

An Event is a point-in-time occurrence inside one or more Sessions: a party joining or dropping, a key press, a call transfer step, or a change of the parties contributing to a recording channel.

The per-type parameter applicability table of section 4.3.1.5 is held in EVENT_PARAMETER_RULES and enforced by validate_event() and by Vcon.is_valid().

Rule codes (section 4.3.1.5):

  • M the parameter MUST be present

  • O the parameter is optional

  • SN the parameter SHOULD NOT be present (reported as a warning)

  • X the parameter MUST NOT be present

vcon.event.CORE_EVENT_TYPES = ('join', 'drop', 'hold', 'unhold', 'mute', 'unmute', 'keydown', 'keyup', 'consultation-start', 'blind-transfer', 'consultative-transfer', 'transfer-abandoned', 'channel-contributors')

Every Event type token defined by core-05 (section 4.3.1).

vcon.event.EVENT_PARAMETERS = ('type', 'time', 'sessions', 'party', 'dialog', 'channel', 'contributors', 'button', 'transferee', 'transfer_target', 'consultation', 'target_session')

Event parameters other than type and time, in the order of 4.3.

vcon.event.EVENT_PARAMETER_RULES: Dict[str, Dict[str, str]] = {'blind-transfer': {'button': 'X', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'M', 'time': 'M', 'transfer_target': 'M', 'transferee': 'M', 'type': 'M'}, 'channel-contributors': {'button': 'X', 'channel': 'M', 'consultation': 'X', 'contributors': 'O', 'dialog': 'M', 'party': 'X', 'sessions': 'X', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}, 'consultation-start': {'button': 'X', 'channel': 'X', 'consultation': 'M', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'M', 'transferee': 'M', 'type': 'M'}, 'consultative-transfer': {'button': 'X', 'channel': 'X', 'consultation': 'M', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'M', 'time': 'M', 'transfer_target': 'M', 'transferee': 'M', 'type': 'M'}, 'drop': {'button': 'X', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}, 'hold': {'button': 'X', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}, 'join': {'button': 'X', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}, 'keydown': {'button': 'M', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}, 'keyup': {'button': 'M', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}, 'mute': {'button': 'X', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}, 'transfer-abandoned': {'button': 'X', 'channel': 'X', 'consultation': 'O', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'O', 'transferee': 'M', 'type': 'M'}, 'unhold': {'button': 'X', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}, 'unmute': {'button': 'X', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}}

Parameter applicability by Event type (section 4.3.1.5 tables).

class vcon.event.Event(type: str, time: datetime | str, sessions: int | List[int] | None = None, party: int | None = None, dialog: int | List[int] | None = None, channel: int | None = None, contributors: int | List[int] | None = None, button: str | None = None, transferee: int | None = None, transfer_target: int | None = None, consultation: int | None = None, target_session: int | None = None, validate: bool = True, **extra: Any)[source]

Bases: object

An Event Object (core-05 section 4.3).

Parameters:
  • type – Event type token, for example "join" or "blind-transfer".

  • time – When the event occurred (datetime or ISO 8601 string).

  • sessions – Session index or list of indices (not for channel-contributors).

  • party – Party index (not for channel-contributors).

  • dialog – Dialog index (channel-contributors; SHOULD NOT be used otherwise).

  • channel – Channel index (channel-contributors only).

  • contributors – Party index, list of indices, or None (channel-contributors only).

  • button – DTMF digit or key label (keydown and keyup only).

  • transferee – Party indices (transfer types).

  • transfer_target – Party indices (transfer types).

  • consultation – Session indices (transfer types).

  • target_session – Session indices (transfer types).

  • validate – Apply the parameter applicability table and raise ValueError on an M/X violation (default True).

  • **extra – Parameters defined by a vCon extension.

classmethod from_dict(data: Dict[str, Any], validate: bool = False) → Event[source]
to_dict() → Dict[str, Any][source]

Serialize, omitting parameters that are None.

vcon.event.validate_event(event: Any, *, party_count: int | None = None, dialog_count: int | None = None, session_count: int | None = None, label: str = 'Event') → Tuple[List[str], List[str]][source]

Validate one Event Object dict against core-05 section 4.3.

Returns (errors, warnings). SN violations are warnings, M and X violations are errors. An Event whose type is not a core token is only checked for type and time (section 2.5: it belongs to an extension). Index values are range-checked only when the matching count is supplied.

vcon.migration module

Migrate a vCon from syntax 0.4.0 to 0.5.0 (draft-ietf-vcon-vcon-core-05, Appendix A.1).

The migration is table driven. MIGRATION_STEPS holds one MigrationStep per step T1..T15 of the ordered transform table; each step is one function that mutates a shared _Context. If a later edit of Appendix A.1 changes one step, only that function (or its table entry) needs to change.

Execution order (the draft gives none; this order is inferred so that every dialog index stays valid): the steps that read the 0.4.0 dialog array run before any array is rewritten, and T10 blanks the removed Dialogs in place at the end, so the array length and every other index are unchanged.

T13 T15 T1 -> T8 T9 T9b T6 -> T2 T7 T4(+T5) T3 -> T10 T10b T10c -> T11 T12 T14

T4 runs before T3 so that the Sessions T5 creates for a transfer’s original, consultation and target calls are known when T3 builds the party_history Events: an Event lists every Session of the Dialog it came from (AMB-3).

Nothing is invented silently. Every value the draft does not dictate is listed in the MigrationReport (kind inferred), every field that had to be filled by a fallback is listed (kind fallback), and every problem the migration could not resolve is listed (kind unresolved). In strict mode a fallback raises MigrationError instead.

A signed 0.4.0 vCon is migrated as the unsigned payload. The migration never signs; the report sets resign_required.

vcon.migration.FALLBACK = 'fallback'

A MUST field with no source was filled with the documented fallback.

vcon.migration.INFERRED = 'inferred'

A value the draft does not dictate; a documented default was applied.

vcon.migration.INFO = 'info'

Informational.

vcon.migration.MIGRATION_STEPS: List[MigrationStep] = [MigrationStep(id='T13', title='Signed input: migrate the payload, require re-signing', source='A.1 bullet 11; 6.2.2', func=<function _step_t13_unwrap_signed>), MigrationStep(id='T15', title='Duplicate header parameters tolerated on read', source='A.1 bullet 13', func=<function _step_t15_duplicate_headers>), MigrationStep(id='T1', title='vcon 0.4.0 -> 0.5.0', source='A.1 bullet 1', func=<function _step_t1_version>), MigrationStep(id='T8', title='text Dialog parties -> sender; all parties to Session', source='A.1 bullet 6', func=<function _step_t8_text_parties>), MigrationStep(id='T9', title='incomplete Dialog parties -> originator/first', source='A.1 bullet 6', func=<function _step_t9_incomplete_parties>), MigrationStep(id='T9b', title='other Dialog parties kept; union to Session', source='4.5.4 (A.1 silent)', func=<function _step_t9b_recording_parties>), MigrationStep(id='T6', title='Dialog originator -> Session originator', source='A.1 bullet 5', func=<function _step_t6_originator>), MigrationStep(id='T2', title='Add a Session referencing all Dialogs', source='A.1 bullet 2', func=<function _step_t2_sessions>), MigrationStep(id='T7', title='recording-set Dialog -> Session', source='A.1 bullet 9', func=<function _step_t7_recording_sets>), MigrationStep(id='T4', title='transfer Dialog -> transfer Events (with T5 Session references)', source='A.1 bullet 4', func=<function _step_t4_transfers>), MigrationStep(id='T3', title='party_history -> Events', source='A.1 bullet 3', func=<function _step_t3_party_history>), MigrationStep(id='T10', title='Removed Dialogs -> {} in place', source='A.1 bullet 10; 4.5.1', func=<function _step_t10_blank_removed>), MigrationStep(id='T10b', title='Re-point analysis/attachment references to removed Dialogs', source='AMB-2', func=<function _step_t10b_retarget>), MigrationStep(id='T10c', title='Scope unscoped attachments to the only Session', source='4.6.4 (A.1 silent)', func=<function _step_t10c_unscoped_attachments>), MigrationStep(id='T11', title='redacted -> redacted_from', source='A.1 bullet 7', func=<function _step_t11>), MigrationStep(id='T12', title='amended -> amended_from', source='A.1 bullet 8', func=<function _step_t12>), MigrationStep(id='T14', title='extensions lists every extension in use', source='A.1 bullet 12; 4.1.3', func=<function _step_t14_extensions>)]

One entry per step of the ordered transform table (Appendix A.1), in execution order.

exception vcon.migration.MigrationError[source]

Bases: ValueError

The vCon cannot be migrated (or, in strict mode, a MUST field has no source).

class vcon.migration.MigrationReport(source_version: str | None = None, target_version: str = '0.5.0', strict: bool = False, resign_required: bool = False, entries: ~typing.List[~vcon.migration.ReportEntry] = <factory>, removed_dialogs: ~typing.Dict[int, ~typing.Dict[str, ~typing.Any]] = <factory>, steps_run: ~typing.List[str] = <factory>)[source]

Bases: object

What a migration did that the draft did not dictate.

add(step: str, kind: str, message: str, code: str | None = None, **details: Any) → None[source]
entries: List[ReportEntry]
property fallbacks: List[ReportEntry]
property inferred: List[ReportEntry]
property notes: List[ReportEntry]
removed_dialogs: Dict[int, Dict[str, Any]]

Original content of every Dialog replaced by {}, keyed by its (unchanged) index.

resign_required: bool = False

the signature is dropped and the result is unsigned.

Type:

True when the input was signed

source_version: str | None = None
steps_run: List[str]

Steps that ran, in order.

strict: bool = False
summary() → str[source]
target_version: str = '0.5.0'
to_dict() → Dict[str, Any][source]
property unresolved: List[ReportEntry]
class vcon.migration.MigrationResult(vcon: Dict[str, Any], report: MigrationReport)[source]

Bases: NamedTuple

Result of a migration. Unpacks as (vcon, report).

report: MigrationReport

Alias for field number 1

vcon: Dict[str, Any]

Alias for field number 0

class vcon.migration.MigrationStep(id: 'str', title: 'str', source: 'str', func: 'Callable[[_Context], None]')[source]

Bases: object

func: Callable[[_Context], None]
id: str
source: str
title: str
class vcon.migration.ReportEntry(step: 'str', kind: 'str', message: 'str', code: 'Optional[str]' = None, details: 'Dict[str, Any]' = <factory>)[source]

Bases: object

code: str | None = None
details: Dict[str, Any]
kind: str
message: str
step: str
to_dict() → Dict[str, Any][source]
vcon.migration.UNRESOLVED = 'unresolved'

A problem left for a person to resolve.

vcon.migration.migrate_0_4_0_to_0_5_0(vcon: Any, *, strict: bool = False) → MigrationResult[source]

Migrate a 0.4.0 vCon dict (or JSON string) to 0.5.0.

Parameters:
  • vcon – The 0.4.0 vCon as a dict or JSON string. A signed vCon (JWS general form) is migrated as its unsigned payload. The input is not modified.

  • strict – When True, raise MigrationError instead of using a fallback for a MUST field that cannot be sourced from the input.

Returns:

the 0.5.0 dict and the MigrationReport listing every inferred value, fallback and unresolved item.

Return type:

MigrationResult(vcon, report)

Raises:

MigrationError – the input is not a 0.4.0 vCon, is encrypted, or (strict) a required field has no source.

vcon.party module

class vcon.party.Party(tel: str | None = None, stir: str | None = None, mailto: str | None = None, name: str | None = None, validation: str | None = None, gmlpos: str | None = None, civicaddress: CivicAddress | None = None, uuid: str | None = None, role: str | None = None, contact_list: str | None = None, meta: dict | None = None, sip: str | None = None, did: str | None = None, jCard: dict | None = None, timezone: str | None = None, **kwargs)[source]

Bases: object

A class representing a party (participant) in a vCon conversation.

A party represents a participant in the conversation with various contact and identification information. Parties can be callers, agents, or any other participants in the conversation.

Supported contact methods: - tel: Telephone number - mailto: Email address - sip: SIP URI for VoIP communication - did: Decentralized Identifier for blockchain-based identity

Contact information: - name: Display name of the party - jCard: vCard format contact information (RFC 7095) - timezone: Party’s timezone for temporal context

Location and validation: - civicaddress: Civic address information (GEOPRIV format) - gmlpos: GML position coordinates - validation: Validation information for the party

Additional metadata: - uuid: Unique identifier for the party - role: Role in the conversation (e.g., “caller”, “agent”) - stir: STIR identifier for secure telephony - contact_list: Reference to contact list - meta: Additional metadata

New in vCon 0.4.0: - sip: SIP URI for the party - did: Decentralized Identifier - jCard: vCard format contact information - timezone: Party’s timezone

__init__(tel: str | None = None, stir: str | None = None, mailto: str | None = None, name: str | None = None, validation: str | None = None, gmlpos: str | None = None, civicaddress: CivicAddress | None = None, uuid: str | None = None, role: str | None = None, contact_list: str | None = None, meta: dict | None = None, sip: str | None = None, did: str | None = None, jCard: dict | None = None, timezone: str | None = None, **kwargs) → None[source]

Initialize a new Party object.

Parameters:
  • tel (str | None) – Telephone number of the party

  • stir (str | None) – STIR identifier of the party

  • mailto (str | None) – Email address of the party

  • name (str | None) – Display name of the party

  • validation (str | None) – Validation information of the party

  • gmlpos (str | None) – GML position of the party

  • civicaddress (CivicAddress | None) – Civic address of the party

  • uuid (str | None) – UUID of the party

  • role (str | None) – Role of the party

  • contact_list (str | None) – Contact list of the party

  • sip (str | None) – SIP URI for the party

  • did (str | None) – Decentralized Identifier

  • jCard (dict | None) – vCard format contact information

  • timezone (str | None) – Party’s timezone

  • kwargs – Additional attributes to be set on the party

to_dict()[source]
class vcon.party.PartyHistory(party: int, event: str, time: datetime | str, button: str | None = None)[source]

Bases: object

Deprecated 0.4.0 Party_History Object, kept so old imports keep working.

core-05 replaced Dialog party_history with Event Objects. Build an Event directly, or convert with to_event(), which needs the Session index (or indices) the event belongs to. A PartyHistory can no longer be attached to a Dialog.

VALID_EVENTS = ['join', 'drop', 'hold', 'unhold', 'mute', 'unmute', 'keydown', 'keyup']
to_dict() → Dict[str, Any][source]

The 0.4.0 shape (event, not type).

to_event(sessions: int | List[int])[source]

The equivalent core-05 Event (event renamed type, no dialog).

vcon.session module

Session Object and Session_Reference Object (core-05 sections 4.2 and 4.2.8).

A Session groups the Dialog and Event Objects of one conversation (or part of one) and records its receivers. A Session Object with no parameters is allowed.

vcon.session.SESSION_REFERENCE_TYPES = ('child', 'peer', 'precursor', 'breakout')

Session_Reference type tokens defined by core-05 (4.2.8.2). Values defined by a vCon extension are also allowed.

class vcon.session.Session(start: str | datetime | None = None, duration: int | float | None = None, parties: List[int] | None = None, originator: int | None = None, session_id: Dict[str, str] | None = None, sessions: List[SessionReference | Dict[str, Any]] | None = None, dialog: List[int] | None = None)[source]

Bases: object

A Session Object.

Parameters:
  • start – Session start (datetime or ISO 8601 string). SHOULD be present.

  • duration – Session duration in seconds. Absent means the session has no end.

  • parties – Indices of the receivers. The first one is the implied originator.

  • originator – Index of the originator, only when it is not the first party.

  • session_id – A SessionId Object ({"local": ..., "remote": ...}).

  • sessions – Relationships to other Sessions (SessionReference or dicts).

  • dialog – Indices of the Dialog Objects that are part of the session.

to_dict() → Dict[str, Any][source]

Serialize, omitting parameters that are None. An empty Session is {}.

class vcon.session.SessionReference(session: int, type: str, description: str | None = None)[source]

Bases: object

Session_Reference Object: how another Session relates to this one.

to_dict() → Dict[str, Any][source]
vcon.session.validate_session(session: Any, *, party_count: int | None = None, dialog_count: int | None = None, session_count: int | None = None, label: str = 'Session') → Tuple[List[str], List[str]][source]

Validate one Session Object dict. Returns (errors, warnings).

vcon.validation module

Structural validation of an unsigned vCon dict against core-05.

validate_vcon_dict is the engine behind Vcon.is_valid(). It works on plain dicts so the migration code can reuse it.

vcon.validation.KNOWN_ATTACHMENT_PURPOSE_EXTENSIONS = {'lawful_basis': 'lawful_basis', 'wtf_transcription': 'wtf_transcription'}

Extension names this library knows how to recognise, keyed by how they show up.

vcon.validation.LEGACY_TOP_LEVEL = {'amended': 'amended_from', 'redacted': 'redacted_from'}

Removed in 0.5.0; their presence means the document is still 0.4.0 shaped.

vcon.validation.LIBRARY_DIALOG_TYPES = ('audio', 'video')

Dialog types older versions of this library wrote although core-05 does not define them. Accepted on read with a warning; the library never writes them.

vcon.validation.content_hash_problems(value: Any) → List[str][source]

Return why value is not a ContentHash or ContentHash[] (empty if it is).

vcon.validation.encrypted_form(vcon: Any) → bool[source]

True for a JWE General JSON Serialization container (section 6.3).

vcon.validation.extensions_in_use(vcon: Dict[str, Any]) → Tuple[Set[str], List[str]][source]

Find the vCon extensions the document uses.

Returns (names, unnamed). names holds extension names this library recognises (lawful_basis, wtf_transcription). unnamed describes each use of a value outside the core vocabulary (an Event type, Dialog type, encoding, disposition or Session_Reference type) whose defining extension cannot be identified from the document alone.

vcon.validation.mediatype_ok(mediatype: Any, known: List[str]) → bool[source]

True if mediatype is acceptable for a Dialog.

Media type parameters (; boundary=...) are ignored. Any multipart/, message/ or text/ subtype is accepted, since the draft’s examples use multipart/alternative and the list in the draft is open-ended.

vcon.validation.signed_form(vcon: Any) → bool[source]

True for a JWS General JSON Serialization container (section 6.2).

vcon.validation.signed_payload(vcon: Dict[str, Any]) → Any[source]

The decoded JWS payload of a signed vCon, or None if it is not base64url JSON.

vcon.validation.validate_vcon_dict(vcon: Dict[str, Any], dialog_mime_types: List[str]) → Tuple[List[str], List[str]][source]

Validate a vCon dict. Returns (errors, warnings).

A signed (JWS) vCon is checked as a JWS and its payload as a vCon; an encrypted (JWE) vCon is checked as a JWE only.

vcon.vcon module

exception vcon.vcon.AlgorithmNotPermittedError[source]

Bases: ValueError

A JWS used alg “none” (forbidden by core-05) or an unsupported algorithm.

class vcon.vcon.Attachment(purpose: str, body: Any = None, encoding: str = 'none', mediatype: str | None = None, filename: str | None = None, url: str | None = None, content_hash: str | None = None, start: str | None = None, party: int | None = None, dialog: int | None = None, session: int | List[int] | None = None)[source]

Bases: object

A class representing an attachment in a vCon.

An attachment consists of a purpose, body content, and an encoding format. The encoding format must be one of the supported formats: base64url, json, or none.

purpose

The purpose of the attachment

Type:

str

body

The content of the attachment

Type:

Any

encoding

The encoding format used for the body

Type:

str

VALID_ENCODINGS = ['base64url', 'json', 'none']
__init__(purpose: str, body: Any = None, encoding: str = 'none', mediatype: str | None = None, filename: str | None = None, url: str | None = None, content_hash: str | None = None, start: str | None = None, party: int | None = None, dialog: int | None = None, session: int | List[int] | None = None) → None[source]

Initialize an Attachment object.

Under core-05 (section 4.6) an attachment needs party and at least one of dialog or session. party defaults to 0. Neither dialog nor session is defaulted here, because the right index depends on the vCon; Vcon.add_attachment() defaults it only when the vCon has exactly one Session.

Parameters:
  • purpose – The purpose of the attachment

  • body – The content of the attachment

  • encoding – The encoding format used for the body (default: “none”)

Raises:

ValueError – If the specified encoding is not supported

classmethod from_image(image_path: str, purpose: str = 'image') → Attachment[source]

Create an Attachment from an image file.

Parameters:
  • image_path – Path to the image file

  • type – The type of the attachment (default: “image”)

Returns:

An Attachment object containing the image

Raises:
  • ValueError – If the image format is not supported

  • FileNotFoundError – If the image file cannot be found

to_dict() → Dict[str, Any][source]

Convert the attachment to a dictionary representation.

Returns:

Dict containing the attachment’s purpose, body, and encoding

vcon.vcon.PERMITTED_JWS_ALGORITHMS = ('RS256', 'RS384', 'RS512', 'PS256', 'PS384', 'PS512', 'ES256', 'ES384', 'ES512', 'EdDSA')

JWS algorithms accepted for signing and verifying. “none” is excluded: core-05 section 6.2.2, “The alg parameter MUST NOT have the value none”.

class vcon.vcon.Vcon(vcon_dict: Dict[str, Any] = None, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False)[source]

Bases: object

A class representing a vCon (Virtual Conversation) object according to the vCon specification.

A vCon is a standardized format for representing conversations and related metadata. It includes information about participants (parties), dialog content, attachments, and analysis data.

The vCon format supports features such as:

  • Unique identification via UUID

  • The vcon syntax version (written as "0.5.0")

  • Timestamps for creation and updates

  • Party information with contact details (tel, name, sip, did, jCard, timezone)

  • Dialog content with media types and session information

  • Attachments for ancillary documents

  • Analysis data for conversation insights

  • Digital signatures and encryption

  • Extensions and critical for extensibility

  • Civic address information for location data

  • Sessions (sessions) grouping dialog and events, and Events (events) for joins, drops, holds, key presses and transfers

New in vCon 0.5.0 (draft-ietf-vcon-vcon-core-05):

  • sessions and events arrays; Session and Event classes

  • redacted_from and amended_from replace redacted and amended

  • Attachments need party and dialog or session

  • extensions MUST list every extension in use; alg: "none" is rejected

  • Dialog parties are contributors only; empty {} Dialog placeholders

  • 0.4.0 input is migrated on load (see migrate_0_4_0_to_0_5_0)

vcon_dict

The underlying dictionary containing all vCon data

Type:

Dict

property_handling

How non-standard properties are handled

Type:

str

WTF_SCHEMA_URL = 'https://datatracker.ietf.org/doc/html/draft-howe-vcon-wtf-extension'
__init__(vcon_dict: Dict[str, Any] = None, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) → None[source]

Initialize a Vcon object from a dictionary.

A dict that declares "vcon": "0.4.0" is migrated to 0.5.0 here, using migrate_0_4_0_to_0_5_0. The report is kept in self.migration_report. A signed vCon whose payload is 0.4.0 is NOT migrated on load, because migrating drops the signature: verify it, then call Vcon.migrate_0_4_0_to_0_5_0(). An unmigrated 0.4.0 dict (signed, or migrate_legacy=False) is kept as is; property_handling is not applied to it. A dict with any other (or no) vcon value is taken as is.

Parameters:
  • vcon_dict – A dictionary representing a vCon. Defaults to an empty dict.

  • property_handling – How to handle non-standard properties. Options are: - “default”: Keep non-standard properties (default) - “strict”: Remove non-standard properties - “meta”: Move non-standard properties to meta object

  • migrate_legacy – Migrate 0.4.0 input to 0.5.0 (default True). When False the 0.4.0 dict is kept untouched and is_valid() will report it as not 0.5.0.

  • strict_migration – Passed to the migration as strict; raises MigrationError when a required field has no source.

Example

>>> vcon = Vcon({"uuid": "123", "custom_field": "value"})
>>> strict_vcon = Vcon({"uuid": "123", "custom_field": "value"}, property_handling="strict")
>>> meta_vcon = Vcon({"uuid": "123", "custom_field": "value"}, property_handling="meta")
add_analysis(*, type: str, vendor: str, body: Dict[str, Any] | List[Any] | str, dialog: int | List[int] | None = None, sessions: int | List[int] | None = None, attachment: int | List[int] | None = None, analysis: int | List[int] | None = None, encoding: str = 'none', mediatype: str | None = None, filename: str | None = None, product: str | None = None, url: str | None = None, content_hash: str | None = None, schema: Dict[str, Any] | None = None, meta: Dict[str, Any] | None = None, **extra) → None[source]

Add analysis data to the vCon.

This method adds analysis data with the specified parameters to the vCon’s analysis list. Analysis data can be associated with one or more dialog entries and includes metadata about the vendor who performed the analysis.

Parameters:
  • type – The type of analysis

  • dialog – Index or list of indices of the associated dialog entries (optional)

  • sessions – Index or list of indices of the Sessions analysed (optional)

  • attachment – Index or list of indices of the attachments analysed (optional)

  • analysis – Index or list of indices of other Analysis Objects used (optional)

  • vendor – The name of the vendor who performed the analysis

  • body – The analysis data

  • encoding – The encoding format of the body (default: “none”)

  • mediatype – Optional media type of the analysis content

  • filename – Optional filename for the analysis content

  • product – Optional product name of the vendor

  • url – Optional URL for external analysis content

  • content_hash – Optional content hash for external analysis content

  • schema – Optional schema information about the analysis (default: None)

  • meta – Optional metadata about the analysis (default: None)

  • **extra – Additional key-value pairs to include in the analysis

Raises:

Exception – If the encoding is invalid or if the body format is invalid for the specified encoding

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_analysis(
...     type="sentiment",
...     dialog=[0],
...     vendor="acme",
...     body={"score": 0.8},
...     encoding="json",
...     schema={"version": "1.0"},
...     meta={"confidence": "high"}
... )
add_attachment(purpose: str, body: Any = None, encoding: str = 'none', mediatype: str | None = None, filename: str | None = None, url: str | None = None, content_hash: str | None = None, start: str | None = None, party: int | None = None, dialog: int | None = None, session: int | List[int] | None = None) → Attachment[source]

Add an attachment to the vCon.

This method creates a new attachment with the specified type, body, and encoding and adds it to the vCon’s attachments list.

Core-05 needs party plus dialog or session. party defaults to 0. If neither dialog nor session is given, the attachment is scoped to the only Session when the vCon has exactly one; otherwise ValueError is raised rather than inventing a scope.

Parameters:
  • purpose – The purpose of the attachment

  • body – The content of the attachment

  • encoding – The encoding format for the body (default: “none”)

  • mediatype – Optional media type of the attachment

  • filename – Optional file name of the attachment

  • url – Optional URL for external attachments

  • content_hash – Optional content hash for external attachments

  • start – Optional timestamp for the attachment

  • party – Optional party index (default 0)

  • dialog – Optional dialog index

  • session – Optional Session index or list of indices

Returns:

The created Attachment object

Raises:

ValueError – If the specified encoding is not supported

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Alice"))
>>> vcon.add_session()
>>> attachment = vcon.add_attachment("metadata", {"version": "1.0"}, "json")
>>> print(attachment.purpose)  # Prints "metadata"
add_critical(extension: str) → None[source]

Add an extension to the critical list.

Parameters:

extension – The name of the extension that must be supported

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_critical("encryption")
>>> vcon.add_critical("video")
add_dialog(dialog: Dialog, session: int | None = None) → int[source]

Add a dialog entry to the vCon.

This method adds a Dialog object to the vCon’s dialog list. A dialog entry represents a segment of the conversation with its associated metadata. Use Dialog.placeholder() to add an empty Dialog Object ({}) that holds an array position.

Parameters:
  • dialog – The Dialog object to add

  • session – Optional index of an existing Session; the new Dialog’s index is appended to that Session’s dialog list. Core-05 requires at least one Session when the vCon has Dialogs, so add Sessions with add_session().

Returns:

The index of the new Dialog in the dialog array.

Example

>>> vcon = Vcon.build_new()
>>> dialog = Dialog(type="text", start="2023-01-01T00:00:00Z", parties=[0])
>>> index = vcon.add_dialog(dialog)
add_event(event: Event | Dict[str, Any]) → int[source]

Add an Event Object and return its index in the events array.

An Event is checked against the per-type parameter table when it is built; a plain dict is checked by is_valid().

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_event(Event(type="join", time="2023-01-01T00:00:00Z", sessions=0, party=0))
add_extension(extension: str) → None[source]

Add an extension to the vCon.

Parameters:

extension – The name of the extension to add

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_extension("video")
>>> vcon.add_extension("encryption")
add_image(image_path: str, purpose: str = 'image', party: int | None = None, dialog: int | None = None, session: int | List[int] | None = None) → Attachment[source]

Add an image attachment to the vCon.

This method creates a new attachment with the specified image and adds it to the vCon’s attachments list.

Parameters:
  • image_path – Path to the image file

  • purpose – The purpose of the attachment (default: “image”)

  • party – Party index (default 0)

  • dialog – Dialog index

  • session – Session index or list of indices. With neither dialog nor session, the only Session is used when the vCon has exactly one, as in add_attachment().

Returns:

The created Attachment object

Raises:
  • FileNotFoundError – If the image file cannot be found

  • ValueError – If the image format is not supported, or no dialog/session is given and the vCon does not have exactly one Session

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_session()
>>> attachment = vcon.add_image("document.pdf", "identification")
>>> print(attachment.mediatype)  # Prints "application/pdf"
add_incomplete_dialog(start: str | datetime, disposition: str, details: Dict[str, Any] | None = None, parties: List[int] = None, metadata: Dict[str, Any] | None = None, session: int | None = None) → int[source]

Add an incomplete dialog entry to the vCon.

This method creates a dialog entry of type “incomplete” for conversations that failed to be set up. Under core-05 an incomplete Dialog has no content (no body, mediatype, filename, encoding, url or content_hash), and its parties is the party that attempted the call, the originator. details is kept under metadata["details"].

Parameters:
  • start – When the attempt occurred (ISO 8601 string or datetime)

  • disposition – Reason for the incomplete conversation (for example “no-answer”)

  • details – Additional details about the failure (optional)

  • parties – The party (or parties) that attempted the conversation (optional)

  • metadata – Additional metadata (optional)

  • session – Optional Session index to add the Dialog to

Returns:

The index of the new Dialog.

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_incomplete_dialog(
...     start="2023-01-20T14:00:00Z",
...     disposition="no-answer",
...     details={"ringDuration": 45000},
...     parties=[0]
... )
add_lawful_basis_attachment(lawful_basis: str, expiration: str, purpose_grants: list, party_index: int | None = None, dialog_index: int | None = None, session_index: int | List[int] | None = None, **kwargs) → None[source]

Add a lawful basis attachment to the vCon.

The attachment has purpose "lawful_basis". Under core-05 it is scoped with party plus session: pass session_index (and party_index, the party that records the basis). The scope is never widened or invented: dialog_index alone gives a dialog-only scope (a warning is logged, because 0.5.0 scopes a basis to Sessions), and with neither index the only Session is used when the vCon has exactly one; otherwise ValueError is raised. party defaults to 0 with a warning. The lawful_basis extension name is added to extensions.

Parameters:
  • lawful_basis – The lawful basis type (consent, contract, etc.)

  • expiration – ISO 8601 timestamp when the lawful basis expires

  • purpose_grants – List of purpose grant dictionaries

  • party_index – Index of the party that records the basis (default 0)

  • dialog_index – Index of the dialog this applies to (optional)

  • session_index – Session index or list of indices this applies to (optional)

  • **kwargs – Additional lawful basis parameters

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Alice"))
>>> vcon.add_session()
>>> vcon.add_lawful_basis_attachment(
...     lawful_basis="consent",
...     expiration="2026-01-01T00:00:00Z",
...     purpose_grants=[
...         {"purpose": "recording", "granted": True, "granted_at": "2025-01-01T00:00:00Z"}
...     ]
... )
add_party(party: Party) → None[source]

Add a party to the vCon.

This method adds a party object to the vCon’s parties list. A party represents a participant in the conversation.

Parameters:

party – The Party object to add

Example

>>> vcon = Vcon.build_new()
>>> party = Party(type="person", name="John Doe")
>>> vcon.add_party(party)
add_session(session: Session | Dict[str, Any] | None = None) → int[source]

Add a Session Object and return its index in the sessions array.

With no argument an empty placeholder Session ({}) is added, which core-05 permits.

Example

>>> vcon = Vcon.build_new()
>>> s = vcon.add_session(Session(start="2023-01-01T00:00:00Z", parties=[0, 1]))
add_tag(tag_name: str, tag_value: str, party: int | None = None) → None[source]

Add a tag to the vCon.

This method adds a tag with the specified name and value to the vCon’s tags attachment. If no tags attachment exists, it creates one.

Core-05 requires the attachment’s party to be a valid party index (the party that adds the tags). It defaults to 0. On a vCon with no parties this still writes party 0 but warns (DeprecationWarning), because the result fails is_valid(); from vcon 1.1 it will raise.

Parameters:
  • tag_name – The name of the tag

  • tag_value – The value to associate with the tag

  • party – Party index for a new tags attachment (default 0)

Raises:

ValueError – If party is given (or the vCon has parties) and it is not a valid party index

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Acme Corp"))
>>> vcon.add_tag("category", "meeting")
>>> vcon.add_tag("priority", "high")
add_transfer_dialog(*args: Any, **kwargs: Any) → None[source]

Removed: core-05 has no transfer Dialog type.

Raises NotImplementedError with the replacement: a transfer is one or two transfer Events (blind-transfer, consultation-start plus consultative-transfer, or transfer-abandoned) added with add_event(Event(...)), whose sessions/consultation/ target_session reference Sessions for the calls involved.

add_wtf_transcription_analysis(transcript: Dict[str, Any], segments: List[Dict[str, Any]], metadata: Dict[str, Any], dialog_index: int | None = None, session_index: int | List[int] | None = None, **kwargs) → None[source]

Add a WTF transcription as an analysis entry (vs. an attachment).

This is the placement draft-howe-vcon-wtf-extension requires (section 6.1: transcription results MUST be stored as analysis). add_wtf_transcription_attachment writes to attachments[] and is deprecated.

Emits the analysis entry defined by draft-howe-vcon-wtf-extension (section 5.3): type="wtf_transcription", vendor and product taken from metadata["provider"] / metadata["model"], schema set to the WTF draft URL, encoding="json", and body as the WTF document itself (a JSON value, not a serialized string).

Parameters:
  • transcript – Transcript information dictionary

  • segments – List of segment dictionaries

  • metadata – Metadata dictionary; provider and model keys map to vendor and product on the analysis entry

  • dialog_index – Index of the dialog this transcription applies to

  • session_index – Session index or indices this transcription applies to

  • **kwargs – Additional WTF parameters (words, speakers, quality, etc.)

add_wtf_transcription_attachment(transcript: Dict[str, Any], segments: List[Dict[str, Any]], metadata: Dict[str, Any], party_index: int | None = None, dialog_index: int | None = None, session_index: int | List[int] | None = None, **kwargs) → None[source]

Add a WTF transcription attachment to the vCon.

Deprecated: draft-howe-vcon-wtf-extension stores transcriptions as analysis (section 6.1). Use add_wtf_transcription_analysis().

Scoped by dialog_index and/or session_index as given; with neither, the only Session when the vCon has exactly one, else ValueError (see add_attachment).

Parameters:
  • transcript – Transcript information dictionary

  • segments – List of segment dictionaries

  • metadata – Metadata dictionary

  • party_index – Index of the party this applies to (optional)

  • dialog_index – Index of the dialog this applies to (optional)

  • session_index – Session index or list of indices (optional)

  • **kwargs – Additional WTF parameters

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Alice"))
>>> vcon.add_session()
>>> vcon.add_wtf_transcription_attachment(
...     transcript={"text": "Hello world", "language": "en", "duration": 2.0, "confidence": 0.95},
...     segments=[{"id": 0, "start": 0.0, "end": 2.0, "text": "Hello world", "confidence": 0.95}],
...     metadata={"created_at": "2025-01-01T00:00:00Z", "processed_at": "2025-01-01T00:00:01Z",
...              "provider": "whisper", "model": "whisper-1"}
... )
property amended

Deprecated 0.4.0 name; returns amended_from.

property amended_from
property analysis: List[Dict[str, Any]]

Get the list of analysis entries in the vCon.

Returns:

A list of analysis dictionaries

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_analysis(type="sentiment", dialog=[0], vendor="acme", body={"score": 0.8})
>>> analysis = vcon.analysis
>>> print(analysis[0]["type"])  # Prints "sentiment"
property attachments: List[Dict[str, Any]]

Get the list of attachments in the vCon.

Returns:

A list of attachment dictionaries

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Alice"))
>>> vcon.add_session()
>>> vcon.add_attachment("metadata", {"version": "1.0"})
>>> attachments = vcon.attachments
>>> print(attachments[0]["purpose"])  # Prints "metadata"
classmethod build_from_json(json_string: str, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) → Vcon[source]

Initialize a Vcon object from a JSON string.

This method parses a JSON string representation of a vCon and creates a new Vcon object from it.

Parameters:
  • json_string – A JSON string representing a vCon

  • property_handling – How to handle non-standard properties.

Returns:

A new Vcon object initialized with the parsed JSON data

Raises:

json.JSONDecodeError – If the JSON string is invalid

Example

>>> json_str = '{"uuid": "123"}'
>>> vcon = Vcon.build_from_json(json_str)
classmethod build_new(created_at: str | datetime = None, property_handling: str = 'default') → Vcon[source]

Initialize a new Vcon object with default values.

This method creates a new vCon with a generated UUID and initialized with empty arrays for groups, parties, dialog, attachments, and analysis.

Parameters:
  • created_at (Union[str, datetime], optional) – The timestamp to set for creation, either as a string in ISO format or as a datetime object. Defaults to current time.

  • property_handling – How to handle non-standard properties.

Returns:

A new Vcon object with default values

Example

>>> vcon = Vcon.build_new()
>>> print(vcon.uuid)  # Prints a new UUID8
check_lawful_basis_permission(purpose: str, party_index: int | None = None) → bool[source]

Check if permission is granted for a specific purpose.

Parameters:
  • purpose – The purpose to check permission for

  • party_index – Index of the party to check (optional)

Returns:

True if permission is granted, False otherwise

property created_at
static decoded_body(entry: Dict[str, Any] | None) → Any[source]

Return the decoded body of an attachment, analysis, or dialog entry.

Under draft-ietf-vcon-vcon-core-04, a "json"-encoded body is the JSON value itself, not a json.dumps string. This accepts both that shape and the JSON-string bodies written under -02 conventions (or by this library prior to 0.10.0), so callers don’t need to special-case legacy vCons.

Parameters:

entry – An attachment, analysis, or dialog dictionary

Returns:

The decoded body, or None if there is no body

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Alice"))
>>> vcon.add_session()
>>> vcon.add_tag("category", "meeting")
>>> Vcon.decoded_body(vcon.tags)  # ["category:meeting"]
property dialog: List[Dict[str, Any]]

Get the list of dialog entries in the vCon.

Returns:

A list of dialog dictionaries representing the conversation content. These are mutable references to the internal data structure, allowing in-place modifications.

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_dialog(Dialog(type="text", start="2023-01-01T00:00:00Z", parties=[0]))
>>> dialog = vcon.dialog
>>> print(dialog[0]["type"])  # Prints "text"
>>> dialog[0]["body"] = "Modified content"  # In-place modification works
>>> print(vcon.dialog[0]["body"])  # Prints "Modified content"
dumps() → str[source]

Alias for to_json().

This method is an alias for to_json() and converts the vCon object to a JSON string representation.

Returns:

A JSON string representation of the vCon

Example

>>> vcon = Vcon.build_new()
>>> json_str = vcon.dumps()
>>> print(type(json_str))  # Prints "<class 'str'>"
property events: List[Dict[str, Any]]

The events array (Event Objects).

find_analysis_by_type(type: str) → Dict[str, Any] | None[source]

Find an analysis entry in the vCon by its type.

This method searches through the vCon’s analysis entries and returns the first one matching the specified type.

Parameters:

type – The type of analysis to find

Returns:

The matching analysis dictionary if found, None otherwise

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_analysis(type="sentiment", dialog=[0], vendor="acme", body={"score": 0.8})
>>> sentiment = vcon.find_analysis_by_type("sentiment")
find_attachment_by_purpose(purpose: str) → Dict[str, Any] | None[source]

Find an attachment in the vCon by its purpose.

This method searches through the vCon’s attachments and returns the first attachment matching the specified type.

Parameters:

purpose – The purpose of attachment to find

Returns:

The matching attachment dictionary if found, None otherwise

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Alice"))
>>> vcon.add_session()
>>> vcon.add_attachment("metadata", {"version": "1.0"})
>>> metadata = vcon.find_attachment_by_purpose("metadata")
find_dialog(by: str, val: str) → Dialog | None[source]

Find a dialog entry in the vCon by a key-value pair.

This method searches through the dialog list and returns the first dialog entry that matches the specified key-value pair, converted to a Dialog object.

Parameters:
  • by – The key to search by (e.g., “type”, “start”)

  • val – The value to match

Returns:

A Dialog object if found, None otherwise

Example

>>> vcon = Vcon.build_new()
>>> dialog = Dialog(type="text", start="2023-01-01T00:00:00Z", parties=[0])
>>> vcon.add_dialog(dialog)
>>> found = vcon.find_dialog("type", "text")
>>> print(found.type)  # Prints "text"
find_dialogs_by_type(type: str) → List[Dict[str, Any]][source]

Find all dialog entries in the vCon by type. This method searches through the dialog list and returns all dialog entries matching the specified type. :param type: The type of dialogs to find

Returns:

A list of matching dialog dictionaries

Example

>>> vcon = Vcon.build_new()
>>> incomplete = vcon.find_dialogs_by_type("incomplete")
find_lawful_basis_attachments(party_index: int | None = None) → List[Dict[str, Any]][source]

Find lawful basis attachments in the vCon.

Parameters:

party_index – Filter by party index (optional)

Returns:

List of lawful basis attachment dictionaries

find_party_index(by: str, val: str) → int | None[source]

Find the index of a party in the vCon’s parties list.

This method searches through the parties list and returns the index of the first party that matches the specified key-value pair.

Parameters:
  • by – The key to search by (e.g., “name”, “type”)

  • val – The value to match

Returns:

The index of the matching party if found, None otherwise

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(type="person", name="John Doe"))
>>> index = vcon.find_party_index("name", "John Doe")
>>> print(index)  # Prints 0
find_wtf_attachments(party_index: int | None = None) → List[Dict[str, Any]][source]

Find WTF transcription attachments in the vCon.

Parameters:

party_index – Filter by party index (optional)

Returns:

List of WTF attachment dictionaries

classmethod generate_key_pair() → Tuple[RSAPrivateKey, RSAPublicKey][source]

Generate a new RSA key pair for signing vCons.

This method generates a new RSA key pair that can be used for signing and verifying vCons.

Returns:

A tuple containing the private key and public key

Example

>>> private_key, public_key = Vcon.generate_key_pair()
>>> vcon = Vcon.build_new()
>>> vcon.sign(private_key)
>>> is_valid = vcon.verify(public_key)
get_critical() → List[str][source]

Get the list of critical extensions that must be supported.

Returns:

List of extension names that must be supported, empty list if none are defined

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_critical("encryption")
>>> critical = vcon.get_critical()
>>> print(critical)  # Prints ["encryption"]
get_extensions() → List[str][source]

Get the list of extensions used in this vCon.

Returns:

List of extension names, empty list if none are defined

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_extension("video")
>>> extensions = vcon.get_extensions()
>>> print(extensions)  # Prints ["video"]
get_party_objects() → List[Party][source]

Get the list of parties as Party objects.

This method creates Party objects from the underlying dictionary data. Use this when you need Party objects instead of raw dictionaries.

Returns:

A list of Party objects representing all participants in the conversation

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(type="person", name="John Doe"))
>>> party_objects = vcon.get_party_objects()
>>> print(party_objects[0].name)  # Prints "John Doe"
get_tag(tag_name: str) → str | None[source]

Get the value of a specific tag by name.

Parameters:

tag_name – The name of the tag to retrieve

Returns:

The value of the tag if found, None otherwise

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Alice"))
>>> vcon.add_session()
>>> vcon.add_tag("category", "meeting")
>>> value = vcon.get_tag("category")
>>> print(value)  # Prints "meeting"
get_validation_warnings() → List[str][source]

SHOULD-level findings (for example SHOULD NOT parameters on Events).

property group
is_valid() → Tuple[bool, List[str]][source]

Validate the vCon against the core-05 rules.

Checks required fields and types, that vcon (if present) is “0.5.0”, that Sessions, Events, Dialogs, attachments and analysis reference existing objects, the per-event-type parameter table, that at least one Session exists when there are Dialogs or Events, that attachments have party and dialog or session, that redacted_from and amended_from are exclusive, that extensions lists every extension in use (and every critical entry), that every __REDACTED_REF_# has a redacted_strings entry, that every url has a content_hash and every content_hash is well formed, and the body of every lawful_basis attachment.

SHOULD-level findings are not errors; see get_validation_warnings().

Returns:

A tuple where the first element is True if the vCon is valid and False otherwise, and the second element is a list of error messages.

Return type:

Tuple[bool, List[str]]

classmethod load(source: str, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) → Vcon[source]

Load a vCon from either a file path or URL.

Parameters:
  • source – File path or URL to load the vCon from

  • property_handling – How to handle non-standard properties. Options are “default”, “strict”, or “meta”

Returns:

A Vcon object

Raises:
  • ValueError – If the source is invalid or cannot be loaded

  • requests.RequestException – If there is an error fetching from URL

  • json.JSONDecodeError – If the source contains invalid JSON

classmethod load_from_file(file_path: str, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) → Vcon[source]

Load a vCon from a file.

Parameters:
  • file_path – Path to the vCon JSON file

  • property_handling – How to handle non-standard properties. Options are “default”, “strict”, or “meta”

Returns:

A Vcon object

Raises:
  • FileNotFoundError – If the file does not exist

  • json.JSONDecodeError – If the file contains invalid JSON

classmethod load_from_url(url: str, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) → Vcon[source]

Load a vCon from a URL.

Parameters:
  • url – URL to fetch the vCon JSON from

  • property_handling – How to handle non-standard properties. Options are “default”, “strict”, or “meta”

Returns:

A Vcon object

Raises:
  • requests.RequestException – If there is an error fetching from URL

  • json.JSONDecodeError – If the response contains invalid JSON

property meta
classmethod migrate_0_4_0_to_0_5_0(source: str | Dict[str, Any], strict: bool = False, property_handling: str = 'default') → Vcon[source]

Explicitly migrate a 0.4.0 vCon (dict or JSON string) and return a Vcon.

The migration report is available as vcon.migration_report. Unlike the implicit migration on load, this also accepts input with no vcon parameter. See vcon.migration.migrate_0_4_0_to_0_5_0().

migration_report: MigrationReport | None

MigrationReport when the input was migrated from 0.4.0, else None.

property parties: List[Dict[str, Any]]

Get the list of parties in the vCon.

Returns:

A list of party dictionaries representing all participants in the conversation. These are mutable references to the internal data structure, allowing in-place modifications.

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(type="person", name="John Doe"))
>>> parties = vcon.parties
>>> print(parties[0]["name"])  # Prints "John Doe"
>>> parties[0]["name"] = "Jane Doe"  # In-place modification works
>>> print(vcon.parties[0]["name"])  # Prints "Jane Doe"
post_to_url(url: str, headers: Dict[str, str] | None = None) → Response[source]

Post the vCon as JSON to a URL with optional headers.

Parameters:
  • url (str) – The URL to post the vCon to

  • headers (Optional[Dict[str, str]]) – Optional dictionary of HTTP headers (e.g., {‘x-conserver-api-token’: ‘token123’})

Returns:

The HTTP response from the server

Return type:

requests.Response

Raises:

requests.RequestException – If there is an error making the HTTP request

Example

>>> vcon = Vcon.build_new()
>>> response = vcon.post_to_url(
...     'https://api.example.com/vcons',
...     headers={'x-conserver-api-token': 'your-token-here'}
... )
>>> print(response.status_code)  # Prints HTTP status code (e.g., 200 for success)
process_extensions() → Dict[str, Any][source]

Process all extensions in the vCon.

Returns:

Dictionary with processing results for each extension

property redacted

Deprecated 0.4.0 name; returns redacted_from.

property redacted_from
property redacted_strings: List[Dict[str, Any]]
remove_critical(extension: str) → None[source]

Remove an extension from the critical list.

Parameters:

extension – The name of the extension to remove from critical

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_critical("encryption")
>>> vcon.remove_critical("encryption")
remove_extension(extension: str) → None[source]

Remove an extension from the vCon.

Parameters:

extension – The name of the extension to remove

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_extension("video")
>>> vcon.remove_extension("video")
save_to_file(file_path: str) → None[source]

Save the vCon to a JSON file.

Parameters:

file_path (str) – Path where the vCon JSON should be saved

Raises:

IOError – If there is an error writing to the file

property sessions: List[Dict[str, Any]]

The sessions array (Session Objects).

set_created_at(created_at: str | datetime) → None[source]

Set the created_at field in the vCon.

Parameters:

created_at (Union[str, datetime]) – The timestamp to set, either as a string in ISO format or as a datetime object.

set_updated_at(timestamp: str | datetime) → None[source]

Set the updated_at timestamp.

Args: timestamp: The timestamp to set, either as ISO 8601 string or datetime object

Example: >>> vcon = Vcon.build_new() >>> vcon.set_updated_at(datetime.now(timezone.utc)) >>> vcon.set_updated_at(“2025-02-18T12:00:00Z”)

sign(private_key: RSAPrivateKey | bytes, alg: str = 'RS256') → None[source]

Sign the vCon using JWS (JSON Web Signature).

This method signs the vCon using the provided private key, adding the signature information to the vCon. The signature can later be verified using the corresponding public key.

Parameters:
  • private_key – The RSA private key or its PEM representation

  • alg – JWS algorithm (default “RS256”, the value core-05 says SHOULD be used). “none” is rejected (6.2.2).

Raises:
  • AlgorithmNotPermittedError – If alg is “none” (any case) or is not a permitted algorithm.

  • Exception – If there is an error during the signing process

Example

>>> from cryptography.hazmat.primitives.asymmetric import rsa
>>> private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
>>> vcon = Vcon.build_new()
>>> vcon.sign(private_key)
property subject: str | None
property tags: Dict[str, Any] | None

Get the tags attachment from the vCon.

Returns:

The tags attachment dictionary if it exists, None otherwise

Example

>>> vcon = Vcon.build_new()
>>> vcon.add_party(Party(name="Alice"))
>>> vcon.add_session()
>>> vcon.add_tag("category", "meeting")
>>> tags = vcon.tags
>>> print(tags["body"])  # Prints ["category:meeting"]
to_dict() → Dict[str, Any][source]

Convert the vCon to a dictionary.

This method returns a dictionary representation of the vCon object, which can be used for direct manipulation or inspection.

Returns:

A dictionary representation of the vCon

Example

>>> vcon = Vcon.build_new()
>>> vcon_dict = vcon.to_dict()
>>> print(vcon_dict["vcon"])  # Prints "0.5.0"
to_json() → str[source]

Serialize the vCon to a JSON string.

This method converts the entire vCon object to a JSON string representation, which can be used for storage or transmission.

Returns:

A JSON string representation of the vCon

Example

>>> vcon = Vcon.build_new()
>>> json_str = vcon.to_json()
>>> print(type(json_str))  # Prints "<class 'str'>"
property updated_at
property uuid: str
static uuid8_domain_name(domain_name: str) → str[source]
static uuid8_time(custom_c_62_bits: int) → str[source]
validate_extensions() → Dict[str, Any][source]

Validate all extensions in the vCon.

Returns:

Dictionary with validation results for each extension

static validate_file(file_path: str) → tuple[bool, list[str]][source]

Validate a vCon file at the given path.

Parameters:

file_path (str) – Path to the vCon JSON file

Returns:

A tuple containing (is_valid, list_of_errors)

Return type:

tuple[bool, list[str]]

static validate_json(json_str: str) → tuple[bool, list[str]][source]

Validate a vCon from a JSON string.

Parameters:

json_str (str) – JSON string representing a vCon

Returns:

A tuple containing (is_valid, list_of_errors)

Return type:

tuple[bool, list[str]]

property vcon: str | None
verify(public_key: RSAPublicKey | bytes) → bool[source]

Verify the JWS signature of the vCon.

This method verifies the vCon’s signature using the provided public key. The vCon must have been previously signed using the corresponding private key.

Parameters:

public_key – The RSA public key or its PEM representation

Returns:

True if the signature is valid, False otherwise

Raises:
  • ValueError – If the vCon is not signed

  • AlgorithmNotPermittedError – If the signature declares alg “none” (in the protected header or the signature’s header), which core-05 forbids. Verification is refused rather than skipped.

Example

>>> private_key, public_key = Vcon.generate_key_pair()
>>> vcon = Vcon.build_new()
>>> vcon.sign(private_key)
>>> is_valid = vcon.verify(public_key)
>>> print(is_valid)  # Prints True