0
# Assembly Specification
1

2
The jsii assembly specification defines the complete schema and interfaces for .jsii assembly files. These assemblies contain metadata about TypeScript code that enables cross-language compatibility and code generation.
3

4
## Capabilities
5

6
### Assembly Interface
7

8
The main interface representing a complete jsii assembly with all type definitions and metadata.
9

10
```typescript { .api }
11
/**
12
 * Main interface for JSII assembly specification
13
 */
14
interface Assembly extends AssemblyConfiguration, Documentable, ReadMeContainer {
15
  /** Schema version of this assembly (always 'jsii/0.10.0') */
16
  schema: SchemaVersion.LATEST;
17
  /** Assembly name */
18
  name: string;
19
  /** Assembly description (required for some package managers) */
20
  description: string;
21
  /** Assembly version */
22
  version: string;
23
  /** Homepage URL (required) */
24
  homepage: string;
25
  /** Repository information (required) */
26
  repository: {
27
    /** Repository type (git, svn, etc.) */
28
    type: string;
29
    /** Repository URL */
30
    url: string;
31
    /** Directory within repo for monorepos */
32
    directory?: string;
33
  };
34
  /** Main author information (required) */
35
  author: Person;
36
  /** Additional contributors */
37
  contributors?: Person[];
38
  /** Assembly fingerprint for validation (required) */
39
  fingerprint: string;
40
  /** jsii compiler version used to produce this assembly */
41
  jsiiVersion: string;
42
  /** SPDX license identifier (required) */
43
  license: string;
44
  /** Arbitrary metadata key-value pairs */
45
  metadata?: { [key: string]: any };
46
  /** Keywords for package discovery */
47
  keywords?: string[];
48
  /** Direct dependencies on other assemblies */
49
  dependencies?: { [assembly: string]: string };
50
  /** Target configuration for dependency closure */
51
  dependencyClosure?: { [assembly: string]: DependencyConfiguration };
52
  /** Bundled dependency versions */
53
  bundled?: { [module: string]: string };
54
  /** Type definitions indexed by fully qualified name */
55
  types?: { [fqn: string]: Type };
56
  /** Binary scripts */
57
  bin?: { readonly [script: string]: string };
58
  /** Features used in this assembly */
59
  usedFeatures?: JsiiFeature[];
60
}
61

62
/**
63
 * Configuration shared between assemblies
64
 */
65
interface AssemblyConfiguration extends Targetable {
66
  /** Submodules declared in this assembly */
67
  submodules?: { [fqn: string]: Submodule };
68
}
69

70
/**
71
 * Configuration for assembly dependencies
72
 */
73
interface DependencyConfiguration extends Targetable {
74
  /** Submodule dependencies */
75
  submodules?: { [fqn: string]: Targetable };
76
}
77
```
78

79
### Type System
80

81
Core interfaces for representing different types of TypeScript constructs in jsii assemblies.
82

83
```typescript { .api }
84
/**
85
 * Base interface for all type definitions
86
 */
87
interface TypeBase extends Documentable, SourceLocatable {
88
  /** Fully qualified name */
89
  fqn: FQN;
90
  /** Assembly name containing this type */
91
  assembly: string;
92
  /** Type namespace/module */
93
  namespace?: string;
94
  /** Simple type name */
95
  name?: string;
96
  /** Source location */
97
  locationInModule?: SourceLocation;
98
  /** Whether type is abstract */
99
  abstract?: boolean;
100
  /** Deprecation information */
101
  deprecated?: string | boolean;
102
  /** API stability level */
103
  stability?: Stability;
104
}
105

106
/**
107
 * Union type for all type definitions
108
 */
109
type Type = ClassType | InterfaceType | EnumType;
110

111
/**
112
 * Enumeration of type kinds
113
 */
114
enum TypeKind {
115
  Class = "class",
116
  Enum = "enum",
117
  Interface = "interface"
118
}
119

120
/**
121
 * Represents a class type
122
 */
123
interface ClassType extends TypeBase {
124
  kind: TypeKind.Class;
125
  /** Whether class is abstract */
126
  abstract?: boolean;
127
  /** Base class FQN */
128
  base?: string;
129
  /** Implemented interface FQNs */
130
  interfaces?: string[];
131
  /** Constructor definition */
132
  initializer?: Initializer;
133
  /** Class properties */
134
  properties?: Property[];
135
  /** Class methods */
136
  methods?: Method[];
137
}
138

139
/**
140
 * Represents an interface type  
141
 */
142
interface InterfaceType extends TypeBase {
143
  kind: TypeKind.Interface;
144
  /** Interface properties */
145
  properties?: Property[];
146
  /** Interface methods */
147
  methods?: Method[];
148
  /** Whether this is a data-only interface */
149
  datatype?: boolean;
150
  /** Extended interface FQNs */
151
  interfaces?: string[];
152
}
153

154
/**
155
 * Represents an enumeration type
156
 */
157
interface EnumType extends TypeBase {
158
  kind: TypeKind.Enum;
159
  /** Enumeration members */
160
  members: EnumMember[];
161
}
162

163
/**
164
 * Enumeration member definition
165
 */
166
interface EnumMember extends Documentable {
167
  /** Member name */
168
  name: string;
169
  /** Member value */
170
  value?: string | number;
171
}
172
```
173

174
### Type References
175

176
System for referencing types within assemblies, supporting primitives, collections, and complex type relationships.
177

178
```typescript { .api }
179
/**
180
 * Reference to any type - primitive, collection, or named type
181
 */
182
type TypeReference = 
183
  | PrimitiveTypeReference 
184
  | NamedTypeReference 
185
  | CollectionTypeReference 
186
  | UnionTypeReference 
187
  | IntersectionTypeReference;
188

189
/**
190
 * Reference to a primitive type
191
 */
192
interface PrimitiveTypeReference {
193
  primitive: PrimitiveType;
194
}
195

196
/**
197
 * Reference to a named type by FQN
198
 */
199
interface NamedTypeReference {
200
  fqn: FQN;
201
}
202

203
/**
204
 * Reference to a collection type (Array or Map)
205
 */
206
interface CollectionTypeReference {
207
  collection: {
208
    kind: CollectionKind;
209
    elementtype: TypeReference;
210
  };
211
}
212

213
/**
214
 * Reference to a union of multiple types
215
 */
216
interface UnionTypeReference {
217
  union: {
218
    types: TypeReference[];
219
  };
220
}
221

222
/**
223
 * Reference to an intersection of multiple types
224
 */
225
interface IntersectionTypeReference {
226
  intersection: {
227
    types: TypeReference[];
228
  };
229
}
230

231
/**
232
 * Primitive type enumeration
233
 */
234
enum PrimitiveType {
235
  Date = "date",
236
  String = "string", 
237
  Number = "number",
238
  Boolean = "boolean",
239
  Json = "json",
240
  Any = "any"
241
}
242

243
/**
244
 * Collection type enumeration
245
 */
246
enum CollectionKind {
247
  Array = "array",
248
  Map = "map"
249
}
250

251
/**
252
 * Canonical representation of the 'any' type
253
 */
254
const CANONICAL_ANY: PrimitiveTypeReference = { primitive: PrimitiveType.Any };
255
```
256

257
### Members and Callables
258

259
Interfaces for class and interface members including properties, methods, and constructors.
260

261
```typescript { .api }
262
/**
263
 * Represents a property on a class or interface
264
 */
265
interface Property extends TypeMember, OptionalValue {
266
  /** Property name */
267
  name: string;
268
  /** Property type reference */
269
  type: TypeReference;
270
  /** Whether property is static */
271
  static?: boolean;
272
  /** Property getter/setter access */
273
  immutable?: boolean;
274
  /** Whether property can be overridden */
275
  override?: boolean;
276
  /** Protected access modifier */
277
  protected?: boolean;
278
  /** Const qualifier */
279
  const?: boolean;
280
}
281

282
/**
283
 * Base interface for callable members (methods and constructors)
284
 */
285
interface Callable extends Documentable, SourceLocatable {
286
  /** Method parameters */
287
  parameters?: Parameter[];
288
  /** Whether method can be overridden */
289
  override?: boolean;  
290
  /** Whether method is protected */
291
  protected?: boolean;
292
  /** Whether method is variadic */
293
  variadic?: boolean;
294
}
295

296
/**
297
 * Represents a method
298
 */
299
interface Method extends Callable, TypeMember {
300
  /** Method name */
301
  name: string;
302
  /** Return type (omit for void) */
303
  returns?: TypeReference;
304
  /** Whether method is static */
305
  static?: boolean;
306
  /** Whether method is abstract */
307
  abstract?: boolean;
308
  /** Whether method is async */
309
  async?: boolean;
310
}
311

312
/**
313
 * Type alias for constructor definition
314
 */
315
type Initializer = Callable;
316

317
/**
318
 * Method or constructor parameter
319
 */
320
interface Parameter extends OptionalValue, Documentable {
321
  /** Parameter name */
322
  name: string;
323
  /** Parameter type */
324
  type: TypeReference;
325
  /** Whether parameter is variadic (...args) */
326
  variadic?: boolean;
327
}
328

329
/**
330
 * Base for overridable members
331
 */
332
interface Overridable {
333
  /** Whether member can be overridden */
334
  override?: boolean;
335
}
336

337
/**
338
 * Base interface for type members
339
 */
340
interface TypeMember extends Overridable, Documentable, SourceLocatable {
341
  /** Member name */
342
  name: string;
343
}
344

345
/**
346
 * Interface for optional values
347
 */
348
interface OptionalValue {
349
  /** Whether value is optional */
350
  optional?: boolean;
351
}
352
```
353

354
### Metadata and Documentation
355

356
Support for documentation, source locations, and various metadata attachments.
357

358
```typescript { .api }
359
/**
360
 * Indicates that an entity can have documentation
361
 */
362
interface Documentable {
363
  /** Associated documentation */
364
  docs?: Docs;
365
}
366

367
/**
368
 * Key-value pairs of documentation nodes based on TSDoc
369
 */
370
interface Docs {
371
  /** Brief summary */
372
  summary?: string;
373
  /** Extended remarks */
374
  remarks?: string;
375
  /** Return value description */
376
  returns?: string;  
377
  /** Default value description */
378
  default?: string;
379
  /** Deprecation notice */
380
  deprecated?: string;
381
  /** Usage example */
382
  example?: string;
383
  /** See-also references */
384
  see?: string;
385
  /** Since version information */
386
  since?: string;
387
  /** Whether type is subclassable */
388
  subclassable?: boolean;
389
  /** Custom documentation tags */
390
  [key: string]: string | boolean | undefined;
391
}
392

393
/**
394
 * API stability levels
395
 */
396
enum Stability {
397
  /** Deprecated - will be removed */
398
  Deprecated = "deprecated",
399
  /** Experimental - may change */
400
  Experimental = "experimental",
401
  /** Stable - safe to use */
402
  Stable = "stable", 
403
  /** External - not owned by this package */
404
  External = "external"
405
}
406

407
/**
408
 * Source location information
409
 */
410
interface SourceLocation {
411
  /** Source file name */
412
  filename: string;
413
  /** Line number (1-based) */
414
  line: number;
415
  /** Column number (1-based) */
416
  column: number;
417
}
418

419
/**
420
 * Indicates entity has source location
421
 */
422
interface SourceLocatable {
423
  /** Location in source module */
424
  locationInModule?: SourceLocation;
425
}
426

427
/**
428
 * TypeScript source traceability
429
 */  
430
interface TypeScriptLocatable {
431
  /** Original TypeScript location */
432
  symbolId?: string;
433
}
434

435
/**
436
 * Person or organization metadata
437
 */
438
interface Person {
439
  /** Name */
440
  name: string;
441
  /** Roles in the project (maintainer, contributor, owner, etc.) */
442
  roles: string[];
443
  /** Contact email */
444
  email?: string;
445
  /** Website URL */
446
  url?: string;
447
}
448
```
449

450
### Assembly Configuration and Targets
451

452
Configuration interfaces for target language settings and assembly publishing.
453

454
```typescript { .api }
455
/**
456
 * Interface for entities that support targets
457
 */
458
interface Targetable {
459
  /** Target language configurations */
460
  targets?: AssemblyTargets;
461
}
462

463
/**
464
 * Target language configurations for an assembly
465
 */
466
interface AssemblyTargets {
467
  /** JavaScript/npm configuration */
468
  js?: {
469
    npm?: string;
470
  };
471
  /** Python configuration */
472
  python?: {
473
    distName?: string;
474
    module?: string;
475
    classifiers?: string[];
476
  };
477
  /** Java configuration */  
478
  java?: {
479
    package?: string;
480
    maven?: {
481
      groupId?: string;
482
      artifactId?: string;
483
    };
484
  };
485
  /** .NET configuration */
486
  dotnet?: {
487
    namespace?: string;
488
    packageId?: string;
489
    title?: string;
490
  };
491
  /** Go configuration */
492
  go?: {
493
    moduleName?: string;
494
    packageName?: string;
495
  };
496
}
497

498
/**
499
 * Interface for README-containing entities
500
 */
501
interface ReadMeContainer {
502
  /** README content */
503
  readme?: ReadMe;
504
}
505

506
/**
507
 * README information with markdown content
508
 */
509
interface ReadMe {
510
  /** Markdown content */
511
  markdown: string;
512
}
513

514
/**
515
 * Submodule definition combining interfaces
516
 */
517
type Submodule = Targetable & ReadMeContainer & {
518
  /** Location in parent module */
519
  locationInModule?: SourceLocation;
520
  /** Submodule targets */
521
  targets?: AssemblyTargets;
522
};
523
```
524

525
### Assembly Utilities and Validation
526

527
Helper functions for working with assemblies and type guards for type safety.
528

529
```typescript { .api }
530
/**
531
 * JSON schema for jsii assembly validation
532
 */
533
const schema: object;
534

535
/**
536
 * Validate assembly against JSON schema
537
 * @param assembly Assembly object to validate
538
 * @param schema JSON schema to validate against
539
 * @returns Validation result with errors if any
540
 */
541
function validateAssembly(assembly: Assembly, schema?: object): { 
542
  errors?: string[];
543
  valid: boolean;
544
};
545

546
/**
547
 * Expected file name for jsii assembly files
548
 */
549
const SPEC_FILE_NAME = ".jsii";
550

551
/**
552
 * Expected file name for compressed assemblies
553
 */  
554
const SPEC_FILE_NAME_COMPRESSED = ".jsii.gz";
555

556
/**
557
 * Load assembly from directory path
558
 */
559
function loadAssemblyFromPath(assemblyDir: string): Assembly;
560

561
/**
562
 * Load assembly from specific file path
563
 */
564
function loadAssemblyFromFile(assemblyFile: string): Assembly;
565

566
/**
567
 * Load assembly from buffer with redirect handling
568
 */
569
function loadAssemblyFromBuffer(buffer: Buffer): Assembly;
570

571
/**
572
 * Write assembly to file system
573
 */
574
function writeAssembly(
575
  assembly: Assembly, 
576
  outputPath: string,
577
  options?: { compress?: boolean }
578
): void;
579

580
/**
581
 * Replace existing assembly file
582
 */
583
function replaceAssembly(assemblyPath: string, assembly: Assembly): void;
584

585
/**
586
 * Find assembly file in directory
587
 */
588
function findAssemblyFile(directory: string): string | undefined;
589

590
/**
591
 * Check if compressed assembly exists
592
 */
593
function compressedAssemblyExists(directory: string): boolean;
594
```
595

596
### Type Guards
597

598
Type guard functions for safe type checking and discrimination.
599

600
```typescript { .api }
601
/**
602
 * Type guard for NamedTypeReference
603
 */
604
function isNamedTypeReference(ref: TypeReference): ref is NamedTypeReference;
605

606
/**
607
 * Type guard for PrimitiveTypeReference  
608
 */
609
function isPrimitiveTypeReference(ref: TypeReference): ref is PrimitiveTypeReference;
610

611
/**
612
 * Type guard for CollectionTypeReference
613
 */
614
function isCollectionTypeReference(ref: TypeReference): ref is CollectionTypeReference;
615

616
/**
617
 * Type guard for UnionTypeReference
618
 */
619
function isUnionTypeReference(ref: TypeReference): ref is UnionTypeReference;
620

621
/**
622
 * Type guard for IntersectionTypeReference
623
 */
624
function isIntersectionTypeReference(ref: TypeReference): ref is IntersectionTypeReference;
625

626
/**
627
 * Determine whether a Callable is a Method
628
 */
629
function isMethod(callable: Callable): callable is Method;
630

631
/**
632
 * Type guard for ClassType
633
 */
634
function isClassType(type: Type): type is ClassType;
635

636
/**
637
 * Type guard for InterfaceType  
638
 */
639
function isInterfaceType(type: Type): type is InterfaceType;
640

641
/**
642
 * Type guard for EnumType
643
 */
644
function isEnumType(type: Type): type is EnumType;
645

646
/**
647
 * Type guard for class or interface types
648
 */
649
function isClassOrInterfaceType(type: Type): type is ClassType | InterfaceType;
650

651
/**
652
 * Return string representation of type reference
653
 */
654
function describeTypeReference(ref: TypeReference): string;
655

656
/**
657
 * Determine whether an entity is deprecated
658
 */
659
function isDeprecated(entity: { docs?: Docs; deprecated?: string | boolean }): boolean;
660
```
661

662
## Types
663

664
```typescript { .api }
665
/**
666
 * Fully Qualified Name - unique identifier for types
667
 */
668
type FQN = string;
669

670
/**
671
 * Schema version enumeration
672
 */
673
enum SchemaVersion {
674
  LATEST = "jsii/0.10.0"
675
}
676

677
/**
678
 * jsii extension features
679
 */
680
type JsiiFeature = 'intersection-types';
681

682
/**
683
 * All available jsii features
684
 */
685
const ALL_FEATURES: readonly JsiiFeature[];
686

687
/**
688
 * Type system enforced features
689
 */
690
const ALL_TYPESYSTEM_ENFORCED_FEATURES: readonly JsiiFeature[];
691
```