V1.5 dev resourceReferenceChoice ref clarifications #251

jkowalleck · 2023-06-17T17:49:37Z

@mrutkows could you help improve the schema in terms of documentation?
the resourceReferenceChoice.ref is intended to link to a bom-ref.

Question: Must this link to a bom-ref in the same document, or would it also be okay to link to a bom-ref in another document aswell, using a BOM-Link?
depending on your answer, I might need to modify the content of this PR.

see comments below ...

there was some documentation enhancement brought into the schema to make this much clearer.
followup of #236 & #222
caused by #136 and #217

Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com>

jkowalleck · 2023-06-17T18:00:10Z

current proposal was designed to document that the linked bom-ref must be in the same document. it is possible to link to external documents only, instead. or allow link to same AND external documents.

Need an answer: what should it be? Either any document or same document only or external document only?

Will modify this PR depending on the answer.

mrutkows · 2023-06-19T12:50:08Z

@jkowalleck You have it correct in its intent. That is, for workflows (formulation) it was intended to link to resources (components/services) in the same BOM. The "choice" allows you to use an externalReference (which is what was used for a bom-link) although I have seen hints of discussions a couple weeks ago about making an independent object for BOMLink. If indeed there is a movement away from externalReference for bom-link (that is, it will be deprecated, then that new option could possibly be added to the "choice" object.

The whole reason choice is exists is to link to resources locally, via bom-ref or externally via externalReference (as these were the only two options I was aware of at time of authoring).

jkowalleck · 2023-06-19T12:58:25Z

@mrutkows
current draft is "either bomRef in current document, or externalReference".
And keep in mind: "externalReference" was already modified to be "either URI or BOM-Link." see https://github.com/CycloneDX/specification/blob/v1.5-dev/schema/bom-1.5.xsd#L1405

jkowalleck · 2023-06-19T13:01:12Z

as it was intended to link to components/services in current or external docuemnts (#251 (comment))
i wil also add the dedicated element for it.

mrutkows · 2023-06-19T13:02:40Z

@jkowalleck hehe, I do not "remember" (as I only saw some hints in emails) as this was never discussed in either the Formulation, Attestations or ML work groups I attended ;) and really have no idea what that means in terms of invalidating the use of externalReference.

Also, it appears from your link to the XSD that it is an addition (i.e., "union") which now includes a new explicit type... which is fine the way I read it (guessing from the XSD terminology). That is, it is just a new way to use externalReference to link to another resource's BOM which is fine.

jkowalleck · 2023-06-19T13:27:19Z

@mrutkows

Unfortunately, there was no hint in the docs, how a BOM-link could be detected or where it was allowed to be used.
Just some pamphlet and texts existed, some questions, discussions and issues in GitHub mentioned details.
Rules of thump from @stevespringett was: every URI could be a BOM-Link, if it had the expected format, every value of "ref" could be a BOM-Link if it had the expected format .

I do not "remember" (as I only saw some hints in emails) as this was never discussed in either the Formulation, Attestations or ML work groups I attended ;) and really have no idea what that means in terms of invalidating the use of externalReference.

changes were purely documentations, no need for any working group, as @stevespringett told me. Strings are still strings, URIs are still URIs.

externalReference is still valid and unchanged; externalReference.url is still an iri-reference/anyURI.
the only thing is that via BOM-link it was agreed that a URI(iri-reference/anyURI) in the format urn:cdx:<document-id>/<document-version>[#<bom-ref-value>] had a special meaning.
read https://cyclonedx.org/capabilities/bomlink/

To improve the situation, a new type for BOM-Link was introduced in the schema, which is just another iri-reference/anyURI with some documentation and a regex constraint.
All existing iri-reference/anyURI were reviewed and some were extended, so that they could be either the general URI(just like before), or be a special URI in the format of a BOM-Link.
Since old type and new type are just the same, nothing actually changed in the matter of data formats, but it now is clear from the schema, where a BOM-link could be used, and which kind of BOM-Link was acceptable.

That is, it is just a new way to use externalReference to link to another resource's BOM which is fine.

exactly. No format changes, just documentation and helpers for machine readability.
previously we had things being arbitrary string, now they are arbitrary string or another special-format of string.
previously we had things being arbitrary URI, now they are an arbitrary URI or another special-format of URI.

Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com>

jkowalleck · 2023-06-19T13:47:31Z

@mrutkows could you review the PR again, and mark it as approved/rejected ?

changes since your previous comment:

resourceReferenceChoice.ref could also be a BOM-Link, not only any string
(implications: no change. type was a string already, now it is either an arbitrary string or a special formatted string)

jkowalleck · 2023-06-19T13:52:37Z

schema/bom-1.5.schema.json

@@ -3645,7 +3645,10 @@
        "ref": {
          "title": "BOM Reference",
          "description": "References an object by its bom-ref attribute",
-          "$ref": "#/definitions/refType"


was any string

jkowalleck · 2023-06-19T13:52:48Z

schema/bom-1.5.schema.json

@@ -3645,7 +3645,10 @@
        "ref": {
          "title": "BOM Reference",
          "description": "References an object by its bom-ref attribute",
-          "$ref": "#/definitions/refType"
+          "anyOf": [
+            {"$ref": "#/definitions/refLinkType"},


is any string

jkowalleck · 2023-06-19T13:53:10Z

schema/bom-1.5.schema.json

-          "$ref": "#/definitions/refType"
+          "anyOf": [
+            {"$ref": "#/definitions/refLinkType"},
+            {"$ref": "#/definitions/bomLinkElementType"}


is any string with iri-reference format and a certain regex/format/pattern for BOM-Link

jkowalleck · 2023-06-19T13:53:24Z

schema/bom-1.5.xsd

@@ -4356,12 +4356,15 @@ limitations under the License.
    <xs:complexType name="resourceReferenceType">
        <xs:sequence>
            <xs:choice>
-                <xs:element name="ref" type="bom:refType" minOccurs="1" maxOccurs="1">


was any string

jkowalleck · 2023-06-19T13:54:01Z

schema/bom-1.5.xsd

                    <xs:annotation>
                        <xs:documentation>
                            References an object by its bom-ref attribute
                        </xs:documentation>
                    </xs:annotation>
+                    <xs:simpleType>
+                        <xs:union memberTypes="bom:refLinkType bom:bomLinkElementType"/>


is any of:

bom:refLinkType: any string

bom:bomLinkElementType: anyURI string with a certain pattern/format for BOM-Link

mrutkows · 2023-06-20T16:10:52Z

@jkowalleck Thanks for educating me on these new definitions. It appears the important part, relative to workflow, is whereever we reference the resourceReferenceChoice type which is more expansive to include the latest (2) ways to link to a traditional "bom-ref" (i.e., refLinkType and bomLinkElementType ) and now has this definition:

  "properties": {
    "ref": {
      "title": "BOM Reference",
      "description": "References an object by its bom-ref attribute",
      "anyOf": [
        {"$ref": "#/definitions/refLinkType"},
        {"$ref": "#/definitions/bomLinkElementType"}
      ]
    },
    "externalReference": {
      "title": "External reference",
      "description": "Reference to an externally accessible resource.",
      "$ref": "#/definitions/externalReference"
    }
  },

It looks quite good and understand the rationale (sorry I was not aware before now). I approve this change, but please know I will not have time to "test" this change anytime soon. Looking purely at the schema, it should work for the original "bom-ref" case (as part of the "choice"). Thanks again.

mrutkows

Please see my summary comments above.

stevespringett · 2023-06-22T03:40:21Z

LGTM @jkowalleck. If it's passing the tests, please merge this in.

v1.5 clarify resourceReferenceChoice.ref`

866794e

Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com>

jkowalleck added this to the 1.5 milestone Jun 17, 2023

jkowalleck requested review from mrutkows and a team June 17, 2023 17:49

jkowalleck changed the base branch from master to v1.5-dev June 17, 2023 17:50

jkowalleck marked this pull request as draft June 17, 2023 17:51

jkowalleck changed the title ~~V1.5 dev resourceReferenceChoice ref clarifications~~ [WIP] V1.5 dev resourceReferenceChoice ref clarifications Jun 17, 2023

jkowalleck changed the title ~~[WIP] V1.5 dev resourceReferenceChoice ref clarifications~~ V1.5 dev resourceReferenceChoice ref clarifications Jun 19, 2023

jkowalleck marked this pull request as ready for review June 19, 2023 12:59

jkowalleck marked this pull request as draft June 19, 2023 13:00

explicitrly allow bomLinkElementType

864d4f4

Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com>

jkowalleck marked this pull request as ready for review June 19, 2023 13:38

jkowalleck commented Jun 19, 2023

View reviewed changes

mrutkows approved these changes Jun 20, 2023

View reviewed changes

stevespringett approved these changes Jun 22, 2023

View reviewed changes

stevespringett merged commit 2003555 into CycloneDX:v1.5-dev Jun 22, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

V1.5 dev resourceReferenceChoice ref clarifications #251

V1.5 dev resourceReferenceChoice ref clarifications #251

jkowalleck commented Jun 17, 2023 •

edited

Loading

jkowalleck commented Jun 17, 2023

mrutkows commented Jun 19, 2023 •

edited

Loading

jkowalleck commented Jun 19, 2023

jkowalleck commented Jun 19, 2023

mrutkows commented Jun 19, 2023 •

edited

Loading

jkowalleck commented Jun 19, 2023 •

edited

Loading

jkowalleck commented Jun 19, 2023 •

edited

Loading

jkowalleck Jun 19, 2023

jkowalleck Jun 19, 2023

jkowalleck Jun 19, 2023

jkowalleck Jun 19, 2023

jkowalleck Jun 19, 2023

mrutkows commented Jun 20, 2023

mrutkows left a comment •

edited

Loading

stevespringett commented Jun 22, 2023

V1.5 dev resourceReferenceChoice ref clarifications #251

V1.5 dev resourceReferenceChoice ref clarifications #251

Conversation

jkowalleck commented Jun 17, 2023 • edited Loading

jkowalleck commented Jun 17, 2023

mrutkows commented Jun 19, 2023 • edited Loading

jkowalleck commented Jun 19, 2023

jkowalleck commented Jun 19, 2023

mrutkows commented Jun 19, 2023 • edited Loading

jkowalleck commented Jun 19, 2023 • edited Loading

jkowalleck commented Jun 19, 2023 • edited Loading

jkowalleck Jun 19, 2023

Choose a reason for hiding this comment

jkowalleck Jun 19, 2023

Choose a reason for hiding this comment

jkowalleck Jun 19, 2023

Choose a reason for hiding this comment

jkowalleck Jun 19, 2023

Choose a reason for hiding this comment

jkowalleck Jun 19, 2023

Choose a reason for hiding this comment

mrutkows commented Jun 20, 2023

mrutkows left a comment • edited Loading

Choose a reason for hiding this comment

stevespringett commented Jun 22, 2023

jkowalleck commented Jun 17, 2023 •

edited

Loading

mrutkows commented Jun 19, 2023 •

edited

Loading

mrutkows commented Jun 19, 2023 •

edited

Loading

jkowalleck commented Jun 19, 2023 •

edited

Loading

jkowalleck commented Jun 19, 2023 •

edited

Loading

mrutkows left a comment •

edited

Loading