Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update SPDX predicate specification #187

Merged
merged 2 commits into from
Apr 12, 2023
Merged

Update SPDX predicate specification #187

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
89d76d6
Update SPDX predicate specification
danbev Apr 12, 2023
47c66bf
squash! Update SPDX predicate specification
danbev Apr 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 39 additions & 12 deletions spec/predicates/spdx.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Predicate type: SPDX

Type URI: (tentative) https://spdx.dev/Document
Type URI: https://spdx.dev/Document
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we somehow indicate that the Type URI MUST include a version?

Suggested change
Type URI: https://spdx.dev/Document
Type URI: https://spdx.dev/Document/v${SPDX_MAJOR}.${SPDX_MINOR}

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That makes sense to me 👍

It would probably makes sense to also update the CycloneDX predicate specification in that case, as it does not include the version in the Type URI:

Type URI: https://cyclonedx.org/bom

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this idea, though we haven't required this in other predicate definitions either.

This may be a question beyond the scope of this PR, but it seems like we might want to be clearer in our documentation for predicateTypes.


Version: 1.0.0
Version: 2.3

TODO: Ask SPDX project to choose a URI and to review this spec. Ideally the URI
danbev marked this conversation as resolved.
Show resolved Hide resolved
would resolve to this file. Also, decide whether we want the version number to
Expand All @@ -12,36 +12,63 @@ number in URI).
## Purpose

A Software Bill of Materials type following the
[SPDX standard](https://spdx.dev/specifications/).
[SPDX Specification].

This allows to represent an "exportable" or "published" software artifact. It
can also be used as an entry point for other types of in-toto attestation when
performing policy decisions.

## Prerequisites

The in-toto [attestation] framework and a [SPDX generation tool].

## Model

This is a predicate type that fits within the larger [Attestation] framework.

## Schema

The schema of this predicate type is documented in the
[SPDX Specification].

### Parsing Rules

The parsing rules for this predicate type are documented in the
[SPDX Specification].

### Fields

The fields that make up this predicate type are documented in the
[SPDX specification].

The `predicate` contains a JSON-encoded SPDX document.
The `subject` contains whatever software artifacts are to be associated with
this SPDX document.

## Example

```jsonc
{
// Standard attestation fields:
"_type": "https://in-toto.io/Statement/v0.1",
"subject": [{ ... }],

// Predicate:
"predicateType": "https://spdx.dev/Document",
"predicateType": "https://spdx.dev/Document/v2.3",
"predicate": {
"SPDXID" : "SPDXRef-DOCUMENT",
"spdxVersion" : "SPDX-2.2",
"spdxVersion" : "SPDX-2.3",
...
}
}
```

_(Note: This is a Predicate type that fits within the larger
[Attestation](../README.md) framework.)_
## Changelog and Migrations

The `predicate` contains a JSON-encoded SPDX document. The SPDX format has a
mandatory `spdxVersion` field, so we omit the version number from the
`predicateType` URI to avoid confusion.
### Version 2.3

The `subject` contains whatever software artifacts are to be associated with
this SPDX document.
- Added version to predicateType

[Attestation]: ../README.md
[SPDX specification]: https://spdx.github.io/spdx-spec/v2.3
[SPDX generation tool]: https://spdx.dev/resources/tools/