Hopefully by now the Chocolatey .nuspec extensions and limitations are documented in a more central way
Posted by jpluimers on 2025/08/08
Chocolatey extends the NuGet file format .nuspec based XML files as base for their packages with at the time of writing very sparse and limited documentation in what it extends, why it does that and what extra limitations it imposes on the fields used inside .nuspec files.
Hopefully by now that has improved, so this post is a reminder to myself to check that out eventually.
At the time of writing, the NuGet .nuspec documentation was at [Wayback/Archive] .nuspec File Reference for NuGet | Microsoft Learn and the file format at [Wayback/Archive] NuGet.Client/nuspec.xsd at dev · NuGet/NuGet.Client. Most fields are defined as primitive data types xs:boolean, xs:string and xs:anyURI (of the 19 available primitive XML SChema (W3C) types). Some composite data types are are composed from them using local and global complexType, most using xs:all, xs:attribute or single-type unbounded xs:sequence (which all imply no particular order).
Since an XML Schema allows to both use restriction and extension on data types (the eXtensible in XML!), making them more strict is a relatively straight-forward operation and has the benefit of having these in a central place.
In the past for more than 5 years [Wayback/Archive] Is there a specification for the package format? · Issue #379 · chocolatey/choco was just pointing to the NuGet .nuspec format, but after a request to re-open new comments were made pointing to a current issue (basically a stub, but still) and a Chocolatey nuspec.xsd file, yay!
Still it was a quest to figure out the additional rules they have added, especially since the documentation was sparse and sloppy.
This made figuring out what and how to change the .nuspec files to fix [Wayback/Archive] Fix issues raised after initial 1.24.1 submission to Chocolatey · Issue #4 · corbob/ChocoPackages was a much harder job than anticipated:
- The individual project rule pages all have their large titles in SCREAMING UPPERCASE. So finding out proper casing requires reading the fine print in the breadcrumb naviation (that also helps figuring out that
PROJECTSOURCEURLmeansProjectSourceUrland notProjects-Our-CE-URL). - The proper casing is actually not proper. For instance the
ProjectSourceUrlshould actually beprojectSourceUrl. It might be that Chocolatey does not enforce thecamelCaseused in the NuGetnuspec.xsd. - Some 60 of the rules are defined as [Wayback/Archive] “stub” site:https://docs.chocolatey.org/en-us/community-repository/moderation/package-validator/rules – Google Search of which many of them only have the really meaningful meaning in their title.
- Example: [Wayback/Archive] CPMR0041 – PROJECTSOURCEURL MATCHES PROJECTURL (NUSPEC) which has the readable breadcrumb leaf “CPMR0041 –
ProjectSourceUrlMatchesProjectUrl(nuspec)” that cases bothProjectSourceUrlandProjectUrlwrong.
- Example: [Wayback/Archive] CPMR0041 – PROJECTSOURCEURL MATCHES PROJECTURL (NUSPEC) which has the readable breadcrumb leaf “CPMR0041 –
- Reading a single title on a submission report can be confusing, especially when it is a stub, to understand the exact meaning. Only after viewing the rule overview at [Wayback/Archive] PACKAGE VALIDATOR RULES (which has the NON UPPPERCASE RULE NAMES: much more readable) one learns all rules are phrased in the “what fails now” style (as opposed to the “how to fix this”): very important to know.
- Chocolatey Software Docs: nuspec | Create Packages is of no use as it points to the NuGet specifications without mentioning any extensions.
- Is there a specification for the package format? · Issue #379 · chocolatey/choco was of no use for the same reason until I followed-up there, see further below.
- Chocolatey Software Docs | Create Packages at least sort of defines
projectUrl(note the definition here is incamelCasein stead of the improperProjectUrl) - Chocolatey Software Docs | CPMR0057 – NUSPEC ENHANCEMENTS MISSING (NUSPEC) (I used the title from the breadcrumb) sort of defines
projectSourceUrl(also incamelCasethere in stead of the improperProjectSourceUrl) - [Wayback/Archive] Chocolatey Software Docs | CPMR0050 –
TITLEMATCHESID(nuspec) defines the difference betweenidandtitlein the body (but has the improper casing in the title). - [Wayback/Archive] Chocolatey Software Docs | CPMR0009 – PROJECTURL MISSING (NUSPEC) (I used the title from the breadcrumb) was of no use as it only explains
projectUrlisneeded, not why it is needed. - [Wayback/Archive] Chocolatey Software Docs | CPMR0038 – LICENSEURL MATCHES PROJECTURL (SCRIPT) (also a stub; mentions
licenseUrlandprojectUrl) - [Wayback/Archive] Chocolatey Software Docs | CPMR0031 – INVALID URL (NUSPEC) at least mentios (but not defines) these fields:
The following URL’s, if invalid, will be marked as a Requirement (needs to be fixed).bugTrackerUrl– RequirementdocsUrl– RequirementiconUrl– RequirementlicenseUrl– RequirementmailingListUrl– RequirementpackageSourceUrl– RequirementprojectSourceUrl– RequirementprojectUrl– RequirementwikiUrl– Requirement
- [Wayback/Archive] Chocolatey Software Docs | CPMR0057 – Nuspec Enhancements Missing (nuspec) (for various ageings of “recent”) at least documents tiny bits of a handful fields:
Please update the nuspec to contain one or more of the following:docsUrl– points to the location of the wiki or docs of the softwaremailingListUrl– points to the forum or email list group for the softwarebugTrackerUrl– points to the location where issues and tickets can be accessedpackageSourceUrl– points to the location of your chocolatey package files in source (e.g.https://github.com/chocolatey-community/chocolatey-packages)projectSourceUrl– points to the location of the underlying software source
- The non-documentation link, but package[Wayback/Archive] Chocolatey Software | (unofficial) Chocolatey .nuspec Checker (Script) 2020.09.21 (from the same author that wrote [Wayback/Archive] Chocolatey Software | (unofficial) Choco Cleaner (Script + Task) 0.0.8.4)
- [Wayback/Archive] ChocolateyPackages/choco-nuspec-checker at master · bcurran3/ChocolateyPackages
choco-nuspec-checker (CNC) is a PowerShell script I designed for Chocolatey package maintainers/creators to check Chocolatey .nuspec files for common errors and omissions… and automatically fix most of them! Find out AND FIX what the Chocolatey validator is going to tell you BEFORE you submit your package. CNC also goes beyond it’s original scope and checks for common Chocolatey install/uninstall script errors and omissions as well.
It does an awful lot of checks.
- [Wayback/Archive] ChocolateyPackages/choco-nuspec-checker at master · bcurran3/ChocolateyPackages
It took quite some effort to figure out where the new fieldnames were introduced. Somehow my Google Fu was not on pare for this endeavour. Anyway, these searches helped me:
- [Wayback/Archive] “ProjectUrl” chocolatey nuspec – Google Search
- [Wayback/Archive] “ProjectSourceUrl” chocolatey nuspec – Google Search
It made me find these GitHub issues
- 20120924 – [Wayback/Archive] [Enhancement] Extra metadata in nuspec for package source url · Issue #172 · chocolatey-archive/chocolatey
Chocolatey is a little different from Nuget.- With NuGet packages, the publisher is usually the author.
- With Chocolatey, most times the guy putting together the package is not the author. The ‘Project Site’ in the gallery /
projectUrlin the nuspec typically points back to the authors project, not the publishers…
When looking in the directory, it can be nice to have a convenient way to get back to the author. - 20141019 – [Wayback/Archive] [Enhancement] Handle extra metadata in nuspec · Issue #101 · chocolatey/chocolatey.org · GitHub (does not exist any more: the whole repository is gone now)
- 20150325 – [Wayback/Archive] Enhance the nuspec – first wave · Issue #205 · chocolatey/choco
Allow the following extra metadata into the nuspec:
projectSourceUrlpackageSourceUrldocsUrlmailingListUrlbugTrackerUrlreplacesprovidesconflicts
Closed on on 20150612
- 20150612 [Wayback/Archive] Enhance the nuspec – second wave (enables fully declarative package manifests) · Issue #325 · chocolatey/choco (work in progress):
- original software version string
supportUrlchatUrl
This catches more of the enhancements noted at https://github.com/chocolatey/chocolatey.org/issues/101 :- ARP Name (with wildcard support) (software Name)
- Software Display Version
- OS versions
- Architectures
- Languages supported
- Silent options – all options supported
- Installer type (can help provide silent options)
- Package specific execution timeout – see Package specific ability to adjust the execution timeout #963
Other things that can be added:- Installer url
- Installer 64 bit url
- installer checksum / checksum x64
- checksumtype / checksumtype x64
…Still work in progress
Some of the above also made it to the [Wayback/Archive] Thread by @jpluimers on Thread Reader App.
All of this could have been so much easier with proper rule enforcement in a Chocolatey specific nuspec.xsd file: you can add documentation there (xs:annotation, xs:appinfo, xs:documentation) parse those and generate documentation web-pages from them (I had forgotten which ones; [Wayback/Archive] site:https://www.oreilly.com/library/view/xml-schema “xs:documentation” – Google Search helped me find them).
I tried to advocate for that by following-up at [Wayback/Archive] Is there a specification for the package format? · Issue #379 · chocolatey/choco, so I was happy to learn that:
- There is a documentation issue at [Wayback/Archive] Create Nuspec Document · Issue #374 · chocolatey/docs which back then was still kind of a stub, but a much fresher one and with a positive phrasing.
- There is a Chocolatey specific nuspec XSD file at [Wayback/Archive] nuget-chocolatey/nuspec.xsd at 2.11_adds · chocolatey/nuget-chocolatey which is a modified copy of [Wayback/Archive] NuGet.Client/nuspec.xsd at dev · NuGet/NuGet.Client.
I posted the results of a diff between [Wayback/Archive] raw.githubusercontent.com/chocolatey/nuget-chocolatey/2.11_adds/src/Core/Authoring/nuspec.xsd and [Wayback/Archive] raw.githubusercontent.com/NuGet/NuGet.Client/dev/src/NuGet.Core/NuGet.Packaging/compiler/resources/nuspec.xsd as a comment to [Wayback/Archive] Create Nuspec Document · Issue #374 · chocolatey/docs.
XML Schema links
To help one understand the above XML Schema types, here are some links:
- [Wayback/Archive]
xs:all(outside a group) — Compositor describing an unordered group of elements. – XML Schema [Book] - [Wayback/Archive]
xs:annotation— Informative data for human or electronic agents. – XML Schema [Book] - [Wayback/Archive]
xs:appinfo— Information for applications. – XML Schema [Book] - [Wayback/Archive]
xs:any— Wildcard to replace any element. – XML Schema [Book] - [Wayback/Archive]
xs:anyURI— URI (Uniform Resource Identifier). – XML Schema [Book] - [Wayback/Archive]
xs:attribute(reference or local definition) — Reference to a global attribute definition or local definition (local definitions cannot be referenced). – XML Schema [Book] - [Wayback/Archive]
xs:boolean— Boolean (trueorfalse). – XML Schema [Book] - [Wayback/Archive]
xs:complexType(global definition) — Global definition of a complex type that can be referenced within the same schema by other schemas. – XML Schema [Book] - [Wayback/Archive]
xs:complexType(local definition) — Complex type local definition (local definitions cannot be referenced). – XML Schema [Book] - [Wayback/Archive]
xs:documentation— Human-targeted documentation. – XML Schema [Book] - [Wayback/Archive]
xs:element(reference or local definition) — Reference to a global element declaration or local definition (local definitions cannot be referenced). – XML Schema [Book] - [Wayback/Archive]
xs:simpleContent— Simple content model declaration. – XML Schema [Book] - [Wayback/Archive]
xs:simpleType(global definition) — Global simple type declaration that can be referenced within the same schema by other schemas. – XML Schema [Book] - [Wayback/Archive]
xs:simpleType(local definition) — Local simple type definition (local definitions cannot be referenced). – XML Schema [Book] - [Wayback/Archive]
xs:string— Any string. – XML Schema [Book]
If you are really in a hardcore mood, you can also look these up in the official [Wayback/Archive] W3C XML Schema Definition Language (XSD) 1.1 Part 1: Structures.
–jeroen
The Wiert Corner - irregular stream of stuff 
Leave a comment