Publicize search by PackageType (NuGet#2076)

* Update docs to include new packageType parameter.
* Updated some wording. Updated Catalog Data.
* Update query form to include packageType.
* There was a missing comma.

Author: ryuyu

docs/api/_data/catalog-package-details.json

@@ -28,6 +28,13 @@
   "packageHash": "2edCwKLcbcgFJpsAwa883BLtOy8bZpWwbQpiIb71E74k5t2f2WzXEGWbPwntRleUEgSrcxJrh9Orm/TAmgO4NQ==",
   "packageHashAlgorithm": "SHA512",
   "packageSize": 118348,
+  "packageTypes": [
+    {
+      "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#packagetypes/DotnetTool",
+      "@type": "PackageType",
+      "name": "DotnetTool"
+    }
+  ],
   "projectUrl": "https://github.com/NuGet/NuGetGallery",
   "published": "1900-01-01T00:00:00Z",
   "requireLicenseAcceptance": false,

docs/api/_data/search-result.json

@@ -13,6 +13,11 @@
       "authors": [ "NuGet" ],
       "totalDownloads": 141896,
       "verified": true,
+      "packageTypes": [
+        {
+          "name": "Dependency"
+        }
+      ],
       "versions": [
         {
           "version": "3.3.0",

docs/api/catalog-resource.md

@@ -227,6 +227,7 @@ minClientVersion        | string                     | no       |
 packageHash             | string                     | yes      | The hash of the package, encoding using [standard base 64](https://tools.ietf.org/html/rfc4648#section-4)
 packageHashAlgorithm    | string                     | yes      |
 packageSize             | integer                    | yes      | The size of the package .nupkg in bytes
+packageTypes            | array of objects           | no       | The package types specified by the author.
 projectUrl              | string                     | no       |
 releaseNotes            | string                     | no       |
 requireLicenseAgreement | boolean                    | no       | Assume `false` if excluded
@@ -244,6 +245,13 @@ time before the catalog item's commit timestamp.
 The `packageHashAlgorithm` is a string defined by the server implementation representing the hashing algorithm used to
 produce the `packageHash`. nuget.org always used the `packageHashAlgorithm` value of `SHA512`.
 
+The `packageTypes` property will only be present if a package type was specified by the author. If it is present, it will always have at least one (1) entry. Each item in the `packageTypes` array is a JSON object with the following properties:
+
+Name      | Type    | Required | Notes
+--------- | ------- | -------- | -----
+name      | string  | yes      | The name of the package type.
+version    | string  | no       | The version of the package type. Only present if the author explicitly specified a version in the nuspec.
+
 The `published` timestamp is the time when the package was last listed.
 
 > [!Note]

docs/api/search-autocomplete-service-resource.md

@@ -22,6 +22,10 @@ The following `@type` values are used:
 SearchAutocompleteService            | The initial release
 SearchAutocompleteService/3.0.0-beta | Alias of `SearchAutocompleteService`
 SearchAutocompleteService/3.0.0-rc   | Alias of `SearchAutocompleteService`
+SearchAutocompleteService/3.5.0      | Includes support for `packageType` query parameter
+
+### SearchAutocompleteService/3.5.0
+This version introduces support for the `packageType` query parameter, allowing filtering by author defined package types. It is fully backwards compatible with queries to `SearchAutocompleteService`.
 
 ## Base URL
 
@@ -39,7 +43,7 @@ a package typeahead feature in a user interface integrated with a NuGet package
 
 A package with only unlisted versions will not appear in the results.
 
-    GET {@id}?q={QUERY}&skip={SKIP}&take={TAKE}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL}
+    GET {@id}?q={QUERY}&skip={SKIP}&take={TAKE}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL}&packageType={PACKAGETYPE}
 
 ### Request parameters
 
@@ -50,6 +54,7 @@ skip        | URL    | integer | no       | The number of results to skip, for p
 take        | URL    | integer | no       | The number of results to return, for pagination
 prerelease  | URL    | boolean | no       | `true` or `false` determining whether to include [pre-release packages](../create-packages/prerelease-packages.md)
 semVerLevel | URL    | string  | no       | A SemVer 1.0.0 version string 
+packageType | URL    | string  | no       | The package type to use to filter packages (added in `SearchAutocompleteService/3.5.0`)
 
 The autocomplete query `q` is parsed in a manner that is defined by the server implementation. nuget.org supports
 querying for the prefix of package ID tokens, which are pieces of the ID produced by spliting the original by camel
@@ -69,6 +74,10 @@ If `semVerLevel=2.0.0` is provided, both SemVer 1.0.0 and SemVer 2.0.0 compatibl
 [SemVer 2.0.0 support for nuget.org](https://github.com/NuGet/Home/wiki/SemVer2-support-for-nuget.org-%28server-side%29)
 for more information.
 
+The `packageType` parameter is used to further filter the autocomplete results to only packages that have at least one package type matching the package type name.
+If the provided package type is not a valid package type as defined by the [Package Type document](https://github.com/NuGet/Home/wiki/Package-Type-%5BPacking%5D), an empty result will returned.
+If the provided package type is empty, no filter will be applied. In other words, passing no value to the `packageType` parameter will behave as if the parameter was not passed.
+
 ### Response
 
 The response is JSON document containing up to `take` autocomplete results.

docs/api/search-query-service-resource.md

@@ -22,6 +22,10 @@ The following `@type` values are used:
 SearchQueryService            | The initial release
 SearchQueryService/3.0.0-beta | Alias of `SearchQueryService`
 SearchQueryService/3.0.0-rc   | Alias of `SearchQueryService`
+SearchQueryService/3.5.0      | Includes support for `packageType` query parameter
+
+### SearchQueryService/3.5.0
+This version introduces support for the `packageType` query parameter and the `packageTypes` response property, allowing filtering by author defined package types. It is fully backwards compatible with queries to `SearchQueryService`.
 
 ## Base URL
 
@@ -41,7 +45,7 @@ package metadata fields may also be considered.
 
 An unlisted package should never appear in search results.
 
-    GET {@id}?q={QUERY}&skip={SKIP}&take={TAKE}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL}
+    GET {@id}?q={QUERY}&skip={SKIP}&take={TAKE}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL}&packageType={PACKAGETYPE}
 
 ### Request parameters
 
@@ -52,6 +56,7 @@ skip        | URL    | integer | no       | The number of results to skip, for p
 take        | URL    | integer | no       | The number of results to return, for pagination
 prerelease  | URL    | boolean | no       | `true` or `false` determining whether to include [pre-release packages](../create-packages/prerelease-packages.md)
 semVerLevel | URL    | string  | no       | A SemVer 1.0.0 version string 
+packageType | URL    | string  | no       | The package type to use to filter packages (added in `SearchQueryService/3.5.0`)
 
 The search query `q` is parsed in a manner that is defined by the server implementation. nuget.org supports basic
 filtering on a [variety of fields](../consume-packages/finding-and-choosing-packages.md#search-syntax). If no
@@ -72,6 +77,10 @@ If `semVerLevel=2.0.0` is provided, both SemVer 1.0.0 and SemVer 2.0.0 compatibl
 [SemVer 2.0.0 support for nuget.org](https://github.com/NuGet/Home/wiki/SemVer2-support-for-nuget.org-%28server-side%29)
 for more information.
 
+The `packageType` parameter is used to further filter the search results to only packages that have at least one package type matching the package type name.
+If the provided package type is not a valid package type as defined by the [Package Type document](https://github.com/NuGet/Home/wiki/Package-Type-%5BPacking%5D), an empty result will returned.
+If the provided package type is empty, no filter will be applied. In other words, passing no value to the packageType parameter will behave as if the parameter was not passed.
+
 ### Response
 
 The response is JSON document containing up to `take` search results. Search results are grouped by package ID.
@@ -105,6 +114,7 @@ tags           | string or array of strings | no       |
 title          | string                     | no       | 
 totalDownloads | integer                    | no       | This value can be inferred by the sum of downloads in the `versions` array
 verified       | boolean                    | no       | A JSON boolean indicating whether the package is [verified](../nuget-org/id-prefix-reservation.md)
+packageTypes   | array of objects           | yes      | The package types defined by the package author (added in `SearchQueryService/3.5.0`)
 
 On nuget.org, a verified package is one which has a package ID matching a reserved ID prefix and owned by one of the
 reserved prefix's owners. For more information, see the
@@ -119,6 +129,12 @@ Name      | Type    | Required | Notes
 version   | string  | yes      | The full SemVer 2.0.0 version string of the package (could contain build metadata)
 downloads | integer | yes      | The number of downloads for this specific package version
 
+The `packageTypes` array will always consist of at least one (1) item. Package type for a given package ID is considered to be the package types defined by the latest version of the package with respect to the other search parameters. Each item in the `packageTypes` array is a JSON object with the following properties:
+
+Name      | Type    | Required | Notes
+--------- | ------- | -------- | -----
+name      | string  | yes      | The name of the package type.
+
 ### Sample request
 
     GET https://azuresearch-usnc.nuget.org/query?q=NuGet.Versioning&prerelease=false&semVerLevel=2.0.0