schema-tools

Tools to analyze Pulumi schemas.

Building

go install
go build

Usage

Available Commands:
  compare     Compare two versions of a Pulumi schema
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  squeeze     Utilities to compare Azure Native versions on backward compatibility
  stats       Get the stats of a current schema
  version     Print the version number of schema-tools

Resource Stats

Latest commit on 'master'

$ schema-tools stats --provider azure-native
Provider: azure-native
Total resources: 1056
Unique resources: 1056
Total properties: 13018

Specific tag or commit

schema-tools $./schema-tools stats -p aws -t v5.41.0
Provider: aws
{
  "Functions": {
    "TotalFunctions": 506,
    "TotalDescriptionBytes": 1596936,
    "TotalInputPropertyDescriptionBytes": 98569,
    "InputPropertiesMissingDescriptions": 46,
    "TotalOutputPropertyDescriptionBytes": 0,
    "OutputPropertiesMissingDescriptions": 0
  },
  "Resources": {
    "TotalResources": 1210,
    "TotalDescriptionBytes": 10153011,
    "TotalInputProperties": 12703,
    "InputPropertiesMissingDescriptions": 507,
    "TotalOutputProperties": 13722,
    "OutputPropertiesMissingDescriptions": 709
  }
}

Specific tag or commit with details

schema-tools $./schema-tools stats -p docker -t v4.3.1 -d
Provider: docker
{
  "Functions": {
    "TotalFunctions": 5,
    "TotalDescriptionBytes": 10325,
    "TotalInputPropertyDescriptionBytes": 601,
    "InputPropertiesMissingDescriptions": 8,
    "TotalOutputPropertyDescriptionBytes": 0,
    "OutputPropertiesMissingDescriptions": 0
  },
  "Resources": {
    "TotalResources": 11,
    "TotalDescriptionBytes": 35810,
    "TotalInputProperties": 258,
    "InputPropertiesMissingDescriptions": 56,
    "TotalOutputProperties": 212,
    "OutputPropertiesMissingDescriptions": 56
  }
}

### All Resources:

docker:index/container:Container
docker:index/image:Image
docker:index/network:Network
docker:index/plugin:Plugin
docker:index/registryImage:RegistryImage
docker:index/remoteImage:RemoteImage
docker:index/secret:Secret
docker:index/service:Service
docker:index/serviceConfig:ServiceConfig
docker:index/tag:Tag
docker:index/volume:Volume

### All Functions:

docker:index/getLogs:getLogs
docker:index/getNetwork:getNetwork
docker:index/getPlugin:getPlugin
docker:index/getRegistryImage:getRegistryImage
docker:index/getRemoteImage:getRemoteImage

Schema Comparison

To review potential breaking changes between master and a newer commit from a PR:

$ schema-tools compare -p aws -o master -n 4379b20d1aab018bac69c6d86c4219b08f8d3ec4
Found 1 breaking change:
Function "aws:s3/getBucketObject:getBucketObject" missing input "bucketKeyEnabled"

To review historical changes between two commits or tags like v3 and v4:

(base) schema-tools $schema-tools compare -p docker -o v3.0.0 -n v4.0.0
Found 3 breaking changes:
Function "docker:index/getNetwork:getNetwork" missing input "id"
Type "docker:index/ServiceTaskSpecResourcesLimits:ServiceTaskSpecResourcesLimits" missing property "genericResources"
Type "docker:index/ServiceTaskSpecResourcesLimitsGenericResources:ServiceTaskSpecResourcesLimitsGenericResources" missing

#### New resources:

- `index/image.Image`
- `index/tag.Tag`

#### New functions:

- `index/getLogs.getLogs`
- `index/getRemoteImage.getRemoteImage`

To compare local schema files:

$ schema-tools compare -p aws --old-path ./schemas/aws-old.json --new-path ./schemas/aws-new.json

To emit machine-readable JSON output:

$ schema-tools compare -p docker -o v3.0.0 -n v4.0.0 --json
{
  "summary": [ {"category": "...", "count": 1} ],
  "changes": [...],
  "grouped": {
    "resources": {},
    "functions": {},
    "types": {}
  },
  "new_resources": [...],
  "new_functions": [...]
}

To emit summary-only output (category counts only):

$ schema-tools compare -p docker -o v3.0.0 -n v4.0.0 --summary
Summary by category:
- missing-input: 1

To emit summary-only JSON (category counts only):

$ schema-tools compare -p docker -o v3.0.0 -n v4.0.0 --json --summary
{
  "summary": [
    {
      "category": "missing-input",
      "count": 1
    }
  ]
}

Compare V2 Lookup-First Invariants

The compare pipeline uses one-pass, lookup-first normalization during change generation:

• Token remap lookups call ResolveToken / ResolveNewToken directly per compare decision.
• Field and type-equivalence lookups resolve directly from metadata at call time.
• No constructor service or prebuilt lookup map is required before compare starts.
• Decisions are source-evidence-gated and must remain deterministic.
• Lookup outcomes are explicit: none, resolved, or ambiguous.
• Command rendering does not inject synthetic normalization diagnostics or rewrite emitted lines post hoc.

Squeeze

To show the backwards-incompatible changes between two versioned resources:

$ schema-tools squeeze -s bin/schema-full.json --old azure-native:app:ContainerApp --new azure-native:app/v20230501:ContainerApp
Found 2 breaking changes:
Resource "azure-native:app/v20230501:ContainerApp" missing input "workloadProfileType"
Resource "azure-native:app/v20230501:ContainerApp" missing output "workloadProfileType"

To remove all versioned resources where the removal doesn't break compatibility:

$ schema-tools squeeze -s bin/raw-schema.json --out versions/v2-removed-resources.json