Skip to content

CHANGELOG.md

Latest commit

 

History

History
482 lines (386 loc) · 25.9 KB

CHANGELOG.md

File metadata and controls

482 lines (386 loc) · 25.9 KB
Raw

Changelog

[0.10.0] - Unreleased

Retargets the library to draft-ietf-vcon-vcon-core-04. Under -04 section 2.3.2, a "json"-encoded body is the JSON value itself (object, array, string, number, bool, or null), not a json.dumps string. add_tag()'s list body and add_lawful_basis_attachment()'s object body were already correct under -04; this release brings readers, defaults, and the WTF/ lawful-basis extensions in line with the same convention, and fixes a handful of adjacent spec-compliance gaps.

Changed

  • Breaking (output shape): every attachment created via add_attachment(), add_lawful_basis_attachment(), and add_wtf_transcription_attachment() now defaults party and dialog to 0 when not supplied (matching add_tag()'s existing convention), start to the vCon's created_at, and mediatype to "application/json" for encoding="json" bodies. The WG JSON schema requires start, party, dialog on every attachment; previously these were omitted unless explicitly passed, producing non-compliant output. Callers that inspected the absence of these keys (rather than their values) will see a difference.
  • Attachment.__init__ applies the same party/dialog/mediatype defaults directly, so Attachment(...) constructed outside of a Vcon gets the same defaults as Vcon.add_attachment().
  • Dialog.to_dict() no longer emits empty meta: {} / metadata: {} placeholders. Both attributes are still initialized internally for backward-compatible attribute access (dialog.meta, dialog.metadata); only the serialized form changes.
  • Inline base64url bodies written by the library (Dialog.add_image_data(), Dialog.add_video_data(), Dialog.transcode_video(), Dialog.to_inline_data(), Attachment.from_image()) are now unpadded, per -04's JWS/RFC 7515-style base64url convention. New vcon.dialog.b64url_encode() / vcon.dialog.b64url_decode() helpers encode without padding and decode padded-or-unpadded input respectively; internal decode call sites (add_video_data, generate_thumbnail, extract_video_metadata, transcode_video) were updated to use b64url_decode() so both old (padded) and new (unpadded) bodies still decode.
  • .github/workflows/python-publish.yml now triggers on push: tags: ['v*'] instead of release: published. The tag push is the release; nothing else should publish. Publishing auth is unchanged (a stored PYPI_API_TOKEN secret via pypa/gh-action-pypi-publish) -- this repo's existing workflow was not already using PyPI trusted publishing (OIDC), so switching auth methods was out of scope for this change and is left as a separate follow-up.

Added

  • vcon.body.decode_body(entry) (also exposed as Vcon.decoded_body(entry)), a shared helper that decodes an attachment/analysis/dialog body, accepting both the -04 shape (body already the decoded value) and a legacy JSON-encoded string body (as written under -02 conventions, or by this library prior to 0.10.0). Used by Vcon.get_tag()/add_tag() and by the lawful-basis and WTF extension validators/processors, so every body-reading call site in the library now accepts both shapes.
  • vcon.dialog.b64url_encode() / vcon.dialog.b64url_decode(), public unpadded-base64url encode/decode helpers (see Changed, above).
  • tests/schema/vcon_json_schema.json, a vendored copy of the vCon working group's reference JSON schema (see tests/schema/SOURCE.md for provenance), plus tests/test_schema_compliance.py, which builds a vCon using only public helpers (add_tag, add_lawful_basis_attachment, add_dialog, add_attachment) and validates it against that schema with no post-processing. jsonschema added as a dev dependency.
  • scripts/check_version.py, a version-consistency guard: compares pyproject.toml's version against the newest ## [x.y.z] CHANGELOG heading and (if present) setup.py's hardcoded version, and, given --tag <ref>, also checks a release tag against the pyproject version. Wired into CI on every push/PR, and into the publish workflow immediately before publishing so a release cut from the wrong commit fails loudly.

Fixed

  • Vcon.get_tag() and Vcon.add_tag() now accept a legacy JSON-string tags body (written under -02 conventions, or by this library prior to 0.10.0) as well as the -04 list-valued body. add_tag() normalizes a legacy string body to a list in place, preserving existing tags, before appending the new one.
  • The lawful-basis and WTF extension validators/processors (extensions/lawful_basis/validation.py, extensions/lawful_basis/processing.py, extensions/wtf/validation.py, extensions/wtf/processing.py, extensions/wtf/extension.py) now decode a legacy JSON-string attachment body before working with it, instead of assuming it is already a dict.

[0.9.6] - 2026-06-04

Security

  • Bumped requests to ^2.33.0 (locked 2.34.2). This was the only Dependabot-flagged runtime dependency still vulnerable at the locked version; all others (authlib 1.7.2, cryptography 48.0.0, urllib3 2.7.0, idna 3.15) were already at patched versions in poetry.lock from the v0.9.4 bump.
  • Removed the committed requirements.txt. It was a stale, hash-pinned export (last regenerated 2026-04-16) pinning vulnerable versions (authlib 1.3.2, cryptography 45.0.4, urllib3 2.2.2, idna 3.8, certifi 2024.7.4) and was the source of roughly half the open Dependabot alerts. pyproject.toml / poetry.lock are now the single source of truth; environment.yml installs the project directly via pip: ["."]. No GitHub workflow used requirements.txt (all use poetry install).

Fixed

  • Removed a misconfigured [[tool.poetry.source]] block that declared TestPyPI with priority = "primary" ahead of PyPI, which caused poetry lock / poetry install to query the TestPyPI sandbox first. Dependency resolution now defaults to PyPI.

[0.9.5] - 2026-06-04

Changed

  • Dialog now computes and emits content_hash in the spec-compliant sha512-<base64url> form with no base64 padding, per draft-ietf-vcon-vcon-core-02 (matching the canonical vcon-info examples and the vcon-js v0.4.0 validator). Previously these helpers emitted an unprefixed, padded base64url SHA-256 digest, which strict parsers reject. Affected helpers: add_external_data(), add_inline_data(), add_image_data(), and to_inline_data().
  • Dialog.calculate_content_hash() now defaults to sha512 and returns the algorithm-prefixed form; sha256 is still accepted and returns a sha256- prefixed value.

Fixed

  • Dialog.is_external_data_changed() and Dialog.verify_content_hash() now parse the algorithm prefix (sha512- / sha256-) of the stored hash and recompute with the matching algorithm. They previously always recomputed SHA-256, so they could not verify a spec-compliant SHA-512 hash. Legacy unprefixed (padded SHA-256) hashes emitted by earlier releases still verify, so existing vCons are unaffected.

Added

  • vcon.compute_content_hash(data, algorithm="sha512") and vcon.parse_content_hash_algorithm(content_hash) — reusable, spec-formatting content-hash helpers exported from the package root so adapters and generators can hash external/inline media via the library instead of hand-rolling base64url.

[0.9.4] - 2026-05-19

Security

  • Bumped dependencies to resolve Dependabot alerts: authlib, requests, pydash, python-dateutil, mutagen, pypdf, pillow, uuid6.

[0.9.3] - 2026-05-19

Fixed

  • Vcon.add_tag() now correctly includes party: 0 and dialog: 0 on the created tags-purpose attachment. Previously the attachment was emitted without these spec-required indices, producing non-compliant vCon output. Test coverage added to test_tags to prevent regression.

[0.9.2] - 2026-05-10

Fixed

  • Vcon.build_new() now emits "vcon": "0.4.0" per draft-ietf-vcon-vcon-core-02 §4.1.1. The field is deprecated in the draft but retained for parser compatibility; emitting it by default avoids surprises with strict parsers.
  • Vcon.build_new() no longer initializes empty "group": [] and "redacted": {}. The speckit reserves group, and downstream consumers no longer need to strip these defaults before serializing. Both fields are still populated lazily by their setters.

Added

  • add_wtf_transcription_analysis() — sibling helper to add_wtf_transcription_attachment that places the WTF transcription into analysis[] as a spec-shaped analysis entry (type: "transcription", vendor, product, schema, encoding: "json", JSON-stringified body). Use this when your pipeline treats transcripts as derived analysis output; use the existing _attachment helper for the canonical attachments[] placement shown in the speckit example.

[0.9.0] - 2025-01-26

🎉 Major Release: Extension Framework and Privacy Compliance

This release introduces a comprehensive extension framework with two major extensions: the Lawful Basis extension for GDPR-compliant privacy management and the WTF (World Transcription Format) extension for standardized speech-to-text transcription data.

✨ Added

Extension Framework

  • Extension Registry: Centralized registry for managing vCon extensions
  • Extension Validation: Comprehensive validation framework for extension data
  • Extension Processing: Standardized processing and analysis framework
  • Extension Types: Support for Compatible, Incompatible, and Experimental extensions
  • Extension Management: Methods for adding, removing, and managing extensions

Lawful Basis Extension (Privacy Compliance)

  • GDPR Compliance: Full support for GDPR-compliant consent management
  • Multiple Lawful Basis Types: consent, contract, legal_obligation, vital_interests, public_task, legitimate_interests
  • Purpose-Specific Permissions: Granular permission grants with conditions
  • Cryptographic Proof Mechanisms: Verbal confirmation, signed documents, cryptographic signatures, external systems
  • Temporal Validity: Expiration dates and status intervals
  • Content Integrity: Hash validation and canonicalization
  • External Registry Integration: SCITT (Supply Chain Integrity, Transparency, and Trust) support
  • Permission Checking: check_lawful_basis_permission() method for granular permission validation

WTF Extension (World Transcription Format)

  • Multi-Provider Support: Whisper, Deepgram, AssemblyAI
  • Standardized Format: Hierarchical structure with transcripts, segments, words, and speakers
  • Quality Metrics: Audio quality assessment and confidence scoring
  • Export Capabilities: SRT and WebVTT subtitle formats
  • Provider Adapters: Automatic conversion from provider-specific formats
  • Analysis Tools: Keyword extraction, confidence analysis, and transcription comparison
  • Speaker Identification: Support for multiple speakers with timing and confidence data

Vcon Class Extensions

  • add_lawful_basis_attachment(): Add lawful basis attachments with consent management
  • add_wtf_transcription_attachment(): Add standardized transcription attachments
  • find_lawful_basis_attachments(): Find and filter lawful basis attachments
  • find_wtf_attachments(): Find and filter WTF transcription attachments
  • check_lawful_basis_permission(): Check permissions for specific purposes
  • validate_extensions(): Validate all extensions in a vCon
  • process_extensions(): Process all extensions in a vCon

🔄 Changed

Extension Integration

  • Attachment Properties: Added start, party, and dialog to allowed attachment properties
  • Extension Registry: Automatic initialization of default extensions
  • Import Handling: Graceful handling of extension imports with fallback

🧪 Testing

Comprehensive Test Suite

  • Extension Framework Tests: Test coverage for extension registry and validation
  • Lawful Basis Tests: Test suite for privacy compliance functionality
  • WTF Extension Tests: Test coverage for transcription functionality
  • Integration Tests: End-to-end testing of extension workflows
  • Provider Adapter Tests: Testing of multi-provider data conversion
  • Export Functionality Tests: SRT and WebVTT export testing

📄 Documentation

Comprehensive Documentation Updates

  • README.md: Added comprehensive quickstart with extension examples
  • API_REFERENCE.md: Complete extension API documentation (1,751 lines)
  • GUIDE.md: Comprehensive extension usage guide (765 lines)
  • LLM_GUIDE.md: AI-assisted development guide with extension patterns (1,817 lines)
  • Extension Examples: Complete working examples for both extensions

Sample Files

  • extension_example.py: Comprehensive extension example (231 lines)
  • example_new_fields.vcon.json: Clean example showing new fields
  • Cleaned Samples: Removed 8 deprecated files (~1.4MB cleanup)

🔧 Technical Details

Extension Architecture

  • Base Classes: ExtensionType, ExtensionValidator, ExtensionProcessor
  • Registry System: Centralized ExtensionRegistry with automatic initialization
  • Validation Framework: Comprehensive validation with error and warning reporting
  • Processing Framework: Standardized processing with result reporting

Lawful Basis Implementation

  • Data Structures: LawfulBasisAttachment, PurposeGrant, ContentHash, ProofMechanism
  • Validation: Comprehensive validation of consent data and temporal validity
  • Processing: Permission checking and consent verification
  • Compliance: GDPR, CCPA, and HIPAA compliance support

WTF Implementation

  • Data Structures: WTFAttachment, Transcript, Segment, Word, Speaker, Quality
  • Provider Adapters: WhisperAdapter, DeepgramAdapter, AssemblyAIAdapter
  • Export Formats: SRT and WebVTT subtitle generation
  • Analysis Tools: Keyword extraction, confidence analysis, speaking time calculation

🚀 Performance

Optimizations

  • Lazy Loading: Extensions loaded only when needed
  • Efficient Validation: Optimized validation algorithms
  • Memory Management: Efficient handling of large transcription data
  • Export Performance: Fast SRT and WebVTT generation

🔒 Security

Privacy and Security

  • Content Integrity: Hash validation and canonicalization
  • Cryptographic Proofs: Support for digital signatures and proof mechanisms
  • Temporal Validation: Expiration date checking and status validation
  • Permission Granularity: Fine-grained permission checking

📊 Statistics

Code Metrics

  • New Files: 20+ new extension-related files
  • Lines of Code: 2,000+ lines of new extension functionality
  • Test Coverage: Test coverage for extension features
  • Documentation: 4,000+ lines of comprehensive documentation

Feature Coverage

  • 2 Major Extensions: Lawful Basis and WTF
  • 3 Provider Adapters: Multi-provider transcription support
  • 2 Export Formats: SRT and WebVTT
  • 6+ Validation Types: Comprehensive extension validation
  • 15+ New Methods: Extension-specific functionality

[0.8.0] - 2025-01-26

🎉 Major Release: Version Management Simplification

This release aligns with the upcoming vCon draft specification by removing mandatory version management and enforcement, making the version field optional while maintaining full backward compatibility.

✨ Added

Flexible Versioning

  • Optional Version Field: The vcon field is now optional in vCon objects
  • Version Preservation: Existing vCons with version fields continue to work unchanged
  • Simplified Creation: New vCons can be created without version fields

🔄 Changed

Version Management Simplification

  • Removed strict_version Parameter: Eliminated from all Vcon methods (__init__, build_from_json, build_new, load, load_from_file, load_from_url)
  • No Automatic Version Assignment: vCon objects no longer automatically get a version field
  • No Version Migration: Removed automatic migration from older versions
  • Updated Validation: The is_valid() method no longer requires the version field

Method Signatures Updated

  • Vcon(vcon_dict=None, property_handling="default") - removed strict_version parameter
  • build_from_json(json_str, property_handling="default") - removed strict_version parameter
  • build_new(created_at=None, property_handling="default") - removed strict_version parameter
  • load(source, property_handling="default") - removed strict_version parameter
  • load_from_file(file_path, property_handling="default") - removed strict_version parameter
  • load_from_url(url, property_handling="default") - removed strict_version parameter

🧪 Testing

Updated Test Suite

  • Replaced Version Migration Tests: Updated tests to cover optional version field behavior
  • New Test Cases: Added comprehensive tests for versionless vCon creation and preservation
  • Backward Compatibility Tests: Ensured existing vCons with version fields continue to work

📄 Documentation

Updated Documentation

  • README.md: Updated to reflect version field being optional
  • API_REFERENCE.md: Removed strict_version parameter from all method signatures
  • GUIDE.md: Updated examples to show versionless vCon creation
  • MIGRATION_GUIDE.md: Added migration steps for version management changes

Updated Sample Files

  • Removed Version Fields: All sample vCon JSON files updated to demonstrate versionless vCons
  • Backward Compatibility: Existing vCons with version fields continue to work

🔧 Technical Details

Implementation Changes

  • Removed Version Logic: Eliminated version checking, migration, and enforcement code
  • Simplified Initialization: Streamlined vCon object creation process
  • Preserved Functionality: All other features remain unchanged

Backward Compatibility

  • Existing vCons: Continue to work without any changes
  • Version Fields: Preserved when present, not added when absent
  • API Compatibility: All other methods and properties remain unchanged

🎯 Benefits

  1. Enhanced Flexibility: vCon objects can now exist without mandatory versioning
  2. Simplified Implementation: Reduced complexity in version management
  3. Better Privacy Support: Enables creation of redacted versions without version conflicts
  4. Multiple Version Support: Allows different versions of the same vCon to coexist
  5. Specification Compliance: Aligns with upcoming vCon draft specification

[0.7.0] - 2025-07-19

🎉 Major Release: Complete vCon 0.3.0 Specification Compliance

This release implements full compliance with the IETF vCon 0.3.0 specification, adding comprehensive support for all new fields, validation, and features while maintaining complete backward compatibility.

✨ Added

vCon Object Level Features

  • Extensions Support:
    • extensions field for declaring extension capabilities
    • must_support field for specifying required extensions
    • Helper methods: add_extension(), remove_extension(), get_extensions()
    • Helper methods: add_must_support(), remove_must_support(), get_must_support()
    • Automatic duplicate prevention and validation

Enhanced Party Object Support

  • New Contact Methods:
    • sip field for SIP URI contact information
    • did field for Decentralized Identifier (blockchain-based identity)
    • jCard field for vCard format contact information (RFC 7095)
    • timezone field for party timezone information
  • Civic Address Support: Complete GEOPRIV specification compliance
    • All administrative areas (a1-a6)
    • Street and building information (sts, hno, hns, prd, flr)
    • Location and identification fields (country, pc, nam, lmk, loc, pod)

Enhanced Dialog Object Support

  • Session Management:
    • session_id field for session tracking
    • content_hash field for content integrity verification (replaces alg/signature)
    • application field for application identification
    • message_id field for email/text dialog identification
  • Content Integrity:
    • calculate_content_hash() method with SHA-256 support
    • verify_content_hash() method for integrity verification
    • Automatic content hash calculation for external files

Party History Event Tracking

  • New PartyHistory Class: Complete implementation of party history events
    • Support for all 6 specification event types: join, drop, hold, unhold, mute, unmute
    • Event validation with VALID_EVENTS list
    • ISO 8601 time serialization for all events
    • Proper error handling for invalid events

Enhanced Media Type Support

  • Specification-Compliant Media Types:
    • Added audio/x-mp3 and audio/x-mp4 (specification required)
    • Enhanced video format support (MP4, WebM, AVI, MKV, MOV, FLV, 3GP)
    • Complete audio format coverage (WAV, MP3, MP4, OGG, WebM, AAC)
    • Image and document support (JPEG, TIFF, PDF)

Disposition Values for Incomplete Dialogs

  • Complete Disposition Support: All 6 specification values implemented
    • no-answer: Call attempted but no answer
    • congestion: System load prevented completion
    • failed: Call/connection failed
    • busy: Party was busy
    • hung-up: Party hung up before conversation
    • voicemail-no-message: Voicemail answered but no message left
  • Validation: Automatic validation for incomplete dialog types

Transfer Dialog Enhancements

  • Updated Field Names: Consistent underscore naming convention
    • transfer-target → transfer_target
    • target-dialog → target_dialog
  • Enhanced Transfer Support: Complete transfer operation tracking

Comprehensive Documentation

  • Updated Class Documentation: Complete docstrings for all classes
    • Vcon class with vCon 0.3.0 feature documentation
    • Party class with new contact method documentation
    • Dialog class with session and content hash documentation
    • CivicAddress class with GEOPRIV compliance documentation
    • PartyHistory class with event tracking documentation
  • Enhanced README: Comprehensive usage examples and feature documentation
  • API Documentation: Complete API reference with examples

🔧 Changed

Property Handling

  • Updated Allowed Properties: All new fields added to property lists
    • _ALLOWED_VCON_PROPERTIES: Added extensions, must_support
    • _ALLOWED_PARTY_PROPERTIES: Added sip, did, jCard, timezone
    • _ALLOWED_DIALOG_PROPERTIES: Added session_id, content_hash, application, message_id
  • Enhanced Property Processing: Improved handling in all modes (default, strict, meta)

Validation Enhancements

  • Comprehensive Validation: Enhanced validation for all new fields
    • Party history event validation
    • Disposition value validation for incomplete dialogs
    • Media type validation with specification compliance
    • Civic address field validation
  • Backward Compatibility: All validation maintains backward compatibility

Serialization Improvements

  • ISO 8601 Compliance: All datetime fields properly serialized
  • Content Hash Integration: Automatic content hash calculation and verification
  • Extension Management: Proper serialization of extensions and must_support fields

🧪 Testing

Comprehensive Test Coverage

  • 149 Tests Passing: Complete test suite with 7 skipped (advanced features)
  • New Feature Tests: Extensive testing for all new vCon 0.3.0 features
    • Party history event validation tests
    • Disposition value validation tests
    • Media type validation tests
    • Extension management tests
    • Content hash calculation tests
  • Backward Compatibility Tests: Verification that existing functionality works unchanged
  • Validation Tests: Comprehensive validation testing for all new fields

📚 Documentation

Complete Documentation Update

  • Class Documentation: Updated all class docstrings with vCon 0.3.0 features
  • README Enhancement: Comprehensive usage examples and feature documentation
  • API Reference: Complete API documentation with examples
  • Workplan Documentation: Complete implementation tracking in IETF-123-WORKPLAN.md

🔄 Migration Support

Version Migration

  • Automatic Migration: Seamless migration from older vCon versions
  • Strict Mode Support: Optional strict version checking
  • Backward Compatibility: Full compatibility with existing vCon files

🔑 Security

Enhanced Security Features

  • Content Integrity: SHA-256 content hashing for external files
  • Digital Signatures: JWS support for vCon signing
  • Validation: Comprehensive validation for all security-related fields

📄 Sample Files

Updated Sample Files

  • Version 0.3.0 Compliance: All sample files updated to vCon 0.3.0
  • New Field Examples: Sample files demonstrating new features
  • Backward Compatibility: Existing sample files continue to work

🔧 Technical Details

Implementation Quality

  • 149 Tests Passing: Comprehensive test coverage
  • Zero Breaking Changes: Complete backward compatibility
  • Specification Compliance: Full vCon 0.3.0 specification implementation
  • Performance: Optimized implementation with minimal overhead
  • Error Handling: Comprehensive error handling and validation

Code Quality

  • Type Hints: Complete type annotation coverage
  • Documentation: Comprehensive docstrings and comments
  • Linting: Clean code with minimal linting issues
  • Modularity: Well-structured, maintainable code

[0.6.0] - Previous Version

  • Updated the __init__ methods in Dialog and Party classes to accept additional keyword arguments (**kwargs) for flexibility.
  • Simplified attribute assignment by using locals() to set non-None values.
  • Enhanced the to_dict method in Dialog to return all non-None attributes.
  • Improved readability and consistency in the code structure.
  • Added docstrings for better documentation of methods and parameters.