0
# MIME and Validation
1

2
MIME bundle interfaces and validation functions for handling multimedia content in notebook cells, ensuring data integrity and format compliance with nbformat specifications.
3

4
## Capabilities
5

6
### MIME Bundle Interface
7

8
Interface for representing multimedia content with MIME type keys.
9

10
```typescript { .api }
11
/**
12
 * A mime-type keyed dictionary of data for multimedia content
13
 */
14
interface IMimeBundle extends PartialJSONObject {
15
  /** MIME type mapped to content data */
16
  [key: string]: MultilineString | PartialJSONObject;
17
}
18
```
19

20
**Usage Example:**
21

22
```typescript
23
import { IMimeBundle, MultilineString } from "@jupyterlab/nbformat";
24

25
// Rich display data with multiple MIME types
26
const richOutput: IMimeBundle = {
27
  'text/plain': 'A simple plot',
28
  'text/html': '<div>Interactive plot here</div>',
29
  'image/png': 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==',
30
  'application/json': {
31
    'data': [1, 2, 3, 4, 5],
32
    'labels': ['A', 'B', 'C', 'D', 'E']
33
  }
34
};
35

36
// Text content as array of lines
37
const multilineContent: IMimeBundle = {
38
  'text/plain': [
39
    'Line 1 of output',
40
    'Line 2 of output', 
41
    'Line 3 of output'
42
  ]
43
};
44
```
45

46
### Attachments Interface
47

48
Interface for media attachments in cells, such as inline images.
49

50
```typescript { .api }
51
/**
52
 * Media attachments (e.g. inline images) keyed by attachment name
53
 */
54
interface IAttachments {
55
  /** Attachment name mapped to MIME bundle data */
56
  [key: string]: IMimeBundle | undefined;
57
}
58
```
59

60
**Usage Example:**
61

62
```typescript
63
import { IAttachments, IMimeBundle } from "@jupyterlab/nbformat";
64

65
const attachments: IAttachments = {
66
  'logo.png': {
67
    'image/png': 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg=='
68
  },
69
  'chart.svg': {
70
    'image/svg+xml': '<svg width="100" height="100"><circle cx="50" cy="50" r="40"/></svg>'
71
  }
72
};
73
```
74

75
### MIME Validation Function
76

77
Function to validate MIME type and value pairs for data integrity.
78

79
```typescript { .api }
80
/**
81
 * Validate a mime type/value pair for format compliance
82
 * 
83
 * @param type - The mimetype name (e.g., 'text/plain', 'application/json')
84
 * @param value - The value associated with the type
85
 * @returns Whether the type/value pair are valid according to nbformat rules
86
 */
87
function validateMimeValue(
88
  type: string,
89
  value: MultilineString | PartialJSONObject
90
): boolean;
91
```
92

93
**Usage Examples:**
94

95
```typescript
96
import { validateMimeValue } from "@jupyterlab/nbformat";
97

98
// Valid cases
99
console.log(validateMimeValue('text/plain', 'Hello world')); // true
100
console.log(validateMimeValue('text/plain', ['Line 1', 'Line 2'])); // true
101
console.log(validateMimeValue('application/json', { key: 'value' })); // true
102
console.log(validateMimeValue('application/vnd.custom+json', { data: 123 })); // true
103

104
// Invalid cases
105
console.log(validateMimeValue('application/json', 'string data')); // false - JSON type with string
106
console.log(validateMimeValue('text/plain', { key: 'value' })); // false - text type with object
107
console.log(validateMimeValue('application/json', ['array', 'data'])); // false - JSON type with array
108

109
// Validation logic
110
function isValidMimeBundle(bundle: IMimeBundle): boolean {
111
  return Object.entries(bundle).every(([mimeType, value]) => 
112
    validateMimeValue(mimeType, value)
113
  );
114
}
115

116
// Practical usage in output processing
117
function sanitizeDisplayData(data: IMimeBundle): IMimeBundle {
118
  const sanitized: IMimeBundle = {};
119
  
120
  Object.entries(data).forEach(([mimeType, value]) => {
121
    if (validateMimeValue(mimeType, value)) {
122
      sanitized[mimeType] = value;
123
    } else {
124
      console.warn(`Invalid MIME data for type ${mimeType}, skipping`);
125
    }
126
  });
127
  
128
  return sanitized;
129
}
130
```
131

132
### Validation Rules
133

134
The `validateMimeValue` function enforces the following rules:
135

136
1. **JSON MIME types** (`application/json`, `application/*+json`):
137
   - Must have object values (not strings or arrays)
138
   - Value must be a valid JSON object structure
139

140
2. **Text MIME types** (everything else):
141
   - Can have string values or string arrays
142
   - Cannot have object values
143

144
3. **Array validation**:
145
   - Only allowed for non-JSON MIME types
146
   - All array elements must be strings
147

148
**Advanced Validation Example:**
149

150
```typescript
151
import { validateMimeValue, IMimeBundle } from "@jupyterlab/nbformat";
152

153
class MimeValidator {
154
  /**
155
   * Validate an entire MIME bundle
156
   */
157
  static validateBundle(bundle: IMimeBundle): { valid: boolean; errors: string[] } {
158
    const errors: string[] = [];
159
    
160
    Object.entries(bundle).forEach(([mimeType, value]) => {
161
      if (!validateMimeValue(mimeType, value)) {
162
        errors.push(`Invalid value for MIME type '${mimeType}'`);
163
      }
164
    });
165
    
166
    return {
167
      valid: errors.length === 0,
168
      errors
169
    };
170
  }
171
  
172
  /**
173
   * Get the preferred MIME type from a bundle
174
   */
175
  static getPreferredMimeType(bundle: IMimeBundle): string | null {
176
    const preferenceOrder = [
177
      'application/json',
178
      'text/html', 
179
      'image/png',
180
      'image/jpeg',
181
      'text/plain'
182
    ];
183
    
184
    for (const mimeType of preferenceOrder) {
185
      if (mimeType in bundle && validateMimeValue(mimeType, bundle[mimeType])) {
186
        return mimeType;
187
      }
188
    }
189
    
190
    // Fallback to first valid MIME type
191
    const validTypes = Object.keys(bundle).filter(type => 
192
      validateMimeValue(type, bundle[type])
193
    );
194
    
195
    return validTypes.length > 0 ? validTypes[0] : null;
196
  }
197
}
198
```
199

200
## Types
201

202
```typescript { .api }
203
/**
204
 * A multiline string that can be a single string or array of strings
205
 */
206
type MultilineString = string | string[];
207
```