Extension validation guidelines
Open VSIX Gallery checks uploaded extensions against the rules below. Validation warnings do not prevent publication, but resolving them improves how an extension is presented and protects users from broken or unsafe metadata.
This list is generated from the same rule catalog used by the validator, so every warning emitted by the gallery has a corresponding requirement and justification here.
Manifest metadata
- Provide a non-blank display name.
- Why: The name identifies the extension in gallery search results, feeds, and its details page.
Warning code:manifest.name-missing - Keep the display name at or below 200 characters.
- Why: A bounded name remains usable in gallery navigation, search results, feeds, and API clients.
Warning code:manifest.name-too-long - Provide a non-blank publisher.
- Why: The publisher identifies who maintains the extension and powers the gallery's author pages.
Warning code:manifest.publisher-missing - Keep the publisher at or below 200 characters.
- Why: A bounded publisher name remains usable in gallery pages, feeds, and API clients.
Warning code:manifest.publisher-too-long - Provide a non-blank version.
- Why: Visual Studio and gallery clients need a version to determine which package is current.
Warning code:manifest.version-missing - Keep the version at or below 100 characters.
- Why: A bounded version remains usable in feeds and clients that compare and display package versions.
Warning code:manifest.version-too-long
Icon
- Include a square PNG, GIF, or JPEG icon. The preferred display size is 128x128 pixels, and larger source images are supported.
- Why: An icon makes the extension recognizable. Extension galleries display it at no more than 128x128 pixels.
Warning code:icon.missing - Use PNG, GIF, or JPEG for the source icon packaged inside the VSIX.
- Why: These are the icon formats supported by Visual Studio extension manifests. The gallery separately converts the source icon to WebP for display on this website.
Warning code:icon.unsupported-format - Package the icon at the path referenced by the manifest.
- Why: The gallery cannot display an icon that is declared but absent from the VSIX.
Warning code:icon.file-missing - Keep the source icon at or below 10 MB.
- Why: Optimized icons reduce upload processing, storage, and page-transfer costs.
Warning code:icon.file-too-large - For best results, use a 128x128 pixel icon or a larger source image.
- Why: Extension galleries display icons at no more than 128x128 pixels. Larger images are supported and scaled down, while smaller images can appear blurry when enlarged.
Warning code:icon.invalid-dimensions - Use an icon with equal width and height.
- Why: Extension galleries display icons in a square area; a square source avoids cropping or distortion.
Warning code:icon.not-square - Provide a valid, decodable image file.
- Why: The gallery must be able to decode the source image to verify and display it reliably.
Warning code:icon.invalid-image - Use colors that remain visible on dark backgrounds.
- Why: Visual Studio's Extension Manager and the gallery show icons directly on dark theme backgrounds. An icon whose visible pixels are almost entirely dark can blend into the page.
Warning code:icon.low-contrast-dark-theme - Use colors that remain visible on light backgrounds.
- Why: Visual Studio's Extension Manager and the gallery show icons directly on light theme backgrounds. An icon whose visible pixels are almost entirely light can blend into the page.
Warning code:icon.low-contrast-light-theme
Description
- Provide a description that explains what the extension does.
- Why: The description helps users understand the extension before deciding whether to install it.
Warning code:description.missing - Write a description of at least 40 characters.
- Why: A meaningful sentence gives users enough context to understand the extension's purpose.
Warning code:description.too-short - Keep the manifest description at or below 4,000 characters and put detailed documentation in the README.
- Why: The manifest description is a summary used by gallery surfaces and clients; the README is designed for long-form documentation.
Warning code:description.too-long
License
- Specify a license in the VSIX manifest.
- Why: A license tells users the terms under which they may use the extension and is shown by extension distribution and installation surfaces.
Warning code:license.missing
Links
- Provide a valid HTTP or HTTPS repository URL without embedded credentials.
- Why: A valid web URL keeps gallery links usable and prevents unsupported schemes or embedded credentials.
Warning code:url.repository-invalid - Use HTTPS for the repository URL.
- Why: HTTPS protects users from links whose content or destination could be altered in transit.
Warning code:url.repository-insecure - Provide a valid HTTP or HTTPS repository URL without embedded credentials.
- Why: A valid web URL keeps gallery links usable and prevents unsupported schemes or embedded credentials.
Warning code:url.input-repository-invalid - Use HTTPS for the repository URL.
- Why: HTTPS protects users from links whose content or destination could be altered in transit.
Warning code:url.input-repository-insecure - Provide a valid HTTP or HTTPS issue tracker URL without embedded credentials.
- Why: A valid web URL keeps gallery links usable and prevents unsupported schemes or embedded credentials.
Warning code:url.issue-tracker-invalid - Use HTTPS for the issue tracker URL.
- Why: HTTPS protects users from links whose content or destination could be altered in transit.
Warning code:url.issue-tracker-insecure - Provide a valid HTTP or HTTPS issue tracker URL without embedded credentials.
- Why: A valid web URL keeps gallery links usable and prevents unsupported schemes or embedded credentials.
Warning code:url.input-issue-tracker-invalid - Use HTTPS for the issue tracker URL.
- Why: HTTPS protects users from links whose content or destination could be altered in transit.
Warning code:url.input-issue-tracker-insecure - Provide a valid HTTP or HTTPS README URL without embedded credentials.
- Why: A valid web URL keeps gallery links usable and prevents unsupported schemes or embedded credentials.
Warning code:url.readme-invalid - Use HTTPS for the README URL.
- Why: HTTPS protects users from links whose content or destination could be altered in transit.
Warning code:url.readme-insecure - Provide a valid HTTP or HTTPS README URL without embedded credentials.
- Why: A valid web URL keeps gallery links usable and prevents unsupported schemes or embedded credentials.
Warning code:url.input-readme-invalid - Use HTTPS for the README URL.
- Why: HTTPS protects users from links whose content or destination could be altered in transit.
Warning code:url.input-readme-insecure - Provide a valid HTTP or HTTPS more information URL without embedded credentials.
- Why: A valid web URL keeps gallery links usable and prevents unsupported schemes or embedded credentials.
Warning code:url.more-info-invalid - Use HTTPS for the more information URL.
- Why: HTTPS protects users from links whose content or destination could be altered in transit.
Warning code:url.more-info-insecure - Provide a valid HTTP or HTTPS more information URL without embedded credentials.
- Why: A valid web URL keeps gallery links usable and prevents unsupported schemes or embedded credentials.
Warning code:url.input-more-info-invalid - Use HTTPS for the more information URL.
- Why: HTTPS protects users from links whose content or destination could be altered in transit.
Warning code:url.input-more-info-insecure