cps-org / cps-org/cps

Proposal: Add `package_url` and `package_provider` to CPS supplemental schema

Open
#97 3 comments 1 reaction 0 assignees View on GitHub
enhancement help wanted scheduled
Dominant language
Python
Stars
191
Forks
14
PR merge metrics
No merged PRs in 30d

Description

**Summary**
Request to add two new CPS **Supplemental** properties: `package_url` and `package_provider`.

These supply provenance and discovery metadata that help consumers trace, reproduce, and report package origins.

This proposal grew out of [spdx-to-cps](https://gitlab.kitware.com/bbean/spdx-to-cps), where we saw a need to represent provenance fields.

As noted in [CMake issue #27128](https://gitlab.kitware.com/cmake/cmake/-/issues/27128):

> *"Sbom generation would like to list all the information it can, including each dependencies Description, PackageUrl, Website, and License."*

This proposal addresses the need for `package_url` (canonical retrievable source) as well as `package_provider` (ecosystem identifier).

---

**Motivation / Problem**
Currently, CPS packages contain metadata about the package name, version, and requirements, but lack a standardized way to indicate:

- Where the package can be retrieved from (URL, registry, distribution archive, etc.).
- Which provider or ecosystem is responsible for the package (e.g., vcpkg, Conan, system package manager).

This information is important for:
- Reproducibility: tools or humans can trace back to the original distribution.
- Provenance: consumers can validate where a package was sourced.
- Ecosystem integration: enabling bridges between CPS and existing package ecosystems.

---

**Proposed Specification Changes (Supplemental)**

1. **`package_url`**
- **Type:** `string`
- **Applies To:** `package`
- **Required:** No
- **Semantics:**
A URL pointing to the canonical location of the package.
This may be:
- A fetchable VCS or distribution URL, e.g.:
`git+https://github.com/madler/zlib@v1.3.1`
`https://example.com/foo-1.2.3.tar.gz`,
- A canonical identifier (e.g. [purl spec](https://github.com/package-url/purl-spec)).

At present, the [`spdx-to-cps`](https://gitlab.kitware.com/bbean/spdx-to-cps) script emits `git+https://...` style URLs.

- **Example:**
```json
{
"package": {
"name": "zlib",
"version": "1.2.11",
"package_url": "git+https://github.com/madler/zlib@v1.3.1"
}
}
```

**Distinction from `website`:**

`package_url` identifies a canonical retrievable source for the package (e.g., VCS URL, distribution archive, or purl), while `website` is informational and intended to point to a project or package homepage for human use.

2. **`package_provider`**
- **Type:** `string`
- **Applies To:** `package`
- **Required:** No
- **Semantics:**
The ecosystem or distribution source that supplied this package.
Intended values may include `vcpkg`, `conan`, `system`, `spack`, etc.
Tools can use this to customize resolution strategies or provenance reports.

- **Example:**
```json
{
"package": {
"name": "zlib",
"version": "1.2.11",
"package_provider": "vcpkg"
}
}
```

---

**Compatibility**
- Additive change, backward compatible.
- Existing consumers that do not recognize these properties may safely ignore them.
- If accepted into the **Supplemental Schema**, tools MAY support them.

Contributor guide

No contributing guide indexed for this repository

Research direction

No file or test is named in the issue; start by locating the CPS Supplemental schema and reviewing the linked spdx-to-cps and CMake context. Done means the schema decision is recorded for both optional package properties with their stated semantics and examples.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.