# vCon Specification

Complete reference for the IETF vCon (Virtual Conversation) standard.

## Overview

**Specification:** `draft-ietf-vcon-vcon-core-02`\
**Version:** 0.4.0\
**Working Group:** IETF vCon WG\
**Status:** Internet-Draft\
**Full Text:** [../background\_docs/draft-ietf-vcon-vcon-core-00.txt](https://github.com/vcon-dev/vcon-mcp/blob/main/background_docs/draft-ietf-vcon-vcon-core-00.txt) (v0.3.0 reference; v0.4.0 spec in project background-docs)

The vCon (Virtual Conversation) is a standard container format for storing conversation data in a structured, interoperable way. It supports voice calls, video meetings, text chats, emails, and other communication forms.

***

## Table of Contents

1. [Core Concepts](#core-concepts)
2. [Main vCon Object](#main-vcon-object)
3. [Party Object](#party-object)
4. [Dialog Object](#dialog-object)
5. [Attachment Object](#attachment-object)
6. [Analysis Object](#analysis-object)
7. [Encoding Options](#encoding-options)
8. [Extensions](#extensions)
9. [Security](#security)

***

## Core Concepts

### What is a vCon?

A vCon is a JSON object that contains:

* **Metadata** - Subject, timestamps, identifiers
* **Parties** - Participants in the conversation
* **Dialog** - The actual conversation content (audio, text, video)
* **Attachments** - Supporting files and metadata (tags, notes)
* **Analysis** - AI/ML analysis results (transcripts, sentiment, summary)

### Key Principles

1. **Self-contained** - All conversation data in one object
2. **Interoperable** - Standard format across systems
3. **Extensible** - Support for custom data via extensions
4. **Secure** - Support for signing (JWS) and encryption (JWE)
5. **Flexible** - Support for any communication medium

### Use Cases

* **Call recording storage** - Phone, video, web calls
* **Chat archival** - Text conversations, emails
* **Compliance** - GDPR, CCPA, HIPAA record keeping
* **Analytics** - Conversation intelligence and insights
* **Training** - Agent training data
* **Legal** - Dispute resolution and evidence

***

## Main vCon Object

**Section 4.1** of the IETF spec defines the top-level vCon structure.

### Required Fields

```typescript
interface VCon {
  // REQUIRED
  vcon: string;           // Version (e.g., "0.4.0")
  uuid: string;           // Unique identifier (RFC 4122)
  created_at: string;     // ISO 8601 timestamp
  parties: Party[];       // At least one party required
}
```

### Optional Fields

```typescript
interface VCon {
  // Optional metadata
  subject?: string;        // Conversation subject/title
  updated_at?: string;     // Last modification timestamp
  
  // Optional content
  dialog?: Dialog[];       // Conversation content
  analysis?: Analysis[];   // AI/ML analysis results
  attachments?: Attachment[]; // Files, notes, metadata
  
  // Optional advanced features
  redacted?: RedactedInfo;    // Redaction information
  amended?: AmendedInfo;      // Append-only chain info (v0.4.0; was 'appended')
  group?: GroupInfo[];        // Group conversation info
  
  // Extension support (Section 4.1.3, 4.1.4)
  extensions?: string[];      // Extension identifiers
  critical?: string[];        // Required extensions (v0.4.0; was 'must_support')
}
```

### Field Definitions

#### vcon (string, required)

Version of the vCon specification. Current version is `"0.4.0"`.

```json
{
  "vcon": "0.4.0"
}
```

#### uuid (string, required)

Unique identifier for the vCon. Must be a valid UUID per RFC 4122.

```json
{
  "uuid": "01234567-89ab-cdef-0123-456789abcdef"
}
```

#### created\_at (string, required)

When the vCon was created. ISO 8601 format with timezone.

```json
{
  "created_at": "2025-01-15T10:30:00Z"
}
```

#### subject (string, optional)

Human-readable title or subject for the conversation.

```json
{
  "subject": "Customer Support - Billing Inquiry"
}
```

#### extensions (array, optional)

**Section 4.1.3** - List of extension identifiers this vCon uses.

```json
{
  "extensions": ["privacy-v1", "custom-metadata"]
}
```

#### critical (array, optional)

**Section 4.1.4** - Extensions that MUST be understood to process this vCon. Renamed from `must_support` in v0.4.0.

```json
{
  "critical": ["required-extension-v1"]
}
```

***

## Party Object

**Section 4.2** - Represents a participant in the conversation.

### Structure

```typescript
interface Party {
  // Contact information
  tel?: string;           // Telephone number (E.164 format)
  stir?: string;          // STIR information
  mailto?: string;        // Email address
  name?: string;          // Display name
  
  // Identity
  sip?: string;           // SIP URI
  did?: string;           // Decentralized Identifier (Section 4.2.6)
  uuid?: string;          // UUID for this party (Section 4.2.12)
  validation?: string;    // Validation method/proof
  
  // Extended information
  jcard?: object;         // vCard in JSON format
  gmlpos?: string;        // Geographic location (GML)
  civicaddress?: object;  // Civic address
  timezone?: string;      // IANA timezone
}
```

### Examples

**Phone call participant:**

```json
{
  "tel": "+12025551234",
  "name": "John Smith"
}
```

**Email participant:**

```json
{
  "mailto": "customer@example.com",
  "name": "Alice Johnson"
}
```

**Full featured party:**

```json
{
  "name": "Bob Williams",
  "tel": "+12025555678",
  "mailto": "bob@company.com",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "timezone": "America/New_York"
}
```

***

## Dialog Object

**Section 4.3** - Represents conversation content.

### Required Fields

```typescript
interface Dialog {
  type: DialogType;  // REQUIRED
}

type DialogType = 'recording' | 'text' | 'transfer' | 'incomplete';
```

### Optional Fields

```typescript
interface Dialog {
  // Timing
  start?: string;      // ISO 8601 start time
  duration?: number;   // Duration in seconds
  
  // Participants
  parties?: number | number[] | (number | number[])[]; // Party indexes
  originator?: number; // Party index of originator
  
  // Content
  mediatype?: string;  // Media type (v0.4.0; was 'mimetype')
  filename?: string;   // Filename
  body?: string;       // Inline content
  encoding?: Encoding; // Content encoding
  url?: string;        // External URL
  
  // Metadata
  content_hash?: string | string[]; // Content hash
  disposition?: Disposition;  // Call disposition
  session_id?: { local: string; remote: string }; // Session identifier (v0.4.0; was string)
  application?: string;       // Application name (Section 4.3.13)
  message_id?: string;        // Message ID (Section 4.3.14)
}

type Encoding = 'none' | 'base64url' | 'json';
type Disposition = 'no-answer' | 'congestion' | 'failed' | 'busy' | 
                   'hung-up' | 'voicemail-no-message';
```

### Dialog Types

#### recording

Audio or video recording of the conversation.

```json
{
  "type": "recording",
  "start": "2025-01-15T10:30:00Z",
  "duration": 125.4,
  "parties": [0, 1],
  "originator": 0,
  "mediatype": "audio/wav",
  "filename": "call-recording.wav",
  "url": "https://storage.example.com/recording.wav"
}
```

#### text

Text-based conversation (chat, SMS, email body).

```json
{
  "type": "text",
  "start": "2025-01-15T10:32:15Z",
  "parties": 0,
  "body": "Hello, I need help with my account.",
  "encoding": "none"
}
```

#### transfer

Reference to another vCon (call transfer, forwarding).

```json
{
  "type": "transfer",
  "start": "2025-01-15T10:35:00Z",
  "parties": [0, 2],
  "body": "01234567-89ab-cdef-0123-456789abcdef",
  "encoding": "none"
}
```

#### incomplete

Partial or failed conversation.

```json
{
  "type": "incomplete",
  "start": "2025-01-15T10:30:00Z",
  "disposition": "no-answer",
  "parties": [0, 1]
}
```

***

## Attachment Object

**Section 4.4** - Supporting files and metadata.

### Structure

```typescript
interface Attachment {
  // Timing and context
  type?: string;       // Attachment type (custom)
  start?: string;      // ISO 8601 timestamp
  party?: number;      // Associated party index
  dialog?: number;     // Associated dialog index
  
  // Content
  mediatype?: string;  // Media type (v0.4.0; was 'mimetype')
  filename?: string;   // Filename
  body?: string;       // Inline content
  encoding?: Encoding; // Content encoding
  url?: string;        // External URL
  
  // Verification
  content_hash?: string | string[]; // Content hash
}
```

### Common Attachment Types

#### Tags Attachment

Special attachment type for key-value metadata (used by search).

```json
{
  "type": "tags",
  "encoding": "json",
  "body": "[\"department:support\", \"priority:high\", \"status:open\"]"
}
```

#### Document Attachment

Supporting document or file.

```json
{
  "type": "document",
  "start": "2025-01-15T10:30:00Z",
  "mimetype": "application/pdf",
  "filename": "invoice.pdf",
  "url": "https://storage.example.com/invoice.pdf"
}
```

#### Note Attachment

Human-added notes or annotations.

```json
{
  "type": "note",
  "party": 1,
  "start": "2025-01-15T10:35:00Z",
  "body": "Customer was satisfied with resolution",
  "encoding": "none"
}
```

***

## Analysis Object

**Section 4.5** - AI/ML analysis results.

### Required Fields

```typescript
interface Analysis {
  type: string;    // REQUIRED - Analysis type
  vendor: string;  // REQUIRED - Vendor who produced this (Section 4.5.5)
}
```

### Optional Fields

```typescript
interface Analysis {
  // Context
  dialog?: number | number[]; // Associated dialog(s)
  
  // Metadata
  product?: string;   // Specific product/model used
  schema?: string;    // Schema identifier (Section 4.5.6) ⚠️ NOT schema_version
  
  // Content
  mediatype?: string; // Media type (v0.4.0; was 'mimetype')
  filename?: string;  // Filename
  body?: string;      // Analysis result (Section 4.5.7) ⚠️ STRING not object
  encoding?: Encoding; // Content encoding
  url?: string;       // External URL
  
  // Verification
  content_hash?: string | string[]; // Content hash
}
```

### Critical Corrections

⚠️ **Common Mistakes:**

1. Using `schema_version` - WRONG. Use `schema` (Section 4.5.6)
2. Making `vendor` optional - WRONG. It's REQUIRED (Section 4.5.5)
3. Using `object` type for `body` - WRONG. Use `string` (Section 4.5.7)

### Examples

**Transcript analysis:**

```json
{
  "type": "transcript",
  "vendor": "Deepgram",
  "product": "Nova-2",
  "schema": "v1",
  "dialog": 0,
  "body": "Hello, I need help with my account. Sure, I can help...",
  "encoding": "none"
}
```

**Sentiment analysis:**

```json
{
  "type": "sentiment",
  "vendor": "OpenAI",
  "product": "gpt-4",
  "dialog": [0, 1, 2],
  "body": "{\"sentiment\": \"positive\", \"score\": 0.85}",
  "encoding": "json"
}
```

**Summary:**

```json
{
  "type": "summary",
  "vendor": "CustomAI",
  "schema": "summary-v2",
  "body": "Customer inquired about billing. Issue resolved by providing refund.",
  "encoding": "none"
}
```

***

## Encoding Options

**Section 4.3.6, 4.4.7, 4.5.8** - Content encoding types.

### none

Raw text content, no encoding.

```json
{
  "body": "Plain text content",
  "encoding": "none"
}
```

### base64url

Base64 URL-safe encoding (RFC 4648).

```json
{
  "body": "SGVsbG8gV29ybGQh",
  "encoding": "base64url"
}
```

### json

JSON-formatted content.

```json
{
  "body": "{\"key\": \"value\"}",
  "encoding": "json"
}
```

### Important

⚠️ **NO DEFAULT VALUES** - `encoding` field should NOT have a default value in database schema or type definitions. It must be explicitly set.

***

## Extensions

**Section 4.1.3, 4.1.4** - Supporting custom functionality.

### extensions Array

List of extension identifiers used in this vCon.

```json
{
  "extensions": [
    "privacy-redaction-v1",
    "custom-analytics-v2"
  ]
}
```

### critical Array

Extensions that MUST be understood to process this vCon correctly. Renamed from `must_support` in v0.4.0.

```json
{
  "critical": [
    "required-extension-v1"
  ]
}
```

**Processing Rules:**

1. If a vCon has `critical` entries you don't understand, reject it
2. If a vCon has `extensions` you don't understand, you MAY process it
3. Always preserve unrecognized extension data

***

## Security

### Signing (JWS)

vCons can be signed using JSON Web Signature (JWS):

```json
{
  "payload": "base64url(vcon_json)",
  "signatures": [{
    "protected": "base64url(header)",
    "signature": "base64url(signature)"
  }]
}
```

### Encryption (JWE)

vCons can be encrypted using JSON Web Encryption (JWE):

```json
{
  "protected": "base64url(header)",
  "encrypted_key": "base64url(key)",
  "iv": "base64url(iv)",
  "ciphertext": "base64url(encrypted_vcon)",
  "tag": "base64url(tag)"
}
```

### Content Hashing

All content fields (body, url) can have `content_hash` for verification:

```json
{
  "body": "content",
  "content_hash": "sha256:abc123..."
}
```

***

## Complete Example

**Minimal vCon:**

```json
{
  "vcon": "0.4.0",
  "uuid": "01234567-89ab-cdef-0123-456789abcdef",
  "created_at": "2025-01-15T10:30:00Z",
  "parties": [
    {
      "name": "Alice",
      "mailto": "alice@example.com"
    }
  ]
}
```

**Full-featured vCon:**

```json
{
  "vcon": "0.4.0",
  "uuid": "01234567-89ab-cdef-0123-456789abcdef",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:35:00Z",
  "subject": "Customer Support Call - Billing Issue",
  "parties": [
    {
      "tel": "+12025551234",
      "name": "Customer",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    {
      "tel": "+12025555678",
      "name": "Agent Sarah",
      "uuid": "234e5678-e89b-12d3-a456-426614174001"
    }
  ],
  "dialog": [
    {
      "type": "recording",
      "start": "2025-01-15T10:30:00Z",
      "duration": 180,
      "parties": [0, 1],
      "originator": 0,
      "mediatype": "audio/wav",
      "url": "https://storage.example.com/call.wav"
    },
    {
      "type": "text",
      "start": "2025-01-15T10:30:05Z",
      "parties": 0,
      "body": "I was charged twice this month",
      "encoding": "none"
    }
  ],
  "analysis": [
    {
      "type": "transcript",
      "vendor": "Deepgram",
      "product": "Nova-2",
      "dialog": 0,
      "body": "Customer: I was charged twice... Agent: I can help...",
      "encoding": "none"
    },
    {
      "type": "summary",
      "vendor": "OpenAI",
      "product": "gpt-4",
      "body": "Customer reported duplicate charge. Refund processed.",
      "encoding": "none"
    }
  ],
  "attachments": [
    {
      "type": "tags",
      "encoding": "json",
      "body": "[\"department:billing\", \"status:resolved\"]"
    }
  ]
}
```

***

## Validation Rules

### Required Validations

1. ✅ `vcon` field must be `"0.4.0"`
2. ✅ `uuid` must be valid UUID format
3. ✅ `created_at` must be ISO 8601 timestamp
4. ✅ `parties` array must have at least one party
5. ✅ Dialog `type` must be one of 4 valid types
6. ✅ Analysis `vendor` must be provided

### Reference Validations

1. ✅ Party indexes in `dialog.parties` must be valid
2. ✅ Dialog indexes in `analysis.dialog` must be valid
3. ✅ Party indexes in `attachment.party` must be valid
4. ✅ Dialog indexes in `attachment.dialog` must be valid

### Format Validations

1. ✅ Timestamps must be ISO 8601 with timezone
2. ✅ UUIDs must be RFC 4122 format
3. ✅ `encoding` must be one of: `none`, `base64url`, `json`
4. ✅ Phone numbers should be E.164 format

***

## Additional Resources

* **Full Specification:** [../background\_docs/draft-ietf-vcon-vcon-core-00.txt](https://github.com/vcon-dev/vcon-mcp/blob/main/background_docs/draft-ietf-vcon-vcon-core-00.txt)
* **Privacy Primer:** [../background\_docs/draft-ietf-vcon-privacy-primer-00.txt](https://github.com/vcon-dev/vcon-mcp/blob/main/background_docs/draft-ietf-vcon-privacy-primer-00.txt)
* **IETF Working Group:** <https://datatracker.ietf.org/wg/vcon/>
* **Quick Reference:** [QUICK\_REFERENCE.md](https://github.com/vcon-dev/vcon-mcp/blob/main/docs/reference/QUICK_REFERENCE.md)
* **Database Schema:** [CORRECTED\_SCHEMA.md](https://github.com/vcon-dev/vcon-mcp/blob/main/docs/reference/CORRECTED_SCHEMA.md)

***

*This reference is based on draft-ietf-vcon-vcon-core-02 (v0.4.0) and reflects all corrections identified in* [*IMPLEMENTATION\_CORRECTIONS.md*](https://github.com/vcon-dev/vcon-mcp/blob/main/docs/reference/IMPLEMENTATION_CORRECTIONS.md)*.*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mcp.conserver.io/reference/vcon-spec.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.