githubEdit

Coding Prompt Cheat Sheet

For when you need to tell cursor or replit what a vCon is in a prompt...

vCon (Virtual Conversation) Standard - LLM Context

What is a vCon?

A vCon is a standardized JSON container for storing and exchanging real-time human conversation data. It supports multiple communication types: phone calls, video conferences, SMS, MMS, emails, web chat, and more. vCons enable consistent storage, analysis, and interchange of conversational data across different platforms and services.

Core Structure

Every vCon has exactly 5 main sections:

  1. metadata - conversation context and identifiers

  2. parties - participant information

  3. dialog - actual conversation content

  4. analysis - derived insights (transcripts, sentiment, etc.)

  5. attachments - supplemental files

vCon States

  • unsigned - initial/intermediate state during collection

  • signed - verified with JWS digital signature for immutability

  • encrypted - secured with JWE for sensitive data

Complete JSON Schema

Top-Level vCon Object Properties

Party Object Properties

Dialog Object Properties

Analysis Object Properties

Attachment Object Properties

Redacted Object Properties

Appended Object Properties

Group Object Properties

Party History Object Properties (for Dialog.party_history)

Security Features

  • JWS Signing - ensures integrity and authenticity using RS256 (recommended)

  • JWE Encryption - protects sensitive content using RSA-OAEP + A256CBC-HS512 (recommended)

  • Content Hashing - SHA-512 hashes for external file integrity (mandatory for external refs)

  • Versioning - maintains history of changes and redactions via uuid references

Signed vCon Structure (JWS)

Encrypted vCon Structure (JWE)

Common Media Types

Dialog

  • text/plain - plain text messages

  • audio/x-wav - WAV audio files

  • audio/x-mp3 - MP3 audio files

  • audio/x-mp4 - MP4 audio files

  • audio/ogg - OGG audio files

  • video/x-mp4 - MP4 video files

  • video/ogg - OGG video files

  • multipart/mixed - multipart content (emails)

Content Encoding Options

  • base64url - Base64url encoded binary data

  • json - Valid JSON object

  • none - Valid JSON string, no encoding needed

Implementation Guidelines

  • Follow JSON schema strictly for compliance

  • Use proper timestamps (RFC3339/ISO 8601 format)

  • Ensure UUIDs are globally unique (prefer version 8 with domain-based generation)

  • Implement proper signing/encryption for production use

  • Maintain referential integrity between sections

  • Always use HTTPS for external file references

  • Validate content hashes for external files using SHA-512

Python Development Notes

  • Use uuid library for generating UUIDs (version 8 recommended)

  • datetime.isoformat() for RFC3339 timestamps

  • json module for serialization/deserialization

  • cryptography library for JWS/JWE operations

  • hashlib for SHA-512 content hash generation

  • Validate against vCon JSON schema before processing

  • Use requests with SSL verification for external file retrieval

Key Considerations

  • vCons can reference previous versions (redaction/append history via uuid)

  • Media content can be embedded (body + encoding) or referenced externally (url + content_hash)

  • Privacy and compliance requirements vary by jurisdiction

  • Large media files should typically be stored as external references

  • Ensure proper escaping of JSON content in dialog sections

  • Support both single-channel and multi-channel audio recordings

  • Handle participant join/leave events in party_history for complex conversations

  • Maintain chain of custody through signing and encryption across security domains

Validation Rules

  • At most one of: redacted, appended, or group parameters in top-level object

  • Dialog objects of type "incomplete" or "transfer" MUST NOT have body/url content

  • Dialog objects of other types SHOULD have body+encoding OR url+content_hash

  • External references (url) MUST include content_hash for integrity

  • Signed vCons MUST include x5c OR x5u in header for certificate chain

  • Party indices in dialog.parties must reference valid parties array elements

  • Dialog indices in analysis.dialog must reference valid dialog array elements

Last updated

Was this helpful?