Skip to content

.jsii Assemblies

This document describes the contents of the .jsii assembly documents generated by the jsii compiler, and explains the semantics behind the various entities it represents. This serves as a reference for front-end language implementors.

Schema

.jsii assemblies are JSON-formatted documents. The specification is hosted under the jsii-spec package. Refer to the inline documentation in the spec.ts file for more information about the general content of the assembly documents.

The most important part of the assembly documentation, which is described in detail in this document, is the types map, which contains the descriptions of all types declared by the .jsii assembly. It is a map from jsii fully- qualified type names to a type specification.

All boolean attributes in the document specification are optional, and are left out (undefined) when false.

Common Attributes

Certain optional attributes are shared by API entities (types and members):

  • docs - documentation attached to the API entity
  • deprecated - contains a message explaining why an API was deprecated and/or how users should migrate away
  • stability - the stability level of the API entity. The ultimate meaning of the stability level is up to the package maintainer, but a baseline interpretation of the valid values follows:
    • experimental denotes an API that is actively worked on and are not subject to semantic versioning gurantees (they may receive breaking change on a minor version release)
    • stable denotes an API that is safe to use in production systems and are subject ot semantic versioning guarantees (they may not receive breaking changes without a major version bump)
    • deprecated denotes an API that should no longer be used. The deprecated entry in the docs object should contain a message explaining how users should migrate away
    • external denotes an API that is not owned by the package's maintainer and may change in unexpected ways. Such APIs are usually derived from external artifacts, which the package maintainers do not have control over.
  • additional entries represent user-defined JSDoc tags with meaning defined by convention and/or the package maintainer
  • locationInModule - coordinates of the declaration in the source
  • fileName - the path to the source file, relative to the package root
  • line - the line number on which the entity is declared (or the first line when a declaration spans multiple lines)

Types

Classes

Attribute Type Description
kind 'class' Discriminator to identify classes
abstract boolean Whether this class is abstract
assembly string The name of the assembly this class is a part of
base string The fully-qualified name of the parent class of this class
fqn string The fully-qualified name of the class
initializer Constructor The class' constructor
interfaces string[] The fully-qualified names of interfaces implemented by this class
methods Method[] The methods declared by this class
name string The simple name of the class
properties Property[] The properties declared by this class

Interfaces

jsii interfaces are declarations of type signatures that can be implemented by classes. Interface names must be prefixed with an I (e.g: IFoo).

Attribute Type Description
kind 'interface' Discriminator to identify interfaces
assembly string The name of the assembly this interface is a part of
fqn string The fully-qualified name of the interface
interfaces string[] The fully-qualified names of interfaces extended by this interface
methods Method[] The methods declared by this interface
name string The simple name of the interface
properties Property[] The properties declared by this interface

Structs (a.k.a. Data Types)

Structs (or Data Types) are immutable, data-only interfaces:

  • They declare no methods
  • All properties they declare are readonly
  • They can only implement other structs
  • They cannot be extended by interfaces that are not structs
  • They cannot be implemented by classes

Unlike regular interfaces, jsii struct names are not required to have any particular prefix.

Since those are immutable, pure data objects, the jsii-runtime exchanges instances of those by value, instead of by reference, allowing to save cross-language communication overhead when working with the data.

Attribute Type Description
kind 'interface' Discriminator to identify interfaces
datatype true Indicates a struct / data type declaration
assembly string The name of the assembly this struct is a part of
fqn string The fully-qualified name of the struct
interfaces string[] The fully-qualified names of struct extended by this struct
name string The simple name of the struct
properties Property[] The properties declared by this struct (all readonly)

Enums

Attribute Type Description
kind 'enum' Discriminator to identify enums
assembly string The name of the assembly this enum is a part of
fqn string The fully-qualified name of the enum
members EnumMember[] The enum members declared by this enum
name string The simple name of the enum

Members

Constructors

Attribute Type Description
overrides string The fully-qualified name of the class/interface that declares the overridden constructor
parameters Parameter[] Parameters of this constructor
protected boolean Whether this constructor is protected
variadic boolean Whether the last parameter is variadic

Enum Members

Attribute Type Description
name string The name of the enum member. Must be UPPER_SNAKE_CASED

Methods

Attribute Type Description
abstract boolean Whether this method is abstract
async boolean Whether this method is asynchronous
name string The name of the method
overrides string The fully-qualified name of the class/interface that declares the overridden method
parameters Parameter[] Parameters of this method
protected boolean Whether this method is protected
returns OptionalValue The return type of the method
static boolean Whether this method is static
variadic boolean Whether the last parameter is variadic

Methods with the abstract feature may only be members of abstract classes or interfaces, and all methods that are members of interfaces must be abstract.

Methods that are static cannot feature the overrides attribute, as static members are not inherited.

Properties

Attribute Type Description
abstract boolean Whether this property is abstract
const boolean Whether this property is a constant (implies static and immutable)
immutable boolean Whether this property is immutable
name string The name of the property
optional boolean Whether this property is optional
overrides string The fully-qualified name of the class/interface that declares the overridden property
protected boolean Whether this constructor is protected
static boolean Whether this property is static
type TypeReference The type of the property

Properties that are const must have a name that is UPPER_SNAKE_CASED. They represent constants similar to Enum Members, which can be proactively resolved by the jsii runtimes.

Danger

Properties and methods that are static can feature the overrides attribute, as static members are inherited with the prototype in JavaScript (as part of the ES6 specification). Not all target languages have this capability (most, like C# and Java, only support hiding static declarations), and consequently code generators may ignore this (or explicitly hide parent declarations) instead.


Last update: 2021-09-24