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

feat: license expression details and properties - text attachment, licensing, etc #599

Open
wants to merge 26 commits into
base: 1.7-dev
Choose a base branch
from
Open

feat: license expression details and properties - text attachment, licensing, etc #599

wants to merge 26 commits into from

Conversation

jkowalleck
Copy link
Member

@jkowalleck jkowalleck commented Feb 20, 2025 •
edited
Loading

As discussed via #549, this PR adds new structures to allow documenting the licensing and "properties" of SPDX expressions
As discussed via #554, this PR adds new structures to allow documenting the license texts for SPDX expressions' individual parts.

TODO

  • agree on data models & finalize examples
  • write the schemata
  • write the spec
  • write a proper summary for this PR

@jkowalleck jkowalleck changed the base branch from master to 1.7-dev February 20, 2025 13:01
@jkowalleck
feat: license expression text attachment
39524a2 
- tests: examples for licenses with text
- tests: draft for expressiosn with text

Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck jkowalleck force-pushed the feat/license-expression-text-attachment branch from dac5995 to 39524a2 Compare February 20, 2025 13:09
@jkowalleck jkowalleck mentioned this pull request Feb 20, 2025
Open
@Joerki Joerki mentioned this pull request Feb 21, 2025
Open
@jkowalleck
tests: fix json example
c1a6b33 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
tests: examples for license expression details
e97c3d3 
as suggested in https://github.com/CycloneDX/specification/pull/599/files#r1965445439

Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
tests: extend/revisit example for expression-details
cebcf7d 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
rework license expression lext attachments and add shema
903cb43 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
ework license expression lext attachments and add shema
59c9a1f 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
rename xml
ee671a8 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
docs: proto
5995a6d 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
struct proto
7701a10 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
docs
561c8dd 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
docs
0dc34e0 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
Copy link
Member Author

@Joerki , I've tried to incorporate your remarks and suggestions.
Also tried to make a schema for them, which lead to the current state.
Please give them a quick review.

This PR will probably sit here for some weeks, as It requires rework in case #582 is moved forward.

@Joerki
Copy link

Joerki commented Feb 25, 2025

@Joerki , I've tried to incorporate your remarks and suggestions. Also tried to make a schema for them, which lead to the current state. Please give them a quick review.

This PR will probably sit here for some weeks, as It requires rework in case #582 is moved forward.

Hi @jkowalleck ,
I had a look both at the JSON and (first time) XML definition.
The JSON schema definition looks fine!
A "LicenseRef-custom-license" example would be a meaningful.
I noticed a difference in the naming JSON: expressionDetails, XML: expressionDetailedType (-> expression-detailed in XML)

I stumbled over the explanation of "content" of the text:
"The attachment data. Proactive controls such as input validation and sanitization should be employed to prevent misuse of attachment text."
Honestly, I do not understand what is meant here. Shouldn't it simply be: The license text?

@jkowalleck
Copy link
Member Author

A "LicenseRef-custom-license" example would be a meaningful.

added via c16b24a

@jkowalleck
Copy link
Member Author

I noticed a difference in the naming [...]

this is not a difference in naming, but in structure.

in JSON, we have this one object that contains the property "expression", and additional properties.
in XML we dont have objects, we need to have named elements. there was none that could "expression" and arbitrary repeated/nested details - so i've created one - called "expressionDetailedType". See my discussionhere: #599 (comment) ff

Hope this helps to understand.

XSD and JSON-schema and ProtoBuf-schema are just implementations of the CycloneDX spec.
The thing is: XML and JSON have different capabilities, and therefore some structures are not the same.

@jkowalleck
docs
7c49125 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
Copy link
Member Author

jkowalleck commented Feb 26, 2025 •
edited
Loading

I stumbled over the explanation of "content" of the text:
"The attachment data. Proactive controls such as input validation and sanitization should be employed to prevent misuse of attachment text."
Honestly, I do not understand what is meant here. Shouldn't it simply be: The license text?

I've copied this over from the existing spec somewhere. Feel free to open an issue/pullrequest to improve this in the spec 👍

In addition, I've revisited the docs and and changed them - hopefully to the better: 7c49125

@jkowalleck
style
267ef6d 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck jkowalleck mentioned this pull request Feb 26, 2025
Draft
@jkowalleck
refactor: rename and docs
85e903d 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
licenseexpression details bom-ref
714813c 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
tests: examples
6aa6fba 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
tests: examples
d1f83ff 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
tests: examples
add2dc1 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
tests: examples
09a8717 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
Copy link
Member Author

updated schema and examples according to latest discussion

@jkowalleck
docs
b2c5ca5 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
docs
41fc9b2 
Signed-off-by: Jan Kowalleck <[email protected]>
jkowalleck
jkowalleck commented Feb 27, 2025
View reviewed changes
schema/bom-1.7.xsd
</xs:complexType>
</xs:element>
<xs:element name="expression" type="bom:licenseExpressionType" minOccurs="0" maxOccurs="1" />
<xs:element name="expression-detailed" type="bom:licenseExpressionDetailedType" minOccurs="0" maxOccurs="1" />
Copy link
Member Author

@jkowalleck jkowalleck Feb 27, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

after #582 got merged

  • make expression-detailed's maxOccurs="unbounded", too.
  • add an example where a declared expression is transferred to a concluded expression. we have an example for this where the ... OR ... expression become a concrete one.

this change would not affect the spec or scope of this feature, and will not interrupt the standardization process.

Copy link
Member

Choose a reason for hiding this comment

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

Is there a reason why this is called expression-detailed and the JSON is called expressionDetails. Not too worried about the hyphen, rather detailed vs details.

Copy link
Member Author

@jkowalleck jkowalleck Mar 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

  • details - these are the details
  • detailed - that is the thing that contains the details.

@jkowalleck jkowalleck marked this pull request as ready for review February 27, 2025 15:44
@jkowalleck jkowalleck requested a review from a team as a code owner February 27, 2025 15:44
@jkowalleck jkowalleck changed the title [WIP] feat: license expression text attachment feat: license expression text attachment Feb 27, 2025
@jkowalleck
Copy link
Member Author

I think all needed tasks on this PR were touched. it is ready for review.
Thank you, @Joerki , for your persistence and patience during the draft process.

@jkowalleck
feat: license url
c974a3c 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck jkowalleck changed the title feat: license expression text attachment feat: license expression details and properties - text attachment, licensing, etc Feb 27, 2025
@jkowalleck jkowalleck linked an issue Feb 27, 2025 that may be closed by this pull request
[FEATURE]: "properties" on an SPDX-expression license #549
Open
@jkowalleck
feat: license expression licensing and properties
bfd9eb4 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
tests
5b12e67 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck jkowalleck force-pushed the feat/license-expression-text-attachment branch from 49bded2 to 5b12e67 Compare February 27, 2025 16:36
@jkowalleck
Copy link
Member Author

RFC notice sent.

Public RFC period ends April 8, 2025

@jkowalleck jkowalleck added request for comment ready for review draft RFC notice sent A public RFC notice was distributed to the CycloneDX mailing list for consideration and removed prototype labels Mar 11, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@Joerki Joerki Joerki left review comments

@stevespringett stevespringett stevespringett approved these changes

Assignees
No one assigned
Labels
draft proposed core enhancement ready for review request for comment RFC notice sent A public RFC notice was distributed to the CycloneDX mailing list for consideration
Projects
None yet
Milestone
No milestone
3 participants
@jkowalleck @Joerki @stevespringett