docs: new field of license table #1897

bxf12315 · 2025-07-28T07:57:45Z

Rendered version: https://github.com/bxf12315/trustify/blob/adr-new-field-license/docs/adrs/00009-new-field-license.md

Summary by Sourcery

Document the decision to add a new custom_license_refs text[] column to the license table to store custom license identifiers from CycloneDX name entries and SPDX expressions for improved license usage statistics.

New Features:

Propose adding a new custom_license_refs column to the license table to capture custom license names and SPDX license references

Documentation:

Add ADR 00009 documenting the new custom_license_refs field and its usage scenarios for CycloneDX and SPDX

Summary by Sourcery

Document a new ADR to introduce a custom_license_refs text[] column in the license table for capturing custom license references from CycloneDX and SPDX to enhance license usage statistics.

New Features:

Propose adding a custom_license_refs text[] column to the license table to store custom license identifiers from CycloneDX names and SPDX expressions.

Documentation:

Add ADR 00009 documenting the new custom_license_refs field and its usage scenarios for CycloneDX and SPDX.

sourcery-ai · 2025-07-28T07:57:50Z

Reviewer's Guide

This PR adds a new ADR (00009) documenting the decision to introduce a custom_license_refs text[] column to the license table, including its rationale, SQL migration, usage scenarios for CycloneDX and SPDX, and known issues.

Entity relationship diagram for the new custom_license_refs field in the license table

erDiagram
    LICENSE {
        int id
        text text
        text[] spdx_licenses
        text[] spdx_license_exceptions
        text[] custom_license_refs
    }

    LICENSE ||--o{ PACKAGE : contains
    LICENSE ||--o{ SBOM : used_in

Class diagram for the updated License model with custom_license_refs

classDiagram
    class License {
        +int id
        +string text
        +string[] spdx_licenses
        +string[] spdx_license_exceptions
        +string[] custom_license_refs
    }

File-Level Changes

Change	Details	Files
Introduce ADR for new custom_license_refs field	Add draft ADR with context, status, and current license handling overview Include SQL `ALTER TABLE license ADD COLUMN custom_license_refs text[]` statement Provide CycloneDX and SPDX examples illustrating extraction of custom license references Outline known issues and future considerations for document-level references	`docs/adrs/00009-new-field-license.md`

Possibly linked issues

Create a CI workflow to validate fmt, clippy, and tests on PR's #1: The PR adds 'custom_license_refs' to the license table, which addresses the issue's goal of handling custom licenses for better search and statistics.

Tips and commands

Interacting with Sourcery

Trigger a new review: Comment @sourcery-ai review on the pull request.
Continue discussions: Reply directly to Sourcery's review comments.
Generate a GitHub issue from a review comment: Ask Sourcery to create an
issue from a review comment by replying to it. You can also reply to a
review comment with @sourcery-ai issue to create an issue from it.
Generate a pull request title: Write @sourcery-ai anywhere in the pull
request title to generate a title at any time. You can also comment
@sourcery-ai title on the pull request to (re-)generate the title at any time.
Generate a pull request summary: Write @sourcery-ai summary anywhere in
the pull request body to generate a PR summary at any time exactly where you
want it. You can also comment @sourcery-ai summary on the pull request to
(re-)generate the summary at any time.
Generate reviewer's guide: Comment @sourcery-ai guide on the pull
request to (re-)generate the reviewer's guide at any time.
Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
pull request to resolve all Sourcery comments. Useful if you've already
addressed all the comments and don't want to see them anymore.
Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
request to dismiss all existing Sourcery reviews. Especially useful if you
want to start fresh with a new review - don't forget to comment
@sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

Enable or disable review features such as the Sourcery-generated pull request
summary, the reviewer's guide, and others.
Change the review language.
Add, remove or edit custom review instructions.
Adjust other review settings.

Getting Help

Contact our support team for questions or feedback.
Visit our documentation for detailed guides and information.
Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

sourcery-ai

Hey @bxf12315 - I've reviewed your changes and they look great!

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

codecov · 2025-07-28T08:22:06Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.26%. Comparing base (5a4c127) to head (80b5163).
⚠️ Report is 12 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1897      +/-   ##
==========================================
+ Coverage   68.14%   68.26%   +0.11%     
==========================================
  Files         365      367       +2     
  Lines       23123    23216      +93     
  Branches    23123    23216      +93     
==========================================
+ Hits        15757    15848      +91     
- Misses       6485     6488       +3     
+ Partials      881      880       -1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

bxf12315 · 2025-08-05T04:06:50Z

@sourcery-ai summary

bxf12315 · 2025-08-05T04:07:03Z

@sourcery-ai guide

ctron · 2025-08-05T07:47:27Z

docs/adrs/00009-new-field-license.md

+Example:
+
+```json
+{


What would be the other fields of that table entry?

`#[sea_orm(table_name = "license")]
pub struct Model {
#[sea_orm(primary_key)]
pub id: Uuid,
pub text: String,
pub spdx_licenses: Option<Vec>,
pub spdx_license_exceptions: Option<Vec>,

}
`

Maybe you can add those to the example

updated, Please check again.

ctron · 2025-08-05T07:48:55Z

docs/adrs/00009-new-field-license.md

+
+`custom_license_refs`:
+
+```json


Why would we not store the other information (comment, extracted text)?

These pieces of information are already present in licensing_infos.

What the relationship between those two tables?

The current design is not sufficient to support establishing a relationship between these two tables. If we want to build such a relationship, we would need to introduce a mapping-like entity between them. However, this would increase the complexity of both ingestion and querying.

At present, the inclusion of the license name here is actually redundant, and it may also have negative impacts.

It could lead to potential data inconsistencies — for example, if the corresponding data in license_info is deleted, it cannot be deleted here.
However, in our business scenario, we do not delete individual license_info entries; we only delete an entire SBOM. When deleting the entire SBOM, the related records in the license table will naturally be deleted as well, so this design should still be reasonable.

ctron · 2025-08-05T07:51:13Z

docs/adrs/00009-new-field-license.md

+Example:
+
+```json
+{


It looks to me like as if the type doesn't match the declared type above (text[]). This seems to be a map approach, while the column's type is an array of strings.

https://github.com/trustification/trustify/pull/1897/files#diff-1c10ae3082b7c2cf9dd0827b865644565609a6a35c5da2a1030e18f4a5461116R143
It should be multi-line.

How would you map that JSON object into a Vec<String>?

How would you map that JSON object into a Vec<String>?

I do not understand this one.

I did not treat it as a JSON string; I just handled it as a plain string.

The type of the column is Vec<String> in Rust, text[] in SQL. The example provided is a JSON object. How would a JSON object be mapped in a Vec<String>?

ctron · 2025-08-05T07:52:00Z

docs/adrs/00009-new-field-license.md

+  ],
+  "filesAnalyzed": false,
+  "licenseConcluded": "NOASSERTION",
+  "licenseDeclared": "LicenseRef-2 AND LicenseRef-11 AND LicenseRef-BSD",


How would that work with SPDX licenses IDs (non-custom)?

It will parse such license expressions and extract the standard license IDs, storing them in spdx_licenses and spdx_license_exceptions.

mrizzi · 2025-09-02T10:41:00Z

docs/adrs/00009-new-field-license.md

+
+In SPDX, there are two types of licenses: licenseDeclared and licenseConcluded, and the representation is mainly in the form of license expressions, which can include custom license references (licenseRef).
+
+CycloneDX uses only one type, licenseDeclared, but offers three ways to represent it:


According to CycloneDX 1.6 specifications it has both types https://cyclonedx.org/docs/1.6/json/#components_items_licenses_oneOf_i0_items_license_acknowledgement

bxf12315 requested review from ctron and mrizzi July 28, 2025 07:58

sourcery-ai bot reviewed Jul 28, 2025

View reviewed changes

ctron added the ADR label Jul 28, 2025

bxf12315 force-pushed the adr-new-field-license branch 2 times, most recently from af433c0 to 844f3c1 Compare August 5, 2025 03:53

ctron reviewed Aug 5, 2025

View reviewed changes

bxf12315 requested a review from ctron August 6, 2025 14:43

bxf12315 force-pushed the adr-new-field-license branch from 844f3c1 to 7bf378e Compare August 6, 2025 15:05

bxf12315 requested a review from dejanb August 6, 2025 15:09

bxf12315 force-pushed the adr-new-field-license branch from 7bf378e to 26235da Compare August 7, 2025 09:40

docs: new field of license table

80b5163

bxf12315 force-pushed the adr-new-field-license branch from 26235da to 80b5163 Compare August 7, 2025 09:44

mrizzi reviewed Sep 2, 2025

View reviewed changes


		In SPDX, there are two types of licenses: licenseDeclared and licenseConcluded, and the representation is mainly in the form of license expressions, which can include custom license references (licenseRef).

		CycloneDX uses only one type, licenseDeclared, but offers three ways to represent it:


		`custom_license_refs`:

		```json

docs: new field of license table #1897

Are you sure you want to change the base?

docs: new field of license table #1897

Uh oh!

Conversation

bxf12315 commented Jul 28, 2025 • edited by sourcery-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by Sourcery

Summary by Sourcery

Uh oh!

sourcery-ai bot commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviewer's Guide

Entity relationship diagram for the new custom_license_refs field in the license table

Class diagram for the updated License model with custom_license_refs

File-Level Changes

Possibly linked issues

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

sourcery-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

bxf12315 commented Aug 5, 2025

Uh oh!

bxf12315 commented Aug 5, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bxf12315 commented Jul 28, 2025 •

edited by sourcery-ai bot

Loading

sourcery-ai bot commented Jul 28, 2025 •

edited

Loading

codecov bot commented Jul 28, 2025 •

edited

Loading