docs

Signed-off-by: Jan Kowalleck <[email protected]>

Author: jkowalleck

schema/bom-1.7.proto

@@ -384,14 +384,14 @@ message LicenseChoice {
   oneof choice {
     // A license
     License license = 1;
-    // A valid SPDX license expression. Refer to https://spdx.org/specifications for syntax requirements
+    // A valid SPDX license expression. Refer to https://spdx.org/specifications for syntax requirements.
     string expression = 2;
     // TODO
     ExpressionDetailed expression_detailed = 5;
   }
-  // This field must only be used when "expression" is chosen as the License object has its own acknowledgement.
+  // This field must only be used when `expression` is chosen as the other options have their own acknowledgement.
   optional LicenseAcknowledgementEnumeration acknowledgement = 3;
-  // This field must only be used when "expression" is chosen as the License object has its own bom_ref.
+  // This field must only be used when `expression` is chosen as the other options have their own bom_ref.
   optional string bom_ref = 4;
 }
 
@@ -417,22 +417,31 @@ message License {
   optional LicenseAcknowledgementEnumeration acknowledgement = 8;
 }
 
+// Specifies the details and attributes related to a software license. It must be a valid SPDX license expression, along with additional properties such as license acknowledgment.
 message ExpressionDetailed {
-  // TODO
+
+  // Specifies the details and attributes related to a software license identifier.
+  // (An SPDX expression may be a compound of license identifiers.)
   message ExpressionDetails {
-    // TODO
+    // A valid SPDX license identifier. Refer to https://spdx.org/specifications for syntax requirements.
+    // Example values:
+    // - "Apache-2.0",
+    // - "GPL-3.0-only WITH Classpath-exception-2.0"
     string license_identifier = 1;
     // Specifies the optional full text of the attachment
     optional AttachedText text = 2;
   }
 
-  // A valid SPDX license expression. Refer to https://spdx.org/specifications for syntax requirements
+  // A valid SPDX license expression. Refer to https://spdx.org/specifications for syntax requirements.
+  // Example values:
+  // - "Apache-2.0 AND (MIT OR GPL-2.0-only)",
+  // - "GPL-3.0-only WITH Classpath-exception-2.0"
   string expression = 1;
   // An optional identifier which can be used to reference the license elsewhere in the BOM. Uniqueness is enforced within all elements and children of the root-level bom element.
   optional string bom_ref = 2;
   // Declared licenses and concluded licenses represent two different stages in the licensing process within software development. Declared licenses refer to the initial intention of the software authors regarding the licensing terms under which their code is released. On the other hand, concluded licenses are the result of a comprehensive analysis of the project's codebase to identify and confirm the actual licenses of the components used, which may differ from the initially declared licenses. While declared licenses provide an upfront indication of the licensing intentions, concluded licenses offer a more thorough understanding of the actual licensing within a project, facilitating proper compliance and risk management. Observed licenses are defined in `@.evidence.licenses`. Observed licenses form the evidence necessary to substantiate a concluded license.
   optional LicenseAcknowledgementEnumeration acknowledgement = 3;
-  // TODO
+  // Details for parts of the `expression`.
   repeated ExpressionDetails details = 4;
 }
 

schema/bom-1.7.schema.json

@@ -1486,24 +1486,26 @@
               "expression": {
                 "type": "string",
                 "title": "SPDX License Expression",
-                "description": "A valid SPDX license expression.\nRefer to https://spdx.org/specifications for syntax requirements",
+                "description": "A valid SPDX license expression.\nRefer to https://spdx.org/specifications for syntax requirements.",
                 "examples": [
                   "Apache-2.0 AND (MIT OR GPL-2.0-only)",
                   "GPL-3.0-only WITH Classpath-exception-2.0"
                 ]
               },
               "expressionDetails": {
-                "title": "expression details",
+                "title": "Expression Details",
+                "description": "Details for parts of the `expression`.",
                 "type": "array",
                 "items": {
                   "type": "object",
+                  "description": "Specifies the details and attributes related to a software license identifier.\n(An SPDX expression may be a compound of license identifiers.)",
                   "required": [
                     "licenseIdentifier"
                   ],
                   "properties": {
                     "licenseIdentifier": {
                       "title": "License Identifier",
-                      "description": "TODO",
+                      "description": "A valid SPDX license identifier. Refer to https://spdx.org/specifications for syntax requirements.",
                       "type": "string",
                       "examples": [
                         "Apache-2.0",

schema/bom-1.7.xsd

@@ -971,7 +971,7 @@ limitations under the License.
             <xs:extension base="xs:normalizedString">
                 <xs:annotation>
                     <xs:documentation>A valid SPDX license expression.
-                        Refer to https://spdx.org/specifications for syntax requirements
+                        Refer to https://spdx.org/specifications for syntax requirements.
 
                         Example values:
                         - Apache-2.0 AND (MIT OR GPL-2.0-only)
@@ -984,9 +984,21 @@ limitations under the License.
     </xs:complexType>
 
     <xs:complexType name="expressionDetailedType">
+        <xs:annotation>
+            <xs:documentation>Specifies the details and attributes related to a software license. It must be a valid SPDX license expression, along with additional properties such as license acknowledgment.</xs:documentation>
+        </xs:annotation>
         <xs:sequence>
             <xs:element name="details" minOccurs="0" maxOccurs="unbounded">
+                <xs:annotation>
+                    <xs:documentation>Details for parts of the `expression`.</xs:documentation>
+                </xs:annotation>
                 <xs:complexType>
+                    <xs:annotation>
+                        <xs:documentation>
+                            Specifies the details and attributes related to a software license identifier.
+                            (An SPDX expression may be a compound of license identifiers.)
+                        </xs:documentation>
+                    </xs:annotation>
                     <xs:sequence>
                         <xs:element name="text" type="bom:attachedTextType" minOccurs="0" maxOccurs="1">
                             <xs:annotation>
@@ -1004,10 +1016,10 @@ limitations under the License.
                     <xs:attribute name="license-identifier" type="xs:normalizedString" use="required">
                         <xs:annotation>
                             <xs:documentation>
-                                TODO
+                                A valid SPDX license identifier. Refer to https://spdx.org/specifications for syntax requirements.
 
-                                Examples:
-                                - Apache-2.0
+                                Example values:
+                                - Apache-2.0"
                                 - GPL-3.0-only WITH Classpath-exception-2.0
                             </xs:documentation>
                         </xs:annotation>
@@ -1026,7 +1038,7 @@ limitations under the License.
         <xs:attribute name="expression" type="xs:normalizedString" use="required">
             <xs:annotation>
                 <xs:documentation>A valid SPDX license expression.
-                    Refer to https://spdx.org/specifications for syntax requirements
+                    Refer to https://spdx.org/specifications for syntax requirements.
 
                     Example values:
                     - Apache-2.0 AND (MIT OR GPL-2.0-only)