Skip to content

Commit 15d82c3

Browse files
yim-leeyim-lee
authored
Add publication time to registry package release metadata (#6407) (#6413)
* Add publication time to registry package release metadata Motivation: Registry should have information about how a package was published. This includes who published it, who signed it, and when it was published. - "Who published the package release?": this is `metadata.author`, which is already defined in the metadata JSON schema. - "Who signed the package release?": this can be extracted from the signing certificate if signed (requires rdar://107483043 and will be done in separate PR) - "When was the release published?": added in this PR rdar://106674475 Modifications: - Add `originalPublicationTime` to user-provided metadata during publication - Add `publishedAt` to registry's package release metadata response - Update registry API spec * Add publishedAt to PackageSearchClient
1 parent 57096c3 commit 15d82c3

File tree

6 files changed

+295
-96
lines changed

6 files changed

+295
-96
lines changed

‎Documentation/Registry.md

+146-13
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
- [5. Normative References](#5-normative-references)
3434
- [6. Informative References](#6-informative-references)
3535
- [Appendix A - OpenAPI Document](#appendix-a---openapi-document)
36+
- [Appendix B - Package Release Metadata JSON Schema](#appendix-b---package-release-metadata-json-schema)
3637

3738
## 1. Notations
3839

@@ -466,18 +467,20 @@ Link: <https://packages.example.com/mona/LinkedList/1.1.1>; rel="latest-version"
466467
}
467468
}
468469
],
469-
"metadata": { ... }
470+
"metadata": { ... },
471+
"publishedAt": "2023-02-16T04:00:00.000Z"
470472
}
471473
```
472474

473-
The response body MUST contain a JSON object containing the following fields:
475+
The response body SHOULD contain a JSON object containing the following fields:
474476

475-
| Key | Type | Description |
476-
| ----------- | ------ | ----------------------------------------- |
477-
| `id` | String | The namespaced package identifier. |
478-
| `version` | String | The package release version number. |
479-
| `resources` | Array | The resources available for the release. |
480-
| `metadata` | Object | Additional information about the release. |
477+
| Key | Type | Description | Required |
478+
| ------------- | ------ | ----------------------------------------- | :------: |
479+
| `id` | String | The namespaced package identifier. | ✓ |
480+
| `version` | String | The package release version number. | ✓ |
481+
| `resources` | Array | The resources available for the release. | ✓ |
482+
| `metadata` | Object | Additional information about the release. | ✓ |
483+
| `publishedAt` | String | The [ISO 8601]-formatted datetime string of when the package release was published, as recorded by the registry. See related [`originalPublicationTime`](#appendix-b---package-release-metadata-json-schema) in `metadata`. | |
481484

482485
A server SHOULD respond with a `Link` header containing the following entries:
483486

@@ -520,7 +523,8 @@ with a given combination of `name` and `type` values.
520523

521524
#### 4.2.2. Package release metadata standards
522525

523-
SE-391 defines the [JSON schema] for package release metadata that
526+
[Appendix B](#appendix-b---package-release-metadata-json-schema)
527+
defines the JSON schema for package release metadata that
524528
gets submitted as part of the ["create a package release"](#endpoint-6)
525529
request. A server MAY allow and/or populate additional metadata by
526530
expanding the schema. The `metadata` key in the
@@ -1035,7 +1039,7 @@ A client MAY include a multipart section named `metadata`
10351039
containing additional information about the release.
10361040
A client SHOULD set a `Content-Type` header with the value `application/json`
10371041
and a `Content-Length` header with the size of the JSON document in bytes.
1038-
The package release metadata MUST be based on the [JSON schema],
1042+
The package release metadata MUST be based on the [JSON schema](#appendix-b---package-release-metadata-json-schema),
10391043
as discussed in [4.2.2](#422-package-release-metadata-standards).
10401044

10411045
```http
@@ -1058,8 +1062,8 @@ Content-Transfer-Encoding: quoted-printable
10581062

10591063
A server MAY allow and/or populate additional metadata for a release.
10601064

1061-
A server MAY make any properties in the [JSON schema] and additional
1062-
metadata it defines required.
1065+
A server MAY make any properties in the [JSON schema](#appendix-b---package-release-metadata-json-schema)
1066+
and additional metadata it defines required.
10631067

10641068
If a client provides an invalid JSON document,
10651069
the server SHOULD respond with a status code of
@@ -1706,6 +1710,135 @@ components:
17061710

17071711
```
17081712

1713+
## Appendix B - Package Release Metadata JSON Schema
1714+
1715+
The `metadata` section of the [create package release request](#46-create-a-package-release)
1716+
must be a JSON object of type [`PackageRelease`](#packagerelease-type), as defined in the
1717+
JSON schema below.
1718+
1719+
<details>
1720+
1721+
<summary>Expand to view <a href="https://json-schema.org/specification.html">JSON schema</a></summary>
1722+
1723+
```json
1724+
{
1725+
"$schema": "https://json-schema.org/draft/2020-12/schema",
1726+
"$id": "https://github.com/apple/swift-package-manager/blob/main/Documentation/Registry.md",
1727+
"title": "Package Release Metadata",
1728+
"description": "Metadata of a package release.",
1729+
"type": "object",
1730+
"properties": {
1731+
"author": {
1732+
"type": "object",
1733+
"properties": {
1734+
"name": {
1735+
"type": "string",
1736+
"description": "Name of the author."
1737+
},
1738+
"email": {
1739+
"type": "string",
1740+
"format": "email",
1741+
"description": "Email address of the author."
1742+
},
1743+
"description": {
1744+
"type": "string",
1745+
"description": "A description of the author."
1746+
},
1747+
"organization": {
1748+
"type": "object",
1749+
"properties": {
1750+
"name": {
1751+
"type": "string",
1752+
"description": "Name of the organization."
1753+
},
1754+
"email": {
1755+
"type": "string",
1756+
"format": "email",
1757+
"description": "Email address of the organization."
1758+
},
1759+
"description": {
1760+
"type": "string",
1761+
"description": "A description of the organization."
1762+
},
1763+
"url": {
1764+
"type": "string",
1765+
"format": "uri",
1766+
"description": "URL of the organization."
1767+
},
1768+
},
1769+
"required": ["name"]
1770+
},
1771+
"url": {
1772+
"type": "string",
1773+
"format": "uri",
1774+
"description": "URL of the author."
1775+
},
1776+
},
1777+
"required": ["name"]
1778+
},
1779+
"description": {
1780+
"type": "string",
1781+
"description": "A description of the package release."
1782+
},
1783+
"licenseURL": {
1784+
"type": "string",
1785+
"format": "uri",
1786+
"description": "URL of the package release's license document."
1787+
},
1788+
"originalPublicationTime": {
1789+
"type": "string",
1790+
"format": "date-time",
1791+
"description": "Original publication time of the package release in ISO 8601 format."
1792+
},
1793+
"readmeURL": {
1794+
"type": "string",
1795+
"format": "uri",
1796+
"description": "URL of the README specifically for the package release or broadly for the package."
1797+
},
1798+
"repositoryURLs": {
1799+
"type": "array",
1800+
"description": "Code repository URL(s) of the package release.",
1801+
"items": {
1802+
"type": "string",
1803+
"description": "Code repository URL."
1804+
}
1805+
}
1806+
}
1807+
}
1808+
```
1809+
1810+
</details>
1811+
1812+
##### `PackageRelease` type
1813+
1814+
| Property | Type | Description | Required |
1815+
| ------------------------- | :-----------------: | ------------------------------------------------ | :------: |
1816+
| `author` | [Author](#author-type) | Author of the package release. | |
1817+
| `description` | String | A description of the package release. | |
1818+
| `licenseURL` | String | URL of the package release's license document. | |
1819+
| `originalPublicationTime` | String | Original publication time of the package release in [ISO 8601] format. This can be set if the package release was previously published elsewhere.<br>A registry should record the publication time independently and include it as `publishedAt` in the [package release metadata response](#42-fetch-information-about-a-package-release). <br>In case both `originalPublicationTime` and `publishedAt` are set, `originalPublicationTime` should be used. | |
1820+
| `readmeURL` | String | URL of the README specifically for the package release or broadly for the package. | |
1821+
| `repositoryURLs` | Array | Code repository URL(s) of the package. It is recommended to include all URL variations (e.g., SSH, HTTPS) for the same repository. This can be an empty array if the package does not have source control representation.<br/>Setting this property is one way through which a registry can obtain repository URL to package identifier mappings for the ["lookup package identifiers registered for a URL" API](https://github.com/apple/swift-package-manager/blob/main/Documentation/Registry.md#45-lookup-package-identifiers-registered-for-a-url). A registry may choose other mechanism(s) for package authors to specify such mappings. | |
1822+
1823+
##### `Author` type
1824+
1825+
| Property | Type | Description | Required |
1826+
| ----------------- | :-----------------: | ------------------------------------------------ | :------: |
1827+
| `name` | String | Name of the author. | ✓ |
1828+
| `email` | String | Email address of the author. | |
1829+
| `description` | String | A description of the author. | |
1830+
| `organization` | [Organization](#organization-type) | Organization that the author belongs to. | |
1831+
| `url` | String | URL of the author. | |
1832+
1833+
##### `Organization` type
1834+
1835+
| Property | Type | Description | Required |
1836+
| ----------------- | :-----------------: | ------------------------------------------------ | :------: |
1837+
| `name` | String | Name of the organization. | ✓ |
1838+
| `email` | String | Email address of the organization. | |
1839+
| `description` | String | A description of the organization. | |
1840+
| `url` | String | URL of the organization. | |
1841+
17091842
[BCP 13]: https://tools.ietf.org/html/rfc6838 "Media Type Specifications and Registration Procedures"
17101843
[RFC 2119]: https://tools.ietf.org/html/rfc2119 "Key words for use in RFCs to Indicate Requirement Levels"
17111844
[RFC 3230]: https://tools.ietf.org/html/rfc5843 "Instance Digests in HTTP"
@@ -1745,4 +1878,4 @@ components:
17451878
[XCFramework]: https://developer.apple.com/videos/play/wwdc2019/416/ "WWDC 2019 Session 416: Binary Frameworks in Swift"
17461879
[SE-0272]: https://github.com/apple/swift-evolution/blob/master/proposals/0272-swiftpm-binary-dependencies.md "Package Manager Binary Dependencies"
17471880
[Swift tools version]: https://github.com/apple/swift-package-manager/blob/9b9bed7eaf0f38eeccd0d8ca06ae08f6689d1c3f/Documentation/Usage.md#swift-tools-version-specification "Swift Tools Version Specification"
1748-
[JSON schema]: https://github.com/apple/swift-evolution/blob/main/proposals/0391-package-registry-publish.md#package-release-metadata-standards "JSON schema for package release metadata"
1881+
[ISO 8601]: https://www.iso.org/iso-8601-date-and-time-format.html "ISO 8601 Date and Time Format"

0 commit comments

Comments
 (0)