Add Package Purpose field #622

nishakm · 2022-02-08T00:05:01Z

Fixes #621

Signed-off-by: Nisha K [email protected]

nishakm · 2022-02-08T00:06:44Z

@goneall, @iamwillbar This is a first-pass PR. A review is appreciated :)

nishakm · 2022-02-08T13:46:04Z

swinslow · 2022-02-08T14:12:36Z

Thanks for this @nishakm! I haven't been closely involved with the discussions around adding a Package Purpose field, but here are a few random thoughts anyway :)

For the PR, should this maybe be merging into a development/v2.3 branch rather than v2.2.2? I think 2.2.2 would be a point release, just for bugfixes but not to add new fields. @goneall @kestewart do we need / want to create a separate development/v2.3 branch?
I tend to think that it should be optional and the cardinality should be 0..* rather than 1..1:
- 0 rather than 1 on the left, because I don't think it should be a mandatory field. Both because (A) not all use cases for SPDX Documents are going to be appropriate (or possible) to define a Package Purpose for every Package; and also (B) because it would make existing 2.1, 2.2, etc. SPDX Documents no longer valid, which would be a breaking change for a minor release.
- * rather than 1 on the right, because there may be cases where a Package has multiple "Purposes". E.g., a Package could contain the source code for both an application and a library, and therefore could have 3 PackagePurposes. I'm also thinking by comparison the File Type field, which has similar purpose and values and is 0..*
This is a more minor point, but it would also probably be useful to clarify what is meant by some of the different values, e.g. the distinction between APPLICATION vs. FRAMEWORK vs. LIBRARY.
- The existing File Type field says that APPLICATION there means a specific category of MIME types; does that apply here also?
- I'm not sure if there's an obvious distinction of FRAMEWORK vs. LIBRARY -- there probably is, but it might be helpful to clarify that.

Hope this helps -- and apologies if any of this is contrary to things the tech team has discussed separately!

nishakm · 2022-02-08T17:23:04Z

Should I be turning this into a Draft PR?

goneall · 2022-02-09T04:37:44Z

Suggest adding one more enumeration:

FILE - A single distributed file that can be independently distributed (e.g. a properties file or a configuration file)

This would allow mapping to the CycloneDX file type and also solve some of the issues @rjb4standards has raised.

goneall · 2022-02-09T04:40:14Z

I tend to think that it should be optional and the cardinality should be 0..* rather than 1..1

I'm leaning toward 0..1 and changing the semantics slightly to be the "primary" purpose of the package. This would making the mappings to CycloneDX easier.

That being said, there is value to having the multiple purposes represented in that it may help identify expected properties to be present. However, this scenario may be better addressed through Profiles rather than having multiple purposes.

puerco · 2022-02-09T05:23:33Z

Thanks for filing this @nishakm!

I agree with @swinslow and @goneall , I would not make it mandatory as it would break compatibility with older docs.

I'm wondering if purpose really captures the notion we want. Talking about purpose sets the origin of the subject matter within the SBOM. In other words, it sounds as if the SBOM were dictating what the software should be used for while we are really trying to indicate what kind of bundle the package is describing. The said bundle has its inherent properties which the SBOM can only describe but not set.

I'm sorry, I know it is ontological pedantry, I just wanted to note the misalignment. I think I would add an enumerated PackageKind or PackageType mimicking FileType, but if naming it Purpose makes it compatible with 3.0, then there's no point to discuss. :)

rjb4standards · 2022-02-09T12:33:55Z

I believe the 2.3 effort is considering the addition of a Classification element; I'm wondering if PackageType would be more appropriate and in harmony with 3.0, if @puerco suggestion passes muster.

The 2.3 effort is intended to address DocFest issues involving NTIA minimum elements and is considering additional elements under the Package object:
Classification
AttestationsURL or something similar

kestewart

Thanks for getting this started @nishakm! Nice work.

Agree with Gary - this should be optional, so Cardinality 0..1

Of the Purposes (or Classifications) we've got listed, some are beyond software, so we should discuss further.

We should probably discuss if the Examples should include JSON as well at this point? Topic for the next tech call I guess.

kestewart · 2022-02-11T01:40:53Z

@rjb4standards - FileTypes is referencing MIME types today, so as this has a different semantics, we should use a different term to describe it. Classification, Purpose, PrimaryPurpose, ???

yeah let's see if we can come to agreement either in this thread or at one of the meetings.

rjb4standards · 2022-02-11T12:45:17Z

I defer to the group consensus on the name to use. I'll be happy if I can report a version on a file that is part of an installation package. This fills the NTIA minimum check in SAG-PM that is kicking out SPDX SBOM for non-conformance with NTIA minimum standards. That solves a problem for me.

Also, we are currently coding in support for CycloneDX VEX for vulnerability reporting and look forward to doing the same for whatever the SPDX defects team produces to answer the question:
What is the vulnerability status of product P, version V from Supplier S at time(t) at the SBOM component level?

Thanks to all for their technical contributions in helping to solve these problems.

seabass-labrax · 2022-02-11T15:28:56Z

Suggest adding one more enumeration:

* FILE - A single distributed file that can be independently distributed (e.g. a properties file or a configuration file)

@goneall, wouldn't a FILE always be for a specific purpose? For instance it could be a PATCH or CONFIGURATION.

rjb4standards · 2022-02-11T15:38:08Z

+1 for FILE as a catchall for objects that have a version identifier that don't fit comfortably into another calss.

goneall · 2022-02-11T21:01:35Z

wouldn't a FILE always be for a specific purpose? For instance it could be a PATCH or CONFIGURATION.

@seabass-labrax I agree a FILE will likely have a specific purpose, however, it may not be easy for the document creator to know the purpose of the file and it may not always be important to the use case.

I would suggest having a generic FILE purpose and if there are specific use cases where there is value in knowing the purpose having those as additional purposes.

rjb4standards · 2022-02-11T21:07:21Z

Quick question, is PURPOSE the current element name to represent CLASSIFICATION info, i.e. File, Library, installPackage, etc. in V 2.3 or are these two different concepts?
Thanks...

goneall · 2022-02-12T01:33:17Z

Quick question, is PURPOSE the current element name to represent CLASSIFICATION info, i.e. File, Library, installPackage, etc. in V 2.3 or are these two different concepts?

I am thinking we only have one new property to represent CLASSIFICATION info.

rjb4standards · 2022-02-12T12:07:15Z

Thanks, Gary. I can live with a minimum of 2 classifications:
Installation
File
But will be happy to support whatever the team decides for classifications.
The other important item for v 2.3 is the ability to identify an SBOM with a vulnerability report, that updates independently of the SBOM, and is always available for download to check the vulnerability status of the SBOM over time.

nishakm · 2022-02-14T14:19:47Z

To summarize everyone's feedback thus far:

Cardinality should be 0..1
Add File enumeration: FILE - A single file that can be independently distributed (e.g. a properties file or a configuration file)

Do I understand correctly that we are unclear on whether this field should be "PackagePurpose" or "PackageType"?

goneall · 2022-02-14T17:19:50Z

Do I understand correctly that we are unclear on whether this field should be "PackagePurpose" or "PackageType"?

@iamwillbar - Did we already discuss and agree on the name for this field? If so, we should go with the previously chosen field name.

iamwillbar · 2022-02-14T17:21:13Z

@goneall For SPDX 3.0 there was agreement on PackagePurpose. Type was deemed to be ambiguous.

nishakm · 2022-02-15T17:34:29Z

On Cardinality: 0..* is preferred.

nishakm · 2022-02-15T17:36:10Z

From Kate: FILE is confusing. Need another term. FIRMWARE could also be a file.

seabass-labrax · 2022-02-15T17:39:00Z

@nishakm, I would also agree with expanding the cardinality to 0..*, as this would abate my concern about FILE as a type limiting future refinement of the SBOM when a concrete purpose is discovered.

I also agree with Kate's point that FILE could be confused with the file information capability of the SPDX specification. I suggested MONOLITHIC at the 2022-02-15 meeting but Kate had some reservations about that!

nishakm · 2022-02-25T21:24:41Z

@kestewart @goneall Will a 2.3 branch be created soon? :)

goneall · 2022-02-25T23:24:45Z

@kestewart @goneall Will a 2.3 branch be created soon? :)

@kestewart @tsteenbe were you going to set this up?

kestewart · 2022-03-08T17:25:13Z

@nishakm - please update fixes, and submit to 2.3 branch.

swinslow

I have a few specific comments / suggested edits for particular parts of this, which I'm including inline.

I'd also asked earlier in the conversation thread about whether some of the definitions can be clarified, in particular FRAMEWORK vs. LIBRARY. But I know I haven't been on tech team calls for a long time so you may have discussed or resolved any of these comments already. Just sharing in case they're helpful. Thanks!

swinslow · 2022-03-09T18:11:06Z

chapters/package-information.md

+| Attribute | Value |
+| --------- | ----- |
+| Required | Yes |
+| Cardinality | 0..* |


If Cardinality will be 0..*, then I think Required should be "No" rather than "Yes"?

swinslow · 2022-03-09T18:13:44Z

chapters/package-information.md

+`APPLICATION` if the package is a software application;
+`FRAMEWORK` if the package is a software framework;
+`LIBRARY` if the package is a software library;
+`CONTAINER` if the package refers to a container image which can be used by a container runtime application;


Here and below, maybe consider whether "refers to" is the intended language to use here?

In the first few entries, it says "if the package is a...". Is it meant to mean something different where it says "refers to" instead of "is"?

This one is hard - containers are usually declared in the form of "name:tag" and this refers to a remote tag which points to a merkle tree. Eventually, the leaf artifacts are downloaded by the client but container users have no visibility into this. So yes, I intentionally used "refers to", but I am willing to change it to something more appropriate.

swinslow · 2022-03-09T18:16:15Z

chapters/package-information.md

+`LIBRARY` if the package is a software library;
+`CONTAINER` if the package refers to a container image which can be used by a container runtime application;
+`OPERATING-SYSTEM` if the package refers to an operating system;
+`DEVICE` if the package refers to a chipset, processor, or electronic board;


I'm not sure I understand the meaning of DEVICE as defined here. Is the intention that this would be used for:

files which are the actual embodiment of a chipset, etc. (such as PCB images, or VHDL files, etc.); or

files which are specific to a particular device (such as architecture-specific files in the Linux kernel sources)

I'm guessing the intention is 1 but not 2, but the current definition seems to potentially apply to either one... maybe consider clarifying whether that's the intended meaning.

IIRC "DEVICE" is one of the CycloneDX enumerations.

swinslow · 2022-03-09T18:17:49Z

chapters/package-information.md

+`FIRMWARE` if the package provides low level control over a device's hardware;
+`SOURCE` if the package is a collection of source files;
+`ARCHIVE` if the package refers to an archived collection of files (.tar, .zip, etc);
+`FILE` if the package is a single file which can be independently distributed (configuration file, statically linked binary, Kubernetes deployment, etc);


"Kubernetes deployment" seems a bit odd to call out here. Is Kubernetes always or typically deployed as a single file? Apologies if it is, I genuinely don't know :)

It's a YAML file that directs kubernetes to pull and deploy 1 or more containers. I would say it's similar to a config file.

swinslow · 2022-03-09T18:18:21Z

chapters/package-information.md

+
+The metadata for the Package Purpose field is shown in Table 36.
+
+**Table 36 — Metadata for the package name field**


The caption here says "the package name field", should that be "the package purpose field"?

@nishakm does this proposal require the use of "CAPITAL" letters for the enumerated set of 'PackageProposal" content model members? Thanks.

Typically, enumerations are written with CAPITAL letters, at least in code. To be honest, I was just following the pattern in the model document :).
https://github.com/spdx/meetings/blob/main/tech/Model.png

nishakm · 2022-04-01T16:01:35Z

Some questions have come up that I would like clarification on:

Alternative to "FILE" as the enumeration of singleton file distribution
Addition of "INSTALL" enumeration
Clarification of "DEVICE" enumeration
How to describe "CONTAINER" enumeration
What to use for kubernetes distribution

rjb4standards · 2022-04-01T16:18:10Z

Suggestion:
Alternative to "FILE" as the enumeration of singleton file object

kestewart · 2022-04-26T16:33:19Z

From discussion on call.

Agreement to add:
INSTALL - purpose to identify as installable image (ie. RPM, Deb, archive file, etc.)

Next steps: Nisha to revise PR, then submit for re-review.

rjb4standards · 2022-04-27T21:52:04Z

@nishakm , please include the proposed language for section 5.2 in your edits. Will need some cleanup to reflect consensus position changes since this was produced, i.e. classification should be replaced with PackagePurpose and the enumeration list needs to be replaced. Thanks.. #628

nishakm · 2022-04-28T17:25:08Z

@rjb4standards Not sure if I added the information you requested. Please review.

rjb4standards · 2022-04-28T17:42:42Z

chapters/package-information.md

+a LICENSE file
+a CHANGE log 
+a properties file
+```


@nishakm this looks good. Will need to sync this material with section 5.2.2 which needs to be updated accordingly
https://github.com/spdx/spdx-spec/blob/development/v2.3/chapters/composition-of-an-SPDX-document.md
:
5.2.2 Package information section

If SPDX information is being used to describe packages, then one instance of the Package Information per package being described shall exist. It provides important meta information about the package as a whole. Packages are an abstract concept that can be used to refer to any distribution of software, typically consisting of one or more files and capable of containing sub-packages. Starting with SPDX 2.0, it is not necessary to have a package wrapping a set of files.

A Package refers to any unit of content that can be associated with a distribution of software. Typically, a Package is composed of one or more files. An SPDX document may, but is not required to, provide details about the individual files comprising a Package (see Clause 8).

Any of the following non-limiting examples may be (but are not required to be) represented in SPDX as a Package:

Oh I see! I will update accordingly.

rjb4standards · 2022-04-28T17:45:53Z

Nisha, I added a comment regarding the need to sync up section 5.2.2 with section 7 concepts. Thanks, Dick Brooks Active Member of the CISA Critical Manufacturing Sector, Sector Coordinating Council – A Public-Private Partnership <https://reliableenergyanalytics.com/products> Never trust software, always verify and report! ™ <http://www.reliableenergyanalytics.com/> http://www.reliableenergyanalytics.com Email: ***@***.***> ***@***.*** Tel: +1 978-696-1788 From: nisha ***@***.***> Sent: Thursday, April 28, 2022 1:25 PM To: spdx/spdx-spec ***@***.***> Cc: Dick Brooks ***@***.***>; Mention ***@***.***> Subject: Re: [spdx/spdx-spec] Add Package Purpose field (PR #622) @rjb4standards <https://github.com/rjb4standards> Not sure if I added the information you requested. Please review. — Reply to this email directly, view it on GitHub <#622 (comment)> , or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABFI3NHX2MAOWHZGXXW6CJDVHLCX5ANCNFSM5NY5JTWA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

nishakm · 2022-05-02T17:26:08Z

@rjb4standards I just realized what you were asking as a request to sync the package information section. There is a lot to synchronize, so if you don't mind, I would like to submit a separate PR for that bit once this PR is merged. I think you filed an issue for it so I will refer to that.

rjb4standards · 2022-05-02T17:28:05Z

No problem at all Nisha - I defer to your better judgement as to how to accomplish this matter. Thanks for the update.

- Add information about "package" in the information section - Add metadata about Package Purpose Fixes spdx#621 Signed-off-by: nisha <[email protected]>

kestewart added this to the 2.3 milestone Feb 11, 2022

kestewart requested changes Feb 11, 2022

View reviewed changes

rnjudge mentioned this pull request Feb 25, 2022

Denote container package type in SPDX docs tern-tools/tern#1129

Open

iamwillbar mentioned this pull request Mar 1, 2022

Punch List: File spdx/spdx-3-model#12

Closed

3 tasks

kestewart mentioned this pull request Mar 8, 2022

Proposed language to broaden Package semantics to accommodate classification concept in V 2.3 re: Issue 621 #628

Closed

nishakm changed the base branch from development/v2.2.2 to development/v2.3 March 9, 2022 01:41

nishakm force-pushed the 621-package-purpose branch from 613227d to 91a9133 Compare March 9, 2022 01:51

swinslow reviewed Mar 9, 2022

View reviewed changes

nishakm force-pushed the 621-package-purpose branch from 91a9133 to 555cc32 Compare April 1, 2022 15:55

nishakm requested a review from kestewart April 1, 2022 15:55

nishakm force-pushed the 621-package-purpose branch from 555cc32 to 1026215 Compare April 1, 2022 16:03

kestewart approved these changes Apr 26, 2022

View reviewed changes

tsteenbe force-pushed the development/v2.3 branch from 0235fae to 957d16e Compare April 27, 2022 17:52

nishakm force-pushed the 621-package-purpose branch 2 times, most recently from ba088fe to 722bd20 Compare April 28, 2022 17:22

nishakm requested a review from kestewart April 28, 2022 17:24

nishakm force-pushed the 621-package-purpose branch from 722bd20 to d5a0c46 Compare April 28, 2022 17:32

rjb4standards reviewed Apr 28, 2022

View reviewed changes

nishakm force-pushed the 621-package-purpose branch from d5a0c46 to 0531f15 Compare May 2, 2022 17:23

nishakm mentioned this pull request May 2, 2022

Resolve differences between top level composition doc and package information section #668

Closed

seabass-labrax mentioned this pull request May 9, 2022

json SPDX invalid format anchore/syft#992

Closed

seabass-labrax approved these changes May 10, 2022

View reviewed changes

Add Package Purpose field

d66bab6

- Add information about "package" in the information section - Add metadata about Package Purpose Fixes spdx#621 Signed-off-by: nisha <[email protected]>

nishakm force-pushed the 621-package-purpose branch from 0531f15 to d66bab6 Compare May 10, 2022 16:58

kestewart merged commit 185a7d1 into spdx:development/v2.3 May 10, 2022

seabass-labrax approved these changes May 10, 2022

View reviewed changes

seabass-labrax mentioned this pull request Jun 16, 2022

Should packagePurpose have cardinality 0..1? #720

Closed


		The metadata for the Package Purpose field is shown in Table 36.

		Table 36 — Metadata for the package name field

Add Package Purpose field #622

Add Package Purpose field #622

Conversation

nishakm commented Feb 8, 2022

nishakm commented Feb 8, 2022

nishakm commented Feb 8, 2022

swinslow commented Feb 8, 2022

nishakm commented Feb 8, 2022

goneall commented Feb 9, 2022

goneall commented Feb 9, 2022

puerco commented Feb 9, 2022

rjb4standards commented Feb 9, 2022 • edited Loading

kestewart left a comment

Choose a reason for hiding this comment

kestewart commented Feb 11, 2022

rjb4standards commented Feb 11, 2022

seabass-labrax commented Feb 11, 2022

rjb4standards commented Feb 11, 2022

goneall commented Feb 11, 2022

rjb4standards commented Feb 11, 2022

goneall commented Feb 12, 2022

rjb4standards commented Feb 12, 2022

nishakm commented Feb 14, 2022

goneall commented Feb 14, 2022

iamwillbar commented Feb 14, 2022

nishakm commented Feb 15, 2022

nishakm commented Feb 15, 2022

seabass-labrax commented Feb 15, 2022

nishakm commented Feb 25, 2022

goneall commented Feb 25, 2022

kestewart commented Mar 8, 2022

swinslow left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nishakm commented Apr 1, 2022

rjb4standards commented Apr 1, 2022 • edited Loading

kestewart commented Apr 26, 2022

rjb4standards commented Apr 27, 2022 • edited Loading

nishakm commented Apr 28, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rjb4standards commented Apr 28, 2022 via email

nishakm commented May 2, 2022

rjb4standards commented May 2, 2022

rjb4standards commented Feb 9, 2022 •

edited

Loading

rjb4standards commented Apr 1, 2022 •

edited

Loading

rjb4standards commented Apr 27, 2022 •

edited

Loading