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.

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

add list of serialization use cases #364

Merged
merged 1 commit into from
Jun 6, 2023

Conversation

armintaenzertng
Copy link
Contributor

As discussed in today's serialization meeting, it will be helpful to have a list of use cases that elucidate how serializations will work in action. Examples for these use cases will be included in sub-directories of the different serialization formats.

The current list is only concerned with Core and Software.
We would be happy if other profiles could contribute use cases they have been or still are struggling with.

@davaya
Copy link
Contributor

davaya commented Jun 4, 2023

The jsonld folder already (prior to this PR) contains three files. The package and person examples each show a single Element, but the spdxdocument example is a single file containing multiple elements - i.e., it is a serialized payload example, not a logical Element example.

The use cases file should be phrased to avoid confusion between Elements and payloads - all but two of them are worded as "Element with X":

  • Package with ExternalReference
  • Relationship with Package contains two Files
  • Relationship with time properties
  • SBOM containing two Files
  • SpdxDocument containing two Files
  • SpdxDocument with NamespaceMap
  • SpdxDocument with ExternalMap
  • Person with no CreationInfo

Please change the two use cases of "containing" to "with". It may sound like wordsmithing, but we should reinforce the idea that the logical graph is composed of individual Elements that "reference" each other, while serialized data may "contain" or "reference" other serialized data. (A web page html file with image links doesn't "contain" the image data even though when rendered onscreen the page does "contain" the images.) For the use cases we need a single SBOM element that references two file elements, and a single SpdxDocument element that references two file elements. When those elements are serialized into a payload, the elements may either be nested or with all element values listed directly in the "element" property of the payload.

"With" works equally well to describe nested and listed serializations.

Signed-off-by: Armin Tänzer <armin.taenzer@tngtech.com>
@armintaenzertng
Copy link
Contributor Author

I replaced the two "containing" with "with"

@davaya davaya mentioned this pull request Jun 6, 2023
Copy link
Member

@maxhbr maxhbr left a comment

Choose a reason for hiding this comment

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

LGTM

@goneall goneall self-requested a review June 6, 2023 17:11
@goneall goneall merged commit 8128bd5 into spdx:main Jun 6, 2023
@armintaenzertng armintaenzertng deleted the serializationUseCases branch June 7, 2023 08:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants