Skip to content

Commit a8d1c65

Browse files
stevespringettstevespringett
authored
refactor: centralize version and version-range (#322)
goal: improve documentation by consolidating elements regarding "version". pure refactoring, no new functionality was added, nor removed, nor changed. - [x] consolidate `version` - [x] consolidate `range` - [x] rename `range` definition to `version-range` - [x] add more examples - [x] review rendered documentation
2 parents 5d8c05b + 92ae29e commit a8d1c65

2 files changed

Lines changed: 72 additions & 17 deletions

File tree

‎schema/bom-1.6.schema.json‎

Lines changed: 30 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -299,7 +299,7 @@
299299
"description": "The name of the tool"
300300
},
301301
"version": {
302-
"type": "string",
302+
"$ref": "#/definitions/version",
303303
"title": "Tool Version",
304304
"description": "The version of the tool"
305305
},
@@ -457,10 +457,9 @@
457457
"examples": ["tomcat-catalina"]
458458
},
459459
"version": {
460-
"type": "string",
460+
"$ref": "#/definitions/version",
461461
"title": "Component Version",
462-
"description": "The component version. The version should ideally comply with semantic versioning but is not enforced.",
463-
"examples": ["9.0.14"]
462+
"description": "The component version. The version should ideally comply with semantic versioning but is not enforced."
464463
},
465464
"description": {
466465
"type": "string",
@@ -1277,10 +1276,9 @@
12771276
"examples": ["ticker-service"]
12781277
},
12791278
"version": {
1280-
"type": "string",
1279+
"$ref": "#/definitions/version",
12811280
"title": "Service Version",
1282-
"description": "The service version.",
1283-
"examples": ["1.0.0"]
1281+
"description": "The service version."
12841282
},
12851283
"description": {
12861284
"type": "string",
@@ -2285,7 +2283,7 @@
22852283
},
22862284
"range": {
22872285
"description": "A version range specified in Package URL Version Range syntax (vers) which is defined at https://github.com/package-url/purl-spec/VERSION-RANGE-SPEC.rst",
2288-
"$ref": "#/definitions/range"
2286+
"$ref": "#/definitions/versionRange"
22892287
},
22902288
"status": {
22912289
"description": "The vulnerability status for the version or range of versions.",
@@ -2320,16 +2318,36 @@
23202318
]
23212319
},
23222320
"version": {
2323-
"description": "A single version of a component or service.",
2321+
"description": "A single disjunctive version identifier, for a component or service.",
23242322
"type": "string",
23252323
"minLength": 1,
2326-
"maxLength": 1024
2324+
"maxLength": 1024,
2325+
"examples": [
2326+
"9.0.14",
2327+
"v1.33.7",
2328+
"7.0.0-M1",
2329+
"2.0pre1",
2330+
"1.0.0-beta1",
2331+
"0.8.15"
2332+
]
23272333
},
2328-
"range": {
2334+
"versionRange": {
23292335
"description": "A version range specified in Package URL Version Range syntax (vers) which is defined at https://github.com/package-url/purl-spec/VERSION-RANGE-SPEC.rst",
23302336
"type": "string",
23312337
"minLength": 1,
2332-
"maxLength": 1024
2338+
"maxLength": 1024,
2339+
"examples": [
2340+
"9.0.14",
2341+
"1.2.3|>=2.0.0|<5.0.0",
2342+
"0.0.0|0.0.1|0.0.2|0.0.3|1.0|2.0pre1",
2343+
">=1.0.0-beta1|<=1.7.5|>=7.0.0-M1|<=7.0.7|>=7.1.0|<=7.1.2|>=8.0.0-M1|<=8.0.1",
2344+
">=2.2.0|!= 2.2.1|<2.3.0"
2345+
]
2346+
},
2347+
"range": {
2348+
"deprecated": true,
2349+
"description": "Deprecated definition. use definition `versionRange` instead.",
2350+
"allOf": [{"$ref": "#/definitions/versionRange"}]
23332351
},
23342352
"annotations": {
23352353
"type": "object",

‎schema/bom-1.6.xsd‎

Lines changed: 42 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,43 @@ limitations under the License.
5454
<xs:restriction base="bom:refType"/>
5555
</xs:simpleType>
5656

57+
<xs:simpleType name="versionType">
58+
<xs:annotation>
59+
<xs:documentation xml:lang="en"><![CDATA[
60+
A single disjunctive version identifier, for a component or service.
61+
62+
Example values:
63+
- "9.0.14"
64+
- "v1.33.7"
65+
- "7.0.0-M1"
66+
- "2.0pre1"
67+
- "1.0.0-beta1"
68+
- "0.8.15"
69+
]]>
70+
</xs:documentation>
71+
</xs:annotation>
72+
<xs:restriction base="xs:normalizedString"/>
73+
</xs:simpleType>
74+
<xs:simpleType name="versionRangeType">
75+
<xs:annotation>
76+
<xs:documentation xml:lang="en"><![CDATA[
77+
A version range specified in Package URL Version Range syntax (vers) which is defined at https://github.com/package-url/purl-spec/VERSION-RANGE-SPEC.rst
78+
79+
Example values:
80+
- "9.0.14"
81+
- "1.2.3|>=2.0.0|<5.0.0"
82+
- "0.0.0|0.0.1|0.0.2|0.0.3|1.0|2.0pre1"
83+
- ">=1.0.0-beta1|<=1.7.5|>=7.0.0-M1|<=7.0.7|>=7.1.0|<=7.1.2|>=8.0.0-M1|<=8.0.1"
84+
- ">=2.2.0|!= 2.2.1|<2.3.0"
85+
]]>
86+
</xs:documentation>
87+
</xs:annotation>
88+
<xs:restriction base="xs:normalizedString">
89+
<xs:minLength value="1"/>
90+
<xs:maxLength value="1024"/>
91+
</xs:restriction>
92+
</xs:simpleType>
93+
5794
<xs:simpleType name="bomLinkDocumentType">
5895
<xs:annotation>
5996
<xs:documentation xml:lang="en">
@@ -338,7 +375,7 @@ limitations under the License.
338375
<xs:documentation>The name of the tool</xs:documentation>
339376
</xs:annotation>
340377
</xs:element>
341-
<xs:element name="version" minOccurs="0" maxOccurs="1" type="xs:normalizedString">
378+
<xs:element name="version" minOccurs="0" maxOccurs="1" type="bom:versionType">
342379
<xs:annotation>
343380
<xs:documentation>The version of the tool</xs:documentation>
344381
</xs:annotation>
@@ -463,7 +500,7 @@ limitations under the License.
463500
of the component. Examples: commons-lang3 and jquery</xs:documentation>
464501
</xs:annotation>
465502
</xs:element>
466-
<xs:element name="version" type="xs:normalizedString" minOccurs="0" maxOccurs="1">
503+
<xs:element name="version" type="bom:versionType" minOccurs="0" maxOccurs="1">
467504
<xs:annotation>
468505
<xs:documentation>The component version. The version should ideally comply with semantic versioning
469506
but is not enforced.</xs:documentation>
@@ -1851,7 +1888,7 @@ limitations under the License.
18511888
of the service.</xs:documentation>
18521889
</xs:annotation>
18531890
</xs:element>
1854-
<xs:element name="version" type="xs:normalizedString" minOccurs="0" maxOccurs="1">
1891+
<xs:element name="version" type="bom:versionType" minOccurs="0" maxOccurs="1">
18551892
<xs:annotation>
18561893
<xs:documentation>The service version.</xs:documentation>
18571894
</xs:annotation>
@@ -3637,12 +3674,12 @@ limitations under the License.
36373674
<xs:complexType>
36383675
<xs:sequence minOccurs="0" maxOccurs="1">
36393676
<xs:choice>
3640-
<xs:element name="version" type="xs:normalizedString" minOccurs="1" maxOccurs="1">
3677+
<xs:element name="version" type="bom:versionType" minOccurs="1" maxOccurs="1">
36413678
<xs:annotation>
36423679
<xs:documentation>A single version of a component or service.</xs:documentation>
36433680
</xs:annotation>
36443681
</xs:element>
3645-
<xs:element name="range" type="xs:normalizedString" minOccurs="1" maxOccurs="1">
3682+
<xs:element name="range" type="bom:versionRangeType" minOccurs="1" maxOccurs="1">
36463683
<xs:annotation>
36473684
<xs:documentation>A version range specified in Package URL Version Range syntax (vers) which is defined at https://github.com/package-url/purl-spec/VERSION-RANGE-SPEC.rst</xs:documentation>
36483685
</xs:annotation>

0 commit comments

Comments
 (0)