manifest

Documentation

Overview

Package manifest reads and checks azd extension manifests.

It exists because extension.yaml fails quietly. azd's published extension.schema.json does not set additionalProperties to false, and the Go model azd builds from the manifest silently drops any field it does not recognize. A misspelled or invented key therefore validates cleanly, loads cleanly, and does nothing. azd-rest carried "minAzdVersion: 1.10.0" for several releases believing it declared a floor on the azd host; no such field exists, so the extension advertised no constraint at all.

The checks here turn that class of mistake into a test failure. They are meant to be called from a single test in each extension repo:

func TestRequiredAzdVersionTracksTheSdk(t *testing.T) {
	err := manifest.CheckRequiredAzdVersion(
		filepath.Join("..", "extension.yaml"),
		filepath.Join("..", "go.mod"),
	)
	require.NoError(t, err)
}

Index

• Variables
• func AzdModuleVersion(goModPath string) (string, error)
• func CheckRequiredAzdVersion(manifestPath, goModPath string) error
• type Manifest
  • func Load(path string) (*Manifest, error)
  • func (m *Manifest) UnknownKeys(allowed ...string) []string

Variables

var KnownKeys = []string{
	"capabilities",
	"dependencies",
	"description",
	"displayName",
	"entryPoint",
	"examples",
	"id",
	"language",
	"mcp",
	"namespace",
	"platforms",
	"providers",
	"requiredAzdVersion",
	"tags",
	"usage",
	"version",
}

KnownKeys are the top-level manifest keys azd actually reads.

Most come from extension.schema.json. "language" is the exception: it is absent from the published schema but present on azd's ExtensionSchema model, where "azd x build" uses it to pick a toolchain. Leaving it out here would flag a field that does real work.

Functions

func AzdModuleVersion

func AzdModuleVersion(goModPath string) (string, error)

AzdModuleVersion returns the azure-dev module version a go.mod requires.

It deliberately rejects pseudo-versions and replace targets by matching only a plain semantic version, because a floor derived from a commit hash would mean nothing to a user installing the extension.

func CheckRequiredAzdVersion

func CheckRequiredAzdVersion(manifestPath, goModPath string) error

CheckRequiredAzdVersion verifies the manifest declares the azd host version the extension is actually built against.

The rule is equality with the azure-dev module in go.mod, not merely a satisfiable constraint. An extension compiled against a given azdext calls gRPC services that only that azd release serves, so the module version is the floor. Declaring anything lower lets azd install the extension onto a host that cannot run it, and the user learns about it as a runtime error rather than a clear install-time message.

The cost of this rule is that a go.mod bump taken purely for a fix still raises the floor. That is the intended trade: a floor that is too high inconveniences someone, a floor that is too low breaks them.

Types

type Manifest

type Manifest struct {
	ID                 string
	Version            string
	RequiredAzdVersion string

	// Keys holds every top-level key in file order, including ones azd
	// ignores. UnknownKeys reads this.
	Keys []string
}

Manifest is the subset of extension.yaml these checks need, plus every top-level key as it appeared on disk.

func Load

func Load(path string) (*Manifest, error)

Load parses an extension manifest.

func (*Manifest) UnknownKeys

func (m *Manifest) UnknownKeys(allowed ...string) []string

UnknownKeys returns the top-level keys azd does not read, excluding any the caller names in allowed.

allowed exists so a repo that deliberately keeps an inert key has to say so out loud in its test, rather than the key drifting in unnoticed.