1. Docs
  2. Using Pulumi
  3. Pulumi packages
  4. Schema

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

    PropertyTypeRequiredDescription
    namestringYesName is the unqualified name of the package (e.g. “aws”, “azure”, “gcp”, “kubernetes”, “random”)
    displayNamestringNoThe human-friendly name of the package.
    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.

    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.
    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. See Authoring & Publishing for more details.
    publisherstringNoThe name of the person or organization that authored and published the package.
    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.
    languagemap[ObjectTypeLanguage]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.
    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.
    methodsmap[string]stringNoMethods maps method names to functions in this schema.

    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 “boolean”, “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 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".
    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.
    plainbooleanNoPlain indicates that when used as an input, this type does not accept eventual values.

    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).
    replaceOnChangesbooleanNoReplaceOnChanges specifies if the associated object should be updated with a replace operation instead of a update operation.
    willReplaceOnChangesbooleanNoWillReplaceOnChanges indiciates that the provider will replace the resource when this property is changed.

    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 javascript, typescript:

    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.
    respectSchemaVersionbooleanNoUse the package.version field in the generated SDK
    pluginNamestringNoThe name of the plugin, which might be different from the package name.
    pluginVersionstringNoThe version of the plugin, which might be different from the version of the package.

    For python:

    PropertyTypeRequiredDescription
    packageNamestringNoPackageName is an override for the name of the generated python package.
    requiresmap[string]NoDescription for the PyPi 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.
    respectSchemaVersionbooleanNoUse the package.version field in the generated SDK.

    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.
    respectSchemaVersionbooleanUse the package.version field in the generated SDK.

    For csharp:

    PropertyTypeRequiredDescription
    packageReferencesmap[string]No
    namespacesmap[string]No
    compatibilitystringNo
    dictionaryConstructorsbooleanNo
    rootNamespacestringNoThe root namespace that the generated package should live under. This setting defaults to “Pulumi”.
    respectSchemaVersionbooleanNoUse the package.version field in the generated SDK.

    For java:

    PropertyTypeRequiredDescription
    packagesmap[string]NoOverrides for module names to Java package names. Example: “autoscaling/v1” -> “autoscaling.v1”.
    basePackagestringNoPrefixes the generated Java package. This setting defaults to “com.pulumi”.
    buildFilesstringNoGenerates build files for the chosen build tool. Supported values: “gradle”.
    dependenciesmap[string]NoJava dependencies to use with the buildFiles. Example: “com.pulumi.gcp” -> “6.23.0”.

    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.

      Pulumi AI - What cloud infrastructure would you like to build? Generate Program