You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: DOCS/xml-fields.md
+26-31Lines changed: 26 additions & 31 deletions
Original file line number
Diff line number
Diff line change
@@ -44,19 +44,16 @@ Within the .xml file, the first and last lines of the file should be the followi
44
44
The main tag used to define the license or exception is, unsurprisingly, **`<license>`** or **`<exception>`**. All of the remaining content will be enclosed within a `<license></license>` or `<exception></exception>` pair of tags.
45
45
46
46
There are two mandatory attributes for every `<license>` and `<exception>` tag:
47
-
48
-
-`licenseId`: the unique SPDX Identifier for the license; should be identical to the filename
49
-
-`name`: the longer "real name" of the license
47
+
*`licenseId`: the unique SPDX Identifier for the license; should be identical to the filename
48
+
*`name`: the longer "real name" of the license
50
49
51
50
There are two additional attributes which are optional, but highly encouraged:
52
-
53
-
-`isOsiApproved` (for licenses, not exceptions): either "true" or "false" based on whether this license has been approved by the [Open Source Initiative](https://opensource.org/licenses/alphabetical)
54
-
-`listVersionAdded`: in which release version of the SPDX License List was the license first added, e.g. "3.19".
55
-
- Typically you'll check the currently-released version at https://spdx.org/licenses/ and increment the minor version by 1 for a new license.
51
+
*`isOsiApproved` (for licenses, not exceptions): either "true" or "false" based on whether this license has been approved by the [Open Source Initiative](https://opensource.org/licenses/alphabetical)
52
+
*`listVersionAdded`: in which release version of the SPDX License List was the license first added, e.g. "3.19".
53
+
* Typically you'll check the currently-released version at https://spdx.org/licenses/ and increment the minor version by 1 for a new license.
56
54
57
55
Finally, if the license ID has been deprecated, one additional attribute should be included:
58
-
59
-
-`deprecatedVersion`: in which release version of the SPDX License List was the license first marked as deprecated, e.g. "3.19"
56
+
*`deprecatedVersion`: in which release version of the SPDX License List was the license first marked as deprecated, e.g. "3.19"
60
57
61
58
Note that the deprecated tags refer to whether the ID has been deprecated _by SPDX_ -- in other words, if the SPDX Legal Team no longer recommends that the identifier should be used. Licenses that have been described as "deprecated" or "superseded" by the _license author_ might no longer be recommended to use for new code, but their identifiers remain valid License IDs on the SPDX License List.
62
59
@@ -66,15 +63,15 @@ Deprecated license identifiers will be listed at the bottom of the SPDX License
66
63
67
64
There are three optional first-level metadata fields that can be nested immediately under `<license>` or `<exception>`, each of which is optional:
68
65
69
-
-**`<crossRefs>`**: Defines cross-references to URLs where the license can be found in use by one or a few projects, and (if applicable) where posted by the license steward
70
-
-**`<notes>`**: Describes general comments about the license; if deprecated, also briefly explain the reason for deprecating the license identifier
71
-
-**`<obsoletedBys>`** (if license is deprecated): Lists the license(s) that should be used instead of this deprecated license
66
+
***`<crossRefs>`**: Defines cross-references to URLs where the license can be found in use by one or a few projects, and (if applicable) where posted by the license steward
67
+
***`<notes>`**: Describes general comments about the license; if deprecated, also briefly explain the reason for deprecating the license identifier
68
+
***`<obsoletedBys>`** (if license is deprecated): Lists the license(s) that should be used instead of this deprecated license
72
69
73
70
### License text
74
71
75
72
Then, the actual license text would be contained within the `<text></text>` section:
76
73
77
-
-**`<text>`**: Defines the actual text and templating for the license
74
+
***`<text>`**: Defines the actual text and templating for the license
78
75
79
76
Example:
80
77
@@ -97,12 +94,12 @@ Example:
97
94
98
95
Some portions of the license text can be surrounded by annotation tags, to denote certain sections of the license text:
99
96
100
-
-**`<titleText>`**: indicates the title of the license, if specified in the license text itself
101
-
-**`<copyrightText>`**: indicates where a copyright notice would be placed for the licensed code
102
-
- Note that `<copyrightText>` should _not_ be used for copyright notices that apply to the copyright in the license text itself!
103
-
-**`<standardLicenseHeader>`**: indicates a standard way that the license recommends specifying the license, e.g. in code comments
104
-
- Note that `<standardLicenseHeader>` should _only_ be used if it is defined by the license text itself!
105
-
- Typically, this would be located in an appendix titled something like "How to apply the license to your work"
97
+
***`<titleText>`**: indicates the title of the license, if specified in the license text itself
98
+
***`<copyrightText>`**: indicates where a copyright notice would be placed for the licensed code
99
+
* Note that `<copyrightText>` should _not_ be used for copyright notices that apply to the copyright in the license text itself!
100
+
***`<standardLicenseHeader>`**: indicates a standard way that the license recommends specifying the license, e.g. in code comments
101
+
* Note that `<standardLicenseHeader>` should _only_ be used if it is defined by the license text itself!
102
+
* Typically, this would be located in an appendix titled something like "How to apply the license to your work"
106
103
107
104
### Paragraphs and newlines
108
105
@@ -118,11 +115,11 @@ Numbered lists (e.g., a series of numbered sections) and unnumbered lists (e.g.,
118
115
119
116
Here are the basic rules:
120
117
121
-
- The list as a whole should be surrounded with **`<list>...</list>`** tags.
122
-
- Within the `<list>`, each item in the list should be surrounded with **`<item>...</item>`** tags.
123
-
- If a list item has a section number or a bullet point at the start, the section number or bullet should be surrounded with **`<bullet>...</bullet>`** tags.
124
-
- Sub-lists can be nested within an item, to indicate e.g. subsections within an overarching numbered section.
125
-
- Items can also contain **`<p>...</p>`** tags, as needed if an item contains multiple paragraphs.
118
+
* The list as a whole should be surrounded with **`<list>...</list>`** tags.
119
+
* Within the `<list>`, each item in the list should be surrounded with **`<item>...</item>`** tags.
120
+
* If a list item has a section number or a bullet point at the start, the section number or bullet should be surrounded with **`<bullet>...</bullet>`** tags.
121
+
* Sub-lists can be nested within an item, to indicate e.g. subsections within an overarching numbered section.
122
+
* Items can also contain **`<p>...</p>`** tags, as needed if an item contains multiple paragraphs.
126
123
127
124
Example:
128
125
@@ -167,17 +164,15 @@ Note that some annotated portions of text (specifically `<titleText>` and `<copy
167
164
Some licenses contain portions of language that can match to a variety of alternative texts. This is called "replaceable text", and is denoted with the **`<alt>...</alt>`** tag.
168
165
169
166
The **<alt>** tag includes two attributes:
170
-
171
-
-`name`: specifies a unique name for this matching element
172
-
-`match`: specifies a [POSIX extended regular expression (ERE)](http://pubs.opengroup.org/onlinepubs/9699919799/) for what text will match
167
+
*`name`: specifies a unique name for this matching element
168
+
*`match`: specifies a [POSIX extended regular expression (ERE)](http://pubs.opengroup.org/onlinepubs/9699919799/) for what text will match
173
169
174
170
Note that an example of actually-matching text should be included between the `<alt>` and `</alt>` tags, as the specified example is what will be rendered on the SPDX License List website page and in license text files provided by SPDX. To the extent a license has a "canonical" or "most commonly used" standard language, use that in the match between the `alt` tags.
175
171
176
172
Learning regular expressions is outside the scope of this document. However, here are a few of the most common patterns, taken from [BSD-3-Clause](../src/BSD-3-Clause.xml) which is a good example of using several `<alt>` tags effectively:
177
-
178
-
-`<alt match="are|is" name="tobe">are</alt>`: Matches if the text is either the word "are" or the word "is"
179
-
-`<alt match="EXPRESS(ED)?" name="express">EXPRESS</alt>`: Matches if the text is either the word "EXPRESS" or the word "EXPRESSED"
180
-
-`<alt match=".+" name="copyrightHolderAsIs">THE COPYRIGHT HOLDERS AND CONTRIBUTORS</alt>`: Matches anything as long as it consists of at least one or more characters
173
+
*`<alt match="are|is" name="tobe">are</alt>`: Matches if the text is either the word "are" or the word "is"
174
+
*`<alt match="EXPRESS(ED)?" name="express">EXPRESS</alt>`: Matches if the text is either the word "EXPRESS" or the word "EXPRESSED"
175
+
*`<alt match=".+" name="copyrightHolderAsIs">THE COPYRIGHT HOLDERS AND CONTRIBUTORS</alt>`: Matches anything as long as it consists of at least one or more characters
0 commit comments