Pulumi package schema

Pulumi Packages are described by a package schema, which is used to drive code generation for SDKs in each supported Pulumi language, as well as generation of language-agnostic package documentation. This schema can be manually authored (for component packages) or generated from some other source (such as a cloud provider’s API specifications for a native Pulumi resource provider). Packages can expose resources and functions, define types used by these resources and functions, and provide packaging metadata for language-specific SDKs.

Example

An example of the Pulumi Package Schema is below. This schema describes a package named apigateway, with a single resource RestAPI which is a component, and which has a required input property routes and required (always populated) output properties url of type string and api which references the external type of the AWS API Gateway RestAPI resource. The type of the routes input is a custom type named EventHandlerRoute defined in the schema, which is an object type with path,method and function properties. The schema supports generation of SDKs for csharp, go, nodejs and python, with metadata configuring each of the generated SDKs in the corresponding sections.

{
    "name": "apigateway",
    "types": {
        "apigateway:index:EventHandlerRoute": {
            "type": "object",
            "properties": {
                "path": {
                    "type": "string"
                },
                "method": {
                    "type": "string"
                },
                "function": {
                    "$ref": "/aws/v3.30.0/schema.json#/resources/aws:lambda%2Ffunction:Function"
                }
            }
        }
    },
    "resources": {
        "apigateway:index:RestAPI": {
            "isComponent": true,
            "inputProperties": {
                "routes": {
                    "type": "array",
                    "items": {
                        "$ref": "#/types/apigateway:index:EventHandlerRoute"
                    }
                }
            },
            "requiredInputs": [
                "routes"
            ],
            "properties": {
                "url": {
                    "type": "string"
                },
                "api": {
                    "$ref": "/aws/v3.30.0/schema.json#/resources/aws:apigateway%2FrestApi:RestApi"
                }
            },
            "required": [
                "url",
                "api"
            ]
        }
    },
    "language": {
        "csharp": {
            "packageReferences": {
                "Pulumi": "3.*",
                "Pulumi.Aws": "4.*"
            }
        },
        "go": {
            "generateResourceContainerTypes": true,
            "importBasePath": "github.com/acmecorp/pulumi-apigateway/sdk/go/apigateway"
        },
        "nodejs": {
            "dependencies": {
                "@pulumi/aws": "^4.5.1"
            },
            "devDependencies": {
                "typescript": "^3.7.0"
            }
        },
        "python": {
            "requires": {
                "pulumi": ">=3.0.0,<4.0.0",
                "pulumi-aws": ">=4.0.0,<5.0.0"
            }
        }
    }
}

Complete schema examples that include a much wider range of schema configuration styles are available in these existing packages:

AWS - Bridged Provider Package
Azure Native - Native Pulumi Provider Package
EKS - Component Package

Pulumi Package Schema

Package

Property	Type	Required	Description
`name`	`string`	Yes	Name is the unqualified name of the package (e.g. “aws”, “azure”, “gcp”, “kubernetes”, “random”)
`displayName`	`string`	No	The human-friendly name of the package.
`version`	`string`	Yes	Version is the version of the package. The version must be valid semver.
`description`	`string`	No	Description is the description of the package.
`keywords`	`array[string]`	No	Keywords is the list of keywords that are associated with the package, if any. Reserved keywords can be specified that help with categorizing the package in the Pulumi registry. `category/<name>` and `kind/<type>` are the only reserved keywords at this time, where `<name>` can be one of: `cloud`, `database`, `infrastructure`, `network`, `utility`, `vcs` and `<type>` is either `native` or `component`. If the package is a bridged Terraform provider, then don’t include a `kind/` label.
`homepage`	`string`	No	Homepage is the package’s homepage.
`license`	`string`	No	License indicates which license is used for the package’s contents.
`attribution`	`string`	No	Attribution allows freeform text attribution of derived work, if needed.
`repository`	`string`	No	Repository is the URL at which the source for the package can be found.
`logoUrl`	`string`	No	LogoURL is the URL for the package’s logo, if any.
`pluginDownloadURL`	`string`	No	PluginDownloadURL is the URL to use to acquire the provider plugin binary, if any. See Authoring & Publishing for more details.
`publisher`	`string`	No	The name of the person or organization that authored and published the package.
`meta`	`Metadata`	No	Meta contains information for the importer about this package.
`config`	`Config`	No	Config describes the set of configuration variables defined by this package.
`types`	`map[ComplexType]`	No	Types is a map from type token to ComplexType that describes the set of complex types (ie. object, enum) defined by this package.
`provider`	`Resource`	No	Provider describes the provider type for this package.
`resources`	`map[Resource]`	No	Resources is a map from type token to Resourc that describes the set of resources defined by this package.
`functions`	`map[Function]`	No	Functions is a map from token to Function that describes the set of functions defined by this package.
`language`	`map[PackageLanguage]`	No	Language specifies additional language-specific data about the package.

Metadata

Metadata for the importer about this package.

Property	Type	Required	Description
`moduleFormat`	`string`	No	ModuleFormat is a regex that is used by the importer to extract a module name from the module portion of a type token. Packages that use the module format “namespace1/namespace2/…/namespaceN” do not need to specify a format. The regex must define one capturing group that contains the module name, which must be formatted as “namespace1/namespace2/…namespaceN”.

Config

A package’s configuration variables.

Property	Type	Required	Description
`variables`	`map[Property]`	No	Variables is a map from variable name to Property that describes a package’s configuration variables.
`required`	`array[string]`	No	Required is a list of the names of the package’s required configuration variables.

ObjectType

An object type.

Property	Type	Required	Description
`description`	`string`	No	Description is the description of the type, if any.
`properties`	`map[Property]`	No	Properties, if present, is a map from property name to Property that describes the type’s properties.
`type`	`string`	No	Type must be “object” if this is an object type, or the underlying type for an enum.
`required`	`array[string]`	No	Required, if present, is a list of the names of an object type’s required properties. These properties must be set for inputs and will always be set for outputs.
`language`	`map[ObjectTypeLanguage]`	No	Language specifies additional language-specific data about the type.

ComplexType

An object or enum type.

Property	Type	Required	Description
All `ObjectType` properties, as well as:
`enum`	`array[EnumValue]`	No	Enum, if present, is the list of possible values for an enum type.

Resource

A resource description.

Property	Type	Required	Description
All `ObjectType` properties, as well as:
`inputProperties`	`map[Property]`	No	Description is the description of the property, if any.
`requiredInputs`	`array[string]`	No	RequiredInputs is a list of the names of the resource’s required input properties.
`stateInputs`	`ObjectType`	No	StateInputs is an optional ObjectType that describes additional inputs that may be necessary to get an existing resource. If this is unset, only an ID is necessary.
`aliases`	`array[Alias]`	No	Aliases is the list of aliases for the resource.
`deprecationMessage`	`string`	No	DeprecationMessage indicates whether or not the resource is deprecated.
`language`	`map[ResourceLanguage]`	No	Language specifies additional language-specific data about the resource.
`isComponent`	`boolean`	No	IsComponent indicates whether the resource is a ComponentResource.
`methods`	`map[string]string`	No	Methods maps method names to functions in this schema.

Function

A function description.

Property	Type	Required	Description
`description`	`string`	No	Description is the description of the function, if any.
`inputs`	`ObjectType`	No	Inputs is the bag of input values for the function, if any.
`outputs`	`ObjectType`	No	Outputs is the bag of output values for the function, if any.
`deprecationMessage`	`string`	No	DeprecationMessage indicates whether or not the function is deprecated.
`language`	`map[FunctionLanguage]`	No	Language specifies additional language-specific data about the function.

Type

A reference to a type.

Property	Type	Required	Description
`type`	`string`	Yes	Type is the primitive or composite type, if any. May be “boolean”, “integer”, “number”, “string”, “array”, or “object”.
`$ref`	`string`	Yes	Ref is a reference to a type in this or another document. For example, the built-in `Archive`, `Asset`, and `Any` types are referenced as `"pulumi.json#/Archive"`, `"pulumi.json#/Asset"`, and `"pulumi.json#/Any"`, respectively. A type from this document is referenced as `"#/types/pulumi:type:token"`. A type from another document is referenced as `"path#/types/pulumi:type:token"`, where path is of the form: `"/provider/vX.Y.Z/schema.json"` or `"pulumi.json"` or `"http[s]://example.com /provider/vX.Y.Z/schema.json"`. A resource from this document is referenced as “#/resources/pulumi:type:token”. A resource from another document is referenced as `"path#/resources/pulumi:type:token"`, where path is of the form: `"/provider/vX.Y.Z/schema.json"` or `"pulumi.json"` or `"http[s]://example.com /provider/vX.Y.Z/schema.json"`.
`additionalProperties`	`Type`	No	AdditionalProperties, if set, describes the element type of an “object” (i.e. a string -> value map).
`items`	`Type`	No	Items, if set, describes the element type of an array.
`oneOf`	`array[Type]`	No	OneOf indicates that values of the type may be one of any of the listed types.
`discriminator`	`Discriminator`	No	Discriminator informs the consumer of an alternative schema based on the value associated with it.
`plain`	`boolean`	No	Plain indicates that when used as an input, this type does not accept eventual values.

Property

An object or resource property.

Property	Type	Required	Description
All `Type` properties, as well as:
`description`	`string`	No	Description is the description of the property, if any.
`const`	`any`	No	Const is the constant value for the property, if any. The type of the value must be assignable to the type of the property.
`default`	`any`	No	Default is the default value for the property, if any. The type of the value must be assignable to the type of the property.
`defaultInfo`	`Default`	No	DefaultInfo contains additional information about the property’s default value, if any.
`deprecationMessage`	`string`	No	DeprecationMessage indicates whether or not the property is deprecated.
`language`	`map[PropertyLanguage]`	No	Language specifies additional language-specific data about the property.
`secret`	`boolean`	No	Secret specifies if the property is secret (default false).
`replaceOnChanges`	`boolean`	No	ReplaceOnChanges specifies if the associated object should be updated with a replace operation instead of a update operation.
`willReplaceOnChanges`	`boolean`	No	WillReplaceOnChanges indiciates that the provider will replace the resource when this property is changed.

EnumValue

The values metadata associated with an enum type.

Property	Type	Required	Description
`name`	`string`	No	Name, if present, overrides the name of the enum value that would usually be derived from the value.
`description`	`string`	No	Description of the enum value.
`value`	`any`	No	Value is the enum value itself.
`deprecationMessage`	`string`	No	DeprecationMessage indicates whether or not the value is deprecated.

Alias

An alias description.

Property	Type	Required	Description
`name`	`string`	No	Name is the name portion of the alias, if any.
`project`	`string`	No	Project is the project portion of the alias, if any.
`type`	`string`	No	Type is the type portion of the alias, if any.

Default

Extra information about the default value for a property.

Property	Type	Required	Description
`environment`	`array[string]`	Yes	Environment specifies a set of environment variables to probe for a default value.
`language`	`map[DefaultLanguage]`	No	Language specifies additional language-specific data about the default value.

Discriminator

Informs the consumer of an alternative schema based on the value associated with it.

Property	Type	Required	Description
`propertyName`	`string`	Yes	PropertyName is the name of the property in the payload that will hold the discriminator value.
`mapping`	`map[string]`	No	Mapping is an optional object to hold mappings between payload values and schema names or references.

Language-Specific Extensions

Several schema types contain a language field which is a map from a supported language to a language-specific schema type. The schema for this type is language dependent, and offers extensibility for language-specific SDK code generators to encode language-specific information about the schema entry.

PackageLanguage

Language-specific information for a package.

For javascript, typescript:

Property	Type	Required	Description
`packageName`	`string`	No	Custom name for the NPM package.
`packageDescription`	`string`	No	Description for the NPM package.
`readme`	`string`	No	Readme contains the text for the package’s README.md files.
`dependencies`	`map[string]`	No	NPM dependencies to add to package.json.
`devDependencies`	`map[string]`	No	NPM dev-dependencies to add to package.json.
`peerDependencies`	`map[string]`	No	NPM peer-dependencies to add to package.json.
`resolutions`	`map[string]`	No	NPM resolutions to add to package.json
`typescriptVersion`	`string`	No	A specific version of TypeScript to include in package.json.
`moduleToPackage`	`map[string]`	No	A map containing overrides for module names to package names.
`compatibility`	`string`	No	Toggle compatibility mode for a specified target.
`disableUnionOutputTypes`	`boolean`	No	Disable support for unions in output types.
`containsEnums`	`boolean`	No	An indicator for whether the package contains enums.
`respectSchemaVersion`	`boolean`	No	Use the `package.version` field in the generated SDK
`pluginName`	`string`	No	The name of the plugin, which might be different from the package name.
`pluginVersion`	`string`	No	The version of the plugin, which might be different from the version of the package.

For python:

Property	Type	Required	Description
`packageName`	`string`	No	PackageName is an override for the name of the generated python package.
`requires`	`map[string]`	No	Description for the PyPi package.
`readme`	`string`	No	Readme contains the text for the package’s README.md files.
`moduleNameOverrides`	`map[string]`	No	Optional overrides for Pulumi module names.
`compatibility`	`string`	No	Toggle compatibility mode for a specified target.
`respectSchemaVersion`	`boolean`	No	Use the `package.version` field in the generated SDK.
`inputTypes`	`string`	No	Controls the types of resource inputs. Either `classes` for args-classes or `classes-and-dicts` for args-classes side by side with typed dictionaries.

For go:

Property	Type	Description
`importBasePath`	`string`	Base path for package imports.
`rootPackageName`	`string`	Explicit package name, which may be different to the import path.
`moduleToPackage`	`map[string]`	Map from module -> package name.
`packageImportAliases`	`map[string]`	Map from package name -> package alias.
`generateResourceContainerTypes`	`boolean`	Generate container types (arrays, maps, pointer output types etc.) for each resource. These are typically used to support external references.
`respectSchemaVersion`	`boolean`	Use the `package.version` field in the generated SDK.

For csharp:

Property	Type	Required	Description
`packageReferences`	`map[string]`	No
`namespaces`	`map[string]`	No
`compatibility`	`string`	No
`dictionaryConstructors`	`boolean`	No
`rootNamespace`	`string`	No	The root namespace that the generated package should live under. This setting defaults to “Pulumi”.
`respectSchemaVersion`	`boolean`	No	Use the `package.version` field in the generated SDK.

For java:

Property	Type	Required	Description
`packages`	`map[string]`	No	Overrides for module names to Java package names. Example: “autoscaling/v1” -> “autoscaling.v1”.
`basePackage`	`string`	No	Prefixes the generated Java package. This setting defaults to “com.pulumi”.
`buildFiles`	`string`	No	Generates build files for the chosen build tool. Supported values: “gradle”.
`dependencies`	`map[string]`	No	Java dependencies to use with the `buildFiles`. Example: “com.pulumi.gcp” -> “6.23.0”.

PropertyLanguage

Language-specific info for a property.

For csharp:

Property	Type	Required	Description
`name`	`string`	No

DefaultLanguage

Not yet supported in any target languages.

ResourceLanguage

Not yet supported in any target languages.

FunctionLanguage

Not yet supported in any target languages.

ObjectTypeLanguage

Not yet supported in any target languages.

Pulumi package schema

On this page

On this page

Example

Pulumi Package Schema

Package

Metadata

Config

ObjectType

ComplexType

Resource

Function

Type

Property

EnumValue

Alias

Default

Discriminator

Language-Specific Extensions

PackageLanguage

PropertyLanguage

DefaultLanguage

ResourceLanguage

FunctionLanguage

ObjectTypeLanguage

On this page

On this page