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/v7.44.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/v7.44.0/schema.json#/resources/aws:apigateway%2FrestApi:RestApi"
                }
            },
            "required": [
                "url",
                "api"
            ]
        }
    },
    "language": {
        "csharp": {
            "packageReferences": {
                "Pulumi": "3.*",
                "Pulumi.Aws": "7.*"
            }
        },
        "go": {
            "generateResourceContainerTypes": true,
            "importBasePath": "github.com/acmecorp/pulumi-apigateway/sdk/go/apigateway"
        },
        "nodejs": {
            "dependencies": {
                "@pulumi/aws": "^7.44.0"
            },
            "devDependencies": {
                "typescript": "^5.0.0"
            }
        },
        "python": {
            "requires": {
                "pulumi": ">=3.0.0,<4.0.0",
                "pulumi-aws": ">=7.0.0,<8.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

Generated from pkg/codegen/schema/pulumi.json in pulumi/pulumi v3.262.0 — the metaschema pulumi schema check validates against.

Every type below is one shape a package schema can contain. Names are the JSON keys you write; a linked type means that property’s value takes the shape of another type on this page. To check a schema you’ve written against these rules, run pulumi schema check.

Package

The top-level object of a package schema. Everything else on this page describes something reachable from here.

• name string required
  The unqualified name of the package (e.g. “aws”, “azure”, “gcp”, “kubernetes”, “random”)
• displayName string optional
  The human-friendly name of the package.
• version string optional
  The version of the package. The version must be valid semver.
• description string optional
  The description of the package. Descriptions are interpreted as Markdown.
• keywords array[string] optional

  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> is one of cloud, database, infrastructure, network, utility, or vcs, and <type> is either native or component. If the package is a bridged Terraform provider, don’t include a kind/ label.

• homepage string optional
  The package’s homepage.
• license string optional
  The name of the license used for the package’s contents.
• attribution string optional
  Freeform text attribution of derived work, if required.
• repository string optional
  The URL at which the package’s sources can be found.
• logoUrl string optional
  The URL of the package’s logo, if any.
• pluginDownloadURL string optional
  The URL to use when downloading the provider plugin binary.
• configurationDocsUrl string optional
  The URL of the provider’s installation and configuration documentation, if any.
• validateCredentialsOnNew boolean optional
  Indicates that pulumi new may configure the provider after creating a project in order to validate the user’s credentials.
• publisher string optional
  The name of the person or organization that authored and published the package.
• namespace string optional
  The namespace of the package. Used to disambiguate the package name. Defaults to ‘pulumi’ when not specified.
• meta Metadata optional
  Format metadata about this package.
• config Config optional
  The package’s configuration variables.
• types map[ComplexType] optional
  A map from type token to complexTypeSpec that describes the set of complex types (i.e. object, enum) defined by this package.
• dependencies array[PackageDescriptor] optional
  A list of package descriptors that describes the set of dependencies for this package.
• provider Resource optional
  The provider type for this package.
• resources map[Resource] optional
  A map from type token to resourceSpec that describes the set of resources and components defined by this package.
• functions map[Function] optional
  A map from token to functionSpec that describes the set of functions defined by this package.
• language map[PackageLanguage] optional
  Additional language-specific data about the package.
• parameterization ParameterizationSpec optional
  An optional object to define parameterization for the package.
• allowedPackageNames array[string] optional
  A list of allowed package names in addition to the name property.

Metadata

Format metadata about this package.

• moduleFormat string optional
  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”.
• supportPack boolean optional
  Write the package to support the pack command.

Config

The package’s configuration variables.

• variables map[Property] optional
  A map from variable name to propertySpec that describes a package’s configuration variables.
• defaults array[string] optional
  A list of the names of the package’s non-required configuration variables.

PackageDescriptor

Identifies another package this package depends on.

• name string required
  The unqualified name of the package (e.g. “aws”, “azure”, “gcp”, “kubernetes”, “random”)
• version string optional
  The version of the package. The version must be valid semver if present.
• pluginDownloadURL string optional
  The optional URL to use when downloading the provider plugin binary.
• parameterization object optional
  An optional object to define parameterization for the package.

ObjectType

Describes an object type.

• description string optional
  The description of the type, if any.
• properties map[Property] optional
  A map from property name to propertySpec that describes the object’s properties.
• type string optional
  The type of the object. Must be ‘object’ if this is an object type, or the underlying type for an enum.
• required array[string] optional
  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] optional
  Additional language-specific data about the object type.
• isOverlay boolean optional
  indicates whether the type is an overlay provided by the package. Overlay code is generated by the package rather than using the core Pulumi codegen libraries.
• overlaySupportedLanguages array[string] optional
  A list of languages that the overlay supports. This only has an effect if the Resource is an Overlay (isOverlay == true). Supported values are ’nodejs’, ‘python’, ‘go’, ‘csharp’, ‘java’, ‘yaml’.
  Values: nodejs, python, go, csharp, java, yaml

ComplexType

Describes an object or enum type.

• description string optional
  The description of the type, if any. Interpreted as Markdown.
• language map[ObjectTypeLanguage] optional
  Additional language-specific data about the type.
• isOverlay boolean optional
  Indicates that the implementation of the type should not be generated from the schema, and is instead provided out-of-band by the package author.

EnumType

Describes an enum type.

• type string required
  The underlying primitive type of the enum.
  Values: boolean, integer, number, string
• enum array[EnumValue] required
  The list of possible values for the enum.

Resource

Describes a resource or component.

Includes every property of ObjectType, plus:

• description string optional
  The description of the resource, if any. Interpreted as Markdown.
• inputProperties map[Property] optional
  A map from property name to propertySpec that describes the resource’s input properties.
• requiredInputs array[string] optional
  A list of the names of the resource’s required input properties.
• stateInputs ObjectType optional
  An optional objectTypeSpec that describes additional inputs that may be necessary to get an existing resource. If this is unset, only an ID is necessary.
• listInputs ObjectType optional
  An optional objectTypeSpec that describes inputs that may be supplied when listing existing resources of this type. If this is unset, the resource does not declare list support in the schema.
• aliases array[Alias] optional
  The list of aliases for the resource.
• deprecationMessage string optional
  Indicates whether the resource is deprecated.
• isComponent boolean optional
  Indicates whether the resource is a component.
• methods map[string] optional
  A map from method name to function token that describes the resource’s method set.
• isOverlay boolean optional
  Indicates that the implementation of the resource should not be generated from the schema, and is instead provided out-of-band by the package author.

Function

Describes a function.

• description string optional
  The description of the function, if any. Interpreted as Markdown.
• inputs ObjectType optional
  The bag of input values for the function, if any.
• multiArgumentInputs array[string] optional
  A list of parameter names that determines whether the input bag should be treated as a single argument or as multiple arguments. The list corresponds to the order in which the parameters should be passed to the function.
• outputs Type | ObjectType optional
  Specifies the return type of the function definition.
• returnType Type | ObjectType optional
  Specifies the return type of the function definition.
• deprecationMessage string optional
  Indicates whether the function is deprecated.
• language map[FunctionLanguage] optional
  Additional language-specific data about the function.
• isOverlay boolean optional
  Indicates that the implementation of the function should not be generated from the schema, and is instead provided out-of-band by the package author.
• overlaySupportedLanguages array[string] optional
  A list of languages that the overlay supports. This only has an effect if the Resource is an Overlay (isOverlay == true). Supported values are ’nodejs’, ‘python’, ‘go’, ‘csharp’, ‘java’, ‘yaml’.
  Values: nodejs, python, go, csharp, java, yaml
• plain boolean optional
  A marker field to indicate that this function should only generate plain and output style methods. It defaults to true, that is to emit both plain and output style methods. Setting this to false will emit only output style methods.

Type

A reference to a type. The particular kind of type referenced is determined based on the contents of the “type” property and the presence or absence of the “additionalProperties”, “items”, “oneOf”, and “$ref” properties.

• plain boolean optional
  Indicates that when used as an input, this type does not accept eventual values.

Property

Describes an object or resource property.

Includes every property of Type, plus:

• description string optional
  The description of the property, if any. Interpreted as Markdown.
• const boolean | number | string optional
  The constant value for the property, if any. The type of the value must be assignable to the type of the property.
• default boolean | number | string optional
  The default value for the property, if any. The type of the value must be assignable to the type of the property.
• defaultInfo Default optional
  Additional information about the property’s default value, if any.
• deprecationMessage string optional
  Indicates whether the property is deprecated.
• language map[PropertyLanguage] optional
  Additional language-specific data about the property.
• secret boolean optional
  Specifies whether the property is secret (default false).
• replaceOnChanges boolean optional
  Specifies whether a change to the property causes its containing resource to be replaced instead of updated (default false).
• willReplaceOnChanges boolean optional
  Indicates that the provider will replace the resource when this property is changed.

EnumValue

One of the values an enum type may take, and the metadata attached to it.

• name string optional
  If present, overrides the name of the enum value that would usually be derived from the value.
• description string optional
  The description of the enum value, if any. Interpreted as Markdown.
• value boolean | integer | number | string required
  The enum value itself.
• deprecationMessage string optional
  Indicates whether the value is deprecated.

Alias

A previous identity of a resource. Aliases let a resource be renamed or moved without the engine treating it as a delete and a create. May be written as a string or as an object.

• type string optional
  The type portion of the alias, if any.

Default

Additional information about the property’s default value, if any.

• environment array[string] required
  A set of environment variables to probe for a default value.
• language map[DefaultLanguage] optional
  Additional language-specific data about the default value.

Discriminator

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

• propertyName string required
  The name of the property in the payload that will hold the discriminator value.
• mapping map[string] optional
  An optional object to hold mappings between payload values and schema names or references.

ParameterizationSpec

Parameterized packages populate this with concrete parameter values. Pulumi code generators read it to emit SDKs that preserve those values and pass them back to the provider at runtime.

• baseProvider BaseProviderSpec optional
  The provider being specialized, named by package name and version.
• parameter string optional
  The parameter for the provider.

BaseProviderSpec

The provider that a parameterized package specializes.

• name string required
  The unqualified name of the package (e.g. “aws”, “azure”, “gcp”, “kubernetes”, “random”)
• version string required
  The version of the package. The version must be valid semver.

Language-specific extensions

A language field maps a supported language to a language-specific object. The shape of that object is decided by that language’s SDK code generator rather than by the schema itself, which is how a generator gets to encode what it alone needs — an NPM package name, a Java base package, a Go import path.

Each generator owns its extension, so each section below is generated from that language’s own repository and carries the release it came from. A language that has no entry for a section does not read one.

PackageLanguage

Language-specific information for a package.

PropertyLanguage

Language-specific information for a property.

ResourceLanguage

Language-specific information for a resource.

ObjectTypeLanguage

Language-specific information for an object type.

FunctionLanguage

Language-specific information for a function.

Not yet supported in any target language.

DefaultLanguage

Language-specific information for a property’s default value.

Not yet supported in any target language.