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 langauge-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 availble in these existing packages:

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

Pulumi Package Schema

Package

PropertyTypeRequiredDescription
namestringYesName is the unqualified name of the package (e.g. “aws”, “azure”, “gcp”, “kubernetes”, “random”)
versionstringYesVersion is the version of the package. The version must be valid semver.
descriptionstringNoDescription is the description of the package.
keywordsarray[string]NoKeywords is the list of keywords that are associated with the package, if any.
homepagestringNoHomepage is the package’s homepage.
licensestringNoLicense indicates which license is used for the package’s contents.
attributionstringNoAttribution allows freeform text attribution of derived work, if needed.
repositorystringNoRepository is the URL at which the source for the package can be found.
logoUrlstringNoLogoURL is the URL for the package’s logo, if any.
pluginDownloadURLstringNoPluginDownloadURL is the URL to use to acquire the provider plugin binary, if any.
metaMetadataNoMeta contains information for the importer about this package.
configConfigNoConfig describes the set of configuration variables defined by this package.
typesmap[ComplexType]NoTypes is a map from type token to ComplexType that describes the set of complex types (ie. object, enum) defined by this package.
providerResourceNoProvider describes the provider type for this package.
resourcesmap[Resource]NoResources is a map from type token to Resourc that describes the set of resources defined by this package.
functionsmap[Function]NoFunctions is a map from token to Function that describes the set of functions defined by this package.
languagemap[PackageLanguage]NoLanguage specifies additional language-specific data about the package.

Metadata

Metadata for the importer about this package.

PropertyTypeRequiredDescription
moduleFormatstringNoModuleFormat 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.

PropertyTypeRequiredDescription
variablesmap[Property]NoVariables is a map from variable name to Property that describes a package’s configuration variables.
requiredarray[string]NoRequired is a list of the names of the package’s required configuration variables.

ObjectType

An object type.

PropertyTypeRequiredDescription
descriptionstringNoDescription is the description of the type, if any.
propertiesmap[Property]NoProperties, if present, is a map from property name to Property that describes the type’s properties.
typestringNoType must be “object” if this is an object type, or the underlying type for an enum.
requiredarray[string]NoRequired, 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.
plainarray[string]NoPlain, if present, is a list of the names of an object type’s plain properties. These properties only accept prompt values.
languagemap[ObjectTypeLanguge]NoLanguage specifies additional language-specific data about the type.

ComplexType

An object or enum type.

PropertyTypeRequiredDescription
All ObjectType properties, as well as:
enumarray[EnumValue]NoEnum, if present, is the list of possible values for an enum type.

Resource

A resource description.

PropertyTypeRequiredDescription
All ObjectType properties, as well as:
inputPropertiesmap[Property]NoDescription is the description of the property, if any.
requiredInputsarray[string]NoRequiredInputs is a list of the names of the resource’s required input properties.
plainInputsarray[string]NoPlainInputs is a list of the names of the resource’s plain input properties that only accept prompt values.
stateInputsObjectTypeNoStateInputs 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.
aliasesarray[Alias]NoAliases is the list of aliases for the resource.
deprecationMessagestringNoDeprecationMessage indicates whether or not the resource is deprecated.
languagemap[ResourceLanguage]NoLanguage specifies additional language-specific data about the resource.
isComponentbooleanNoIsComponent indicates whether the resource is a ComponentResource.

Function

A function description.

PropertyTypeRequiredDescription
descriptionstringNoDescription is the description of the function, if any.
inputsObjectTypeNoInputs is the bag of input values for the function, if any.
outputsObjectTypeNoOutputs is the bag of output values for the function, if any.
deprecationMessagestringNoDeprecationMessage indicates whether or not the function is deprecated.
languagemap[FunctionLanguage]NoLanguage specifies additional language-specific data about the function.

Type

A reference to a type.

PropertyTypeRequiredDescription
typestringYesType is the primitive or composite type, if any. May be “bool”, “integer”, “number”, “string”, “array”, or “object”.
$refstringYesRef 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 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".
additionalPropertiesTypeNoAdditionalProperties, if set, describes the element type of an “object” (i.e. a string -> value map).
itemsTypeNoItems, if set, describes the element type of an array.
oneOfarray[Type]NoOneOf indicates that values of the type may be one of any of the listed types.
discriminatorDiscriminatorNoDiscriminator informs the consumer of an alternative schema based on the value associated with it.

Property

An object or resource property.

PropertyTypeRequiredDescription
All Type properties, as well as:
descriptionstringNoDescription is the description of the property, if any.
constanyNoConst is the constant value for the property, if any. The type of the value must be assignable to the type of the property.
defaultanyNoDefault is the default value for the property, if any. The type of the value must be assignable to the type of the property.
defaultInfoDefaultNoDefaultInfo contains additional information about the property’s default value, if any.
deprecationMessagestringNoDeprecationMessage indicates whether or not the property is deprecated.
languagemap[PropertyLanguage]NoLanguage specifies additional language-specific data about the property.
secretbooleanNoSecret specifies if the property is secret (default false).

EnumValue

The values metadata associated with an enum type.

PropertyTypeRequiredDescription
namestringNoName, if present, overrides the name of the enum value that would usually be derived from the value.
descriptionstringNoDescription of the enum value.
valueanyNoValue is the enum value itself.
deprecationMessagestringNoDeprecationMessage indicates whether or not the value is deprecated.

Alias

An alias description.

PropertyTypeRequiredDescription
namestringNoName is the name portion of the alias, if any.
projectstringNoProject is the project portion of the alias, if any.
typestringNoType is the type portion of the alias, if any.

Default

Extra information about the default value for a property.

PropertyTypeRequiredDescription
environmentarray[string]YesEnvironment specifies a set of environment variables to probe for a default value.
languagemap[DefaultLanguage]NoLanguage specifies additional language-specific data about the default value.

Discriminator

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

PropertyTypeRequiredDescription
propertyNamestringYesPropertyName is the name of the property in the payload that will hold the discriminator value.
mappingmap[string]NoMapping 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 nodejs:

PropertyTypeRequiredDescription
packageNamestringNoCustom name for the NPM package.
packageDescriptionstringNoDescription for the NPM package.
readmestringNoReadme contains the text for the package’s README.md files.
dependenciesmap[string]NoNPM dependencies to add to package.json.
devDependenciesmap[string]NoNPM dev-dependencies to add to package.json.
peerDependenciesmap[string]NoNPM peer-dependencies to add to package.json.
resolutionsmap[string]NoNPM resolutions to add to package.json
typescriptVersionstringNoA specific version of TypeScript to include in package.json.
moduleToPackagemap[string]NoA map containing overrides for module names to package names.
compatibilitystringNoToggle compatibility mode for a specified target.
disableUnionOutputTypesbooleanNoDisable support for unions in output types.
containsEnumsbooleanNoAn indicator for whether the package contains enums.

For python:

PropertyTypeRequiredDescription
packageNamestringNoPackageName is an override for the name of the generated python package.
requiresmap[string]NoDescription for the NPM package.
readmestringNoReadme contains the text for the package’s README.md files.
moduleNameOverridesmap[string]NoOptional overrides for Pulumi module names.
compatibilitystringNoToggle compatibility mode for a specified target.

For go:

PropertyTypeDescription
importBasePathstringBase path for package imports.
rootPackageNamestringExplicit package name, which may be different to the import path.
moduleToPackagemap[string]Map from module -> package name.
packageImportAliasesmap[string]Map from package name -> package alias.
generateResourceContainerTypesbooleanGenerate container types (arrays, maps, pointer output types etc.) for each resource. These are typically used to support external references.

For csharp:

PropertyTypeRequiredDescription
packageReferencesmap[string]No
namespacesmap[string]No
compatibilitystringNo
dictionaryConstructorsbooleanNo

PropertyLanguage

Language-specific info for a property.

For csharp:

PropertyTypeRequiredDescription
namestringNo

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.