0
# YAML Type Definitions
1

2
Comprehensive type system for generating YAML documentation compatible with DocFX and Office Add-ins documentation platforms. These types define the structure and metadata for API documentation in YAML format.
3

4
## Capabilities
5

6
### YAML Format Types
7

8
Core format selection and configuration types.
9

10
```typescript { .api }
11
type YamlFormat = 'udp' | 'sdp';
12

13
type YamlTypeId = 
14
  | 'Class'
15
  | 'Constructor' 
16
  | 'Enum'
17
  | 'Field'
18
  | 'Function'
19
  | 'Interface'
20
  | 'Method'
21
  | 'Namespace'
22
  | 'Package'
23
  | 'Property'
24
  | 'TypeAlias'
25
  | 'Variable';
26

27
type YamlDevLangs = 'javascript' | 'typescript' | 'nodejs';
28
```
29

30
### API File Structure
31

32
Main YAML file structure for API documentation with complete metadata.
33

34
```typescript { .api }
35
interface IYamlApiFile {
36
  /**
37
   * Array of API items documented in this file
38
   */
39
  items: IYamlItem[];
40
  
41
  /**
42
   * Documentation references and cross-links
43
   */
44
  references?: IYamlReference[];
45
  
46
  /**
47
   * File metadata and generation information
48
   */
49
  metadata?: {
50
    generator: string;
51
    generatorVersion: string;
52
    generatedDate: string;
53
  };
54
}
55

56
interface IYamlItem {
57
  /**
58
   * Unique identifier for this API item
59
   */
60
  uid: string;
61
  
62
  /**
63
   * Display name of the API item
64
   */
65
  name: string;
66
  
67
  /**
68
   * Full name including namespace/package context
69
   */
70
  fullName?: string;
71
  
72
  /**
73
   * Type of API item (Class, Method, Property, etc.)
74
   */
75
  type: YamlTypeId;
76
  
77
  /**
78
   * Programming language context
79
   */
80
  langs?: YamlDevLangs[];
81
  
82
  /**
83
   * Package or namespace containing this item
84
   */
85
  package?: string;
86
  
87
  /**
88
   * Summary documentation text
89
   */
90
  summary?: string;
91
  
92
  /**
93
   * Detailed remarks and additional documentation
94
   */
95
  remarks?: string;
96
  
97
  /**
98
   * Usage examples in code
99
   */
100
  example?: string;
101
  
102
  /**
103
   * Syntax information for this API item
104
   */
105
  syntax?: IYamlSyntax;
106
  
107
  /**
108
   * Inheritance hierarchy information
109
   */
110
  inheritance?: IYamlInheritanceTree[];
111
  
112
  /**
113
   * Child items (methods, properties, etc.)
114
   */
115
  children?: string[];
116
  
117
  /**
118
   * Source code location information
119
   */
120
  source?: IYamlSource;
121
  
122
  /**
123
   * Deprecation notice if applicable
124
   */
125
  deprecated?: IYamlDeprecatedNotice;
126
  
127
  /**
128
   * Exception information for methods
129
   */
130
  exceptions?: IYamlException[];
131
}
132
```
133

134
### Syntax Information
135

136
Detailed syntax and signature information for API items.
137

138
```typescript { .api }
139
interface IYamlSyntax {
140
  /**
141
   * Code signature or declaration
142
   */
143
  content?: string;
144
  
145
  /**
146
   * Parameters for functions and methods
147
   */
148
  parameters?: IYamlParameter[];
149
  
150
  /**
151
   * Return value information
152
   */
153
  return?: IYamlReturn;
154
  
155
  /**
156
   * Type parameters for generic types
157
   */
158
  typeParameters?: IYamlParameter[];
159
}
160

161
interface IYamlParameter {
162
  /**
163
   * Parameter identifier
164
   */
165
  id: string;
166
  
167
  /**
168
   * Parameter type information
169
   */
170
  type?: string;
171
  
172
  /**
173
   * Parameter description
174
   */
175
  description?: string;
176
  
177
  /**
178
   * Whether parameter is optional
179
   */
180
  optional?: boolean;
181
  
182
  /**
183
   * Default value if any
184
   */
185
  defaultValue?: string;
186
}
187

188
interface IYamlReturn {
189
  /**
190
   * Return type information
191
   */
192
  type?: string;
193
  
194
  /**
195
   * Description of return value
196
   */
197
  description?: string;
198
}
199
```
200

201
### Reference and Link System
202

203
Cross-reference and linking system for API documentation.
204

205
```typescript { .api }
206
interface IYamlReference {
207
  /**
208
   * Unique identifier for the referenced item
209
   */
210
  uid: string;
211
  
212
  /**
213
   * Display name of referenced item
214
   */
215
  name: string;
216
  
217
  /**
218
   * Full name with context
219
   */
220
  fullName?: string;
221
  
222
  /**
223
   * Type of referenced item
224
   */
225
  type?: YamlTypeId;
226
  
227
  /**
228
   * Reference specifications
229
   */
230
  spec?: IYamlReferenceSpec[];
231
}
232

233
interface IYamlReferenceSpec {
234
  /**
235
   * Reference UID
236
   */
237
  uid: string;
238
  
239
  /**
240
   * Display name in reference context
241
   */
242
  name: string;
243
  
244
  /**
245
   * Full qualified name
246
   */
247
  fullName?: string;
248
}
249

250
interface IYamlLink {
251
  /**
252
   * Link URL or reference
253
   */
254
  href?: string;
255
  
256
  /**
257
   * Link display text
258
   */
259
  text?: string;
260
  
261
  /**
262
   * Link type (external, internal, etc.)
263
   */
264
  type?: 'internal' | 'external';
265
}
266
```
267

268
### Source Location Information
269

270
Source code location and repository information.
271

272
```typescript { .api }
273
interface IYamlSource {
274
  /**
275
   * Source file path
276
   */
277
  path?: string;
278
  
279
  /**
280
   * Starting line number
281
   */
282
  startLine?: number;
283
  
284
  /**
285
   * Remote repository information
286
   */
287
  remote?: IYamlRemote;
288
}
289

290
interface IYamlRemote {
291
  /**
292
   * Repository URL
293
   */
294
  repo: string;
295
  
296
  /**
297
   * Branch or commit reference
298
   */
299
  branch?: string;
300
  
301
  /**
302
   * File path within repository
303
   */
304
  path?: string;
305
}
306
```
307

308
### Inheritance and Type Hierarchy
309

310
Type inheritance and relationship information.
311

312
```typescript { .api }
313
interface IYamlInheritanceTree {
314
  /**
315
   * Type information for inheritance relationship
316
   */
317
  type?: string;
318
  
319
  /**
320
   * Reference UID for inherited type
321
   */
322
  uid?: string;
323
  
324
  /**
325
   * Inheritance level (0 = direct parent)
326
   */
327
  level?: number;
328
}
329
```
330

331
### Exception Documentation
332

333
Exception and error information for methods and functions.
334

335
```typescript { .api }
336
interface IYamlException {
337
  /**
338
   * Exception type name
339
   */
340
  type?: string;
341
  
342
  /**
343
   * Exception type UID reference
344
   */
345
  uid?: string;
346
  
347
  /**
348
   * Description of when this exception is thrown
349
   */
350
  description?: string;
351
}
352

353
interface IYamlDeprecatedNotice {
354
  /**
355
   * Deprecation message
356
   */
357
  message?: string;
358
  
359
  /**
360
   * Version when deprecated
361
   */
362
  version?: string;
363
  
364
  /**
365
   * Replacement recommendation
366
   */
367
  replacement?: string;
368
}
369
```
370

371
### Table of Contents Structure
372

373
YAML table of contents for navigation and organization.
374

375
```typescript { .api }
376
interface IYamlTocFile {
377
  /**
378
   * Array of top-level TOC items
379
   */
380
  items?: IYamlTocItem[];
381
  
382
  /**
383
   * Metadata for the TOC file
384
   */
385
  metadata?: {
386
    tocTitle?: string;
387
    tocDescription?: string;
388
  };
389
}
390

391
interface IYamlTocItem {
392
  /**
393
   * Display name in table of contents
394
   */
395
  name?: string;
396
  
397
  /**
398
   * Reference UID for this item
399
   */
400
  uid?: string;
401
  
402
  /**
403
   * Direct link href (alternative to uid)
404
   */
405
  href?: string;
406
  
407
  /**
408
   * Child items in the hierarchy
409
   */
410
  items?: IYamlTocItem[];
411
  
412
  /**
413
   * Whether this item is expanded by default
414
   */
415
  expanded?: boolean;
416
}
417
```
418

419
## SDP (Structured Data Platform) Types
420

421
Enhanced type system for the newer SDP YAML format with improved structure and metadata.
422

423
### SDP Model Types
424

425
```typescript { .api }
426
type CommonYamlModel = {
427
  /**
428
   * Unique identifier
429
   */
430
  uid: string;
431
  
432
  /**
433
   * Display name
434
   */
435
  name: string;
436
  
437
  /**
438
   * Item type
439
   */
440
  type: YamlTypeId;
441
  
442
  /**
443
   * Summary documentation
444
   */
445
  summary?: string;
446
  
447
  /**
448
   * Syntax information
449
   */
450
  syntax?: ISyntax;
451
  
452
  /**
453
   * Source location
454
   */
455
  source?: IYamlSource;
456
};
457

458
type PackageYamlModel = CommonYamlModel & {
459
  type: 'Package';
460
  /**
461
   * Package version
462
   */
463
  version?: string;
464
  
465
  /**
466
   * Package description
467
   */
468
  description?: string;
469
  
470
  /**
471
   * Child namespaces and classes
472
   */
473
  children?: string[];
474
};
475

476
type FunctionYamlModel = CommonYamlModel & {
477
  type: 'Function';
478
  /**
479
   * Function parameters
480
   */
481
  parameters?: IYamlParameter[];
482
  
483
  /**
484
   * Return type information
485
   */
486
  returns?: IYamlReturn;
487
  
488
  /**
489
   * Possible exceptions
490
   */
491
  exceptions?: IException[];
492
};
493

494
type TypeAliasYamlModel = CommonYamlModel & {
495
  type: 'TypeAlias';
496
  /**
497
   * Type definition
498
   */
499
  typeDefinition?: IType;
500
};
501

502
type EnumYamlModel = CommonYamlModel & {
503
  type: 'Enum';
504
  /**
505
   * Enum members
506
   */
507
  fields?: FieldYamlModel[];
508
};
509

510
type FieldYamlModel = CommonYamlModel & {
511
  type: 'Field';
512
  /**
513
   * Field value (for enum members)
514
   */
515
  value?: string | number;
516
};
517
```
518

519
### SDP Type System
520

521
Enhanced type representation for SDP format.
522

523
```typescript { .api }
524
interface IType {
525
  /**
526
   * Type name or identifier
527
   */
528
  name?: string;
529
  
530
  /**
531
   * Type kind (primitive, reference, union, etc.)
532
   */
533
  kind?: 'primitive' | 'reference' | 'union' | 'intersection' | 'generic' | 'reflected';
534
  
535
  /**
536
   * Type arguments for generic types
537
   */
538
  typeArguments?: IType[];
539
  
540
  /**
541
   * Union type members
542
   */
543
  unionTypes?: IUnionType[];
544
  
545
  /**
546
   * Intersection type members  
547
   */
548
  intersectionTypes?: IIntersectionType[];
549
}
550

551
interface IUnionType {
552
  /**
553
   * Union member type
554
   */
555
  type: IType;
556
  
557
  /**
558
   * Optional discriminator value
559
   */
560
  discriminator?: string;
561
}
562

563
interface IIntersectionType {
564
  /**
565
   * Intersection member type
566
   */
567
  type: IType;
568
}
569

570
interface IGenericType {
571
  /**
572
   * Generic type constraint
573
   */
574
  constraint?: IType;
575
  
576
  /**
577
   * Default type argument
578
   */
579
  default?: IType;
580
}
581

582
interface IReflectedType {
583
  /**
584
   * Reflected type structure
585
   */
586
  declaration?: {
587
    signatures?: ISyntax[];
588
    children?: IType[];
589
  };
590
}
591
```
592

593
### SDP Syntax Information
594

595
Enhanced syntax representation for SDP format.
596

597
```typescript { .api }
598
interface ISyntax {
599
  /**
600
   * Syntax content/signature
601
   */
602
  content?: string;
603
  
604
  /**
605
   * Parameters with enhanced type information
606
   */
607
  parameters?: IYamlParameter[];
608
  
609
  /**
610
   * Return type with detailed information
611
   */
612
  return?: {
613
    type?: IType;
614
    description?: string;
615
  };
616
  
617
  /**
618
   * Type parameters for generic signatures
619
   */
620
  typeParameters?: Array<{
621
    name: string;
622
    constraint?: IType;
623
    default?: IType;
624
    description?: string;
625
  }>;
626
}
627

628
interface IException {
629
  /**
630
   * Exception type
631
   */
632
  type?: IType;
633
  
634
  /**
635
   * Exception description
636
   */
637
  description?: string;
638
  
639
  /**
640
   * Conditions when thrown
641
   */
642
  condition?: string;
643
}
644
```
645

646
## Usage Examples
647

648
### Basic YAML Generation
649

650
```typescript
651
import { IYamlApiFile, IYamlItem } from "@microsoft/api-documenter/lib/yaml/IYamlApiFile";
652

653
// Create YAML API file structure
654
const yamlFile: IYamlApiFile = {
655
  items: [
656
    {
657
      uid: "mypackage.MyClass",
658
      name: "MyClass", 
659
      type: "Class",
660
      langs: ["typescript"],
661
      package: "mypackage",
662
      summary: "A sample class for demonstration",
663
      syntax: {
664
        content: "class MyClass",
665
        parameters: []
666
      },
667
      children: ["mypackage.MyClass.method1"]
668
    }
669
  ],
670
  metadata: {
671
    generator: "api-documenter",
672
    generatorVersion: "7.26.32",
673
    generatedDate: new Date().toISOString()
674
  }
675
};
676
```
677

678
### TOC Generation
679

680
```typescript
681
import { IYamlTocFile, IYamlTocItem } from "@microsoft/api-documenter/lib/yaml/IYamlTocFile";
682

683
// Create table of contents
684
const tocFile: IYamlTocFile = {
685
  items: [
686
    {
687
      name: "API Reference",
688
      uid: "mypackage",
689
      expanded: true,
690
      items: [
691
        {
692
          name: "Classes",
693
          items: [
694
            {
695
              name: "MyClass",
696
              uid: "mypackage.MyClass"
697
            }
698
          ]
699
        }
700
      ]
701
    }
702
  ],
703
  metadata: {
704
    tocTitle: "My Package API",
705
    tocDescription: "Complete API reference for My Package"
706
  }
707
};
708
```
709

710
## Format Conversion
711

712
### UDP to SDP Conversion
713

714
```typescript
715
import { convertUDPYamlToSDP } from "@microsoft/api-documenter/lib/utils/ToSdpConvertHelper";
716

717
// Convert UDP format to SDP format
718
const udpYaml = {
719
  // UDP format structure
720
};
721

722
const sdpYaml = convertUDPYamlToSDP(udpYaml);
723
```
724

725
This conversion utility transforms legacy UDP (Universal DocFX Platform) format YAML to the newer SDP (Structured Data Platform) format with enhanced type information and improved structure.