Add <obsoletedBy> to licenses and exceptions #392
Conversation
|
I like the concept - it would convey important information. I do have a couple of implementation concerns. If we propogate this out to the JSON and RDF representations of the licenses, it would break current implementations which look for the deprecated flag. There may also be cases in the future where we deprecate licenses without a replacement. I would propose that we make this an optional attribute of licenses and exceptions and retain the notes and deprecated fields. |
|
On Tue, May 30, 2017 at 11:00:48AM -0700, goneall wrote:
There may also be cases in the future where we deprecate licenses
without a replacement. I would propose that we make this an
optional attribute of licenses and exceptions and retain the notes
and deprecated fields.
‘notes’ is so generic. If we want to encourage notes about
deprecation-without-replacement, I'd recommend an ‘obsolete’ tag with
human-oriented content that explained why SPDX decided to drop the
license/exception in question.
Then when we build JSON / RDF / whatever from the XML, you can set a
‘deprecated’ boolean when either ‘obsoleted-by’ or ‘obsolete’ are set,
populate ‘notes’ appropriately, or whatever else we need to do for
backwards compat. But I'd rather avoid repetition and unstructured
data in the canonical source where we can find DRY, structured way to
represent the information we're trying to pass along.
|
|
@wking agree with comment on notes being generic. Disagree that isDeprecated is duplicated. You can have a deprecated license without it being obsoleted by another license. obsoleted-by is just providing additional useful data. |
|
On Tue, May 30, 2017 at 09:50:42PM -0700, goneall wrote:
Disagree that isDeprecated is duplicated. You can have a deprecated
license without it being obsoleted by another license. obsoleted-by
is just providing additional useful data.
But you can't have obsoleted-by *without* having deprecated. Not
having a deprecated attribute means you don't have to worry about
validating the “obsoleted-by set but deprecated not set” case. If in
the future we add other ways for deprecating a license/exception
(e.g. by removing it from the SPDX list without a replacement License
Expression), we can add a new tag to cover that case (e.g. obsolete
[1]). So rather than requiring folks to set deprecated *and* some
more granular field, they'd just set the more granular field. And
then when any of the granular fields were set you'd also set
deprecated in the compiled JSON.
[1]: #392 (comment)
|
|
In thinking about this a bit more, I wonder if we should take a different approach. obsoleted-by would be used to reference a preferred method of expressing the deprecated license. Could we generalize this to a field to express an alternative license expression? This has been proposed in past threads on the legal email list. Something like "preferredAlternative" or "preferredExpression". Then we would continue to use the deprecated flag to indicate a license has been deprecated and the alternative expression could be used with our without the deprecated licenses. |
|
On Wed, May 31, 2017 at 10:11:09AM -0700, goneall wrote:
Could we generalize this to a field to express an alternative
license expression? This has been proposed in past threads on the
legal email list.
Can you link to that discussion? I'm having trouble imagining a
situation where we have a different preferred License Expression but
do not deprecate the short identifier.
|
|
I wasn't able to locate a link to the discussion (it was a while back). I believe it was related to licenses which were a concatonation of other licenses. We may have a similar scenario once we resolve the GPL-2.0+/GPL-2.0-only discussion. My primary concern with removing the deprecated flag is that the semantics are clear and the information is very useful. For example, I filter out all deprecated licenses when I show a selection of license choices. In this scenario I don't need to refer to the obsoleted by expression. |
|
On Wed, May 31, 2017 at 12:33:07PM -0700, goneall wrote:
I believe it was related to licenses which were a concatonation of
other licenses.
In this case, I'd prefer deprecating the short identifier for the
concatenated license and using obsoleted-by.
We may have a similar scenario once we resolve the
GPL-2.0+/GPL-2.0-only discussion.
As I said in [1], I'd prefer we stuck with GPL-2.0, etc. as the
license short name, since that's the license. The + and -only
suffixes would be License Expression syntax for the license *grants*.
If that distinction holds water, there would never be short names for
+ or -only forms, so no need for special handling in the XML.
My primary concern with removing the deprecated flag is that the
semantics are clear and the information is very useful.
You can define clear semantics when you specify the obsoleted-by tag.
And you can recover the ease-of-use in compiled output without adding
redundant information to the XML source (because every entry that sets
obsoleted-by will be deprecated).
For example, I filter out all deprecated licenses when I show a
selection of license choices. In this scenario I don't need to
refer to the obsoleted by expression.
But you can check the obsoleted-by presence. I'd rather not make
consumer-convenience a criterion for the source format.
Consumer-convenience is important, but you can add it during
compilation. Your license-choice widget would be just as easy to
write when it used compiled output that included a deprecated boolean,
regardless of whether that boolean came from an explicit deprecated
attribute or from the presence of obsoleted-by in the source XML.
[1]: https://lists.spdx.org/pipermail/spdx-tech/2017-May/003355.html
|
The XSD suggests (buggily) that we only want a single <notes> element (more details on this in the previous commit). And the information contained in the <notes> sections I'm removing is redundant, because: * Licenses with a release date in their <notes> entry had that same release date in the license title. I don't see a need to include that release date as unstrucutured information in two places, and the license title is clearly the more important location. * Whether the license is only or or-later is covered explicitly in the long name and implicitly in the new deprecation notice (e.g. as added in 55b6fc4, Update comments to reflect the new GPL license ID's, 2017-12-23, spdx#552). Once we get explicit obsoleted-by markup [1], those deprecation notices will become machine readable. So I don't think we need to call out the versioning again in the notes. [1]: spdx#392
The XSD suggests (buggily) that we only want a single <notes> element (more details on this in the previous commit). And the information contained in the <notes> sections I'm removing is redundant, because: * Licenses with a release date in their <notes> entry had that same release date in the license title. I don't see a need to include that release date as unstrucutured information in two places, and the license title is clearly the more important location. * Whether the license is only or or-later is covered explicitly in the long name and implicitly in the new deprecation notice (e.g. as added in 55b6fc4, Update comments to reflect the new GPL license ID's, 2017-12-23, spdx#552). Once we get explicit obsoleted-by markup [1], those deprecation notices will become machine readable. So I don't think we need to call out the versioning again in the notes. [1]: spdx#392
|
I've just filed #583, which drops <obsoleted-by deprecatedVersion="3.0">AGPL-3.0-only</obsoleted-by>where |
The XSD suggests (buggily) that we only want a single <notes> element (more details on this in the previous commit). And the information contained in the <notes> sections I'm removing is redundant, because: * Licenses with a release date in their <notes> entry had that same release date in the license title. I don't see a need to include that release date as unstrucutured information in two places, and the license title is clearly the more important location. * Whether the license is only or or-later is covered explicitly in the long name and implicitly in the new deprecation notice (e.g. as added in 55b6fc4, Update comments to reflect the new GPL license ID's, 2017-12-23, spdx#552). Once we get explicit obsoleted-by markup [1], those deprecation notices will become machine readable. So I don't think we need to call out the versioning again in the notes. [1]: spdx#392
|
This is currently milestoned “later release”. If the holdup is concern over dropping |
I think this is a good approach. If we separate out the issue on deprecated, we can probably close on the addition of the Since this is a broader change, we should get comments/feedback on the legal and tech mailing lists before closing. At some point, this should be documented in the spec (e.g. in a SPDX specification appendix, but that can be a separate effort. @wking Do you want to update the title of this issue to reflect this change? |
|
Suggest changing the element name to Note - we have tried to have the same element names as the license RDFa and license list JSON representations which led to this particular convention. |
wking
changed the title
From [1]:
As a result, a number of licenses formerly included in the SPDX
License List have been deprecated as licenses, and correct usage
employs the License Expression Syntax as of v2.0.
So the sole reason for the deprecations seems to be "there's a better
way to say that now".
Telling people "use an expression instead" is less useful than saying
"use this expression instead: $SOME_EXPRESSION". This commit updates
the schema to allow us to recommend replacements. Consumers can use
logic like:
1. Parse a license expression to extract the short identifiers.
2. Look up obsoletedBy entries for the short identifiers.
3. If any obsoletedBy has an 'expression' attribute that matches the
source, the value of that obsoletedBy is the recommended
replacement for that expression. Otherwise, the value of the
obsoletedBy without an expression attribute is the recommended
replacement for the short identifier.
For example, the expression:
GPL-2.0+ WITH GCC-exception-2.0
could be parsed to either of the following short license identifiers:
* GPL-2.0+, in which case there would be a single obsoletedBy with no
expression attribute:
<obsoletedBy>GPL-2.0-or-later</obsoletedBy>
So the recommended replacement for GPL-2.0+ would be
GPL-2.0-or-later.
* GPL-2.0, in which case there would be two obsoletedBy values:
<obsoletedBy>GPL-2.0-only</obsoletedBy>
<obsoletedBy expression="GPL-2.0+">GPL-2.0-or-later</obsoletedBy>
The one with an 'expression' attribute set to 'GPL-2.0+' matches the
source, so the recommended replacement for GPL-2.0+ is
GPL-2.0-or-later.
The presence of an obsoletedBy element is sufficient to mark a
license/expression obsolete (as is the presence of an
deprecatedVersion attribute), so I'm in favor of dropping isDeprecated
to stay DRY. However, removing isDeprecated (from this repository, we
would still supply it in license-list-data) has proven contentious for
reasons I don't understand. This commit punts on the removal for now
[2].
[1]: spdx#392 (comment)
[2]: spdx#392 (comment)
From [1]:
As a result, a number of licenses formerly included in the SPDX
License List have been deprecated as licenses, and correct usage
employs the License Expression Syntax as of v2.0.
So the sole reason for the deprecations seems to be "there's a better
way to say that now".
Telling people "use an expression instead" is less useful than saying
"use this expression instead: $SOME_EXPRESSION". This commit updates
the schema to allow us to recommend replacements. Consumers can use
logic like:
1. Parse a license expression to extract the short identifiers.
2. Look up obsoletedBy entries for the short identifiers.
3. If any obsoletedBy has an 'expression' attribute that matches the
source, the value of that obsoletedBy is the recommended
replacement for that expression. Otherwise, the value of the
obsoletedBy without an expression attribute is the recommended
replacement for the short identifier.
For example, the expression:
GPL-2.0+ WITH GCC-exception-2.0
could be parsed to either of the following short license identifiers:
* GPL-2.0+, in which case there would be a single obsoletedBy with no
expression attribute:
<obsoletedBy>GPL-2.0-or-later</obsoletedBy>
So the recommended replacement for GPL-2.0+ would be
GPL-2.0-or-later.
* GPL-2.0, in which case there would be two obsoletedBy values:
<obsoletedBy>GPL-2.0-only</obsoletedBy>
<obsoletedBy expression="GPL-2.0+">GPL-2.0-or-later</obsoletedBy>
The one with an 'expression' attribute set to 'GPL-2.0+' matches the
source, so the recommended replacement for GPL-2.0+ is
GPL-2.0-or-later.
The presence of an obsoletedBy element is sufficient to mark a
license/expression obsolete (as is the presence of an
deprecatedVersion attribute), so I'm in favor of dropping isDeprecated
to stay DRY. However, removing isDeprecated (from this repository, we
would still supply it in license-list-data) has proven contentious for
reasons I don't understand. This commit punts on the removal for now
[2].
[1]: spdx#392 (comment)
[2]: spdx#392 (comment)
|
I've pushed 7b56ba9 → a7bef17, which:
|
wking
force-pushed
the
obsoleted-by
branch
2 times, most recently
from
a7bef17 to
390fc63
Compare
From [1]:
As a result, a number of licenses formerly included in the SPDX
License List have been deprecated as licenses, and correct usage
employs the License Expression Syntax as of v2.0.
So the sole reason for the deprecations seems to be "there's a better
way to say that now".
Telling people "use an expression instead" is less useful than saying
"use this expression instead: $SOME_EXPRESSION". This commit updates
the schema to allow us to recommend replacements. Consumers can use
logic like:
1. Parse a license expression to extract the short identifiers.
2. Look up obsoletedBy entries for the short identifiers.
3. If any obsoletedBy has an 'expression' attribute that matches the
source, the value of that obsoletedBy is the recommended
replacement for that expression. Otherwise, the value of the
obsoletedBy without an expression attribute is the recommended
replacement for the short identifier.
For example, the expression:
GPL-2.0+ WITH GCC-exception-2.0
could be parsed to either of the following short license identifiers:
* GPL-2.0+, in which case there would be a single obsoletedBy with no
expression attribute:
<obsoletedBy>GPL-2.0-or-later</obsoletedBy>
So the recommended replacement for GPL-2.0+ would be
GPL-2.0-or-later.
* GPL-2.0, in which case there would be two obsoletedBy values:
<obsoletedBy>GPL-2.0-only</obsoletedBy>
<obsoletedBy expression="GPL-2.0+">GPL-2.0-or-later</obsoletedBy>
The one with an 'expression' attribute set to 'GPL-2.0+' matches the
source, so the recommended replacement for GPL-2.0+ is
GPL-2.0-or-later.
The presence of an obsoletedBy element is sufficient to mark a
license/expression obsolete (as is the presence of an
deprecatedVersion attribute), so I'm in favor of dropping isDeprecated
to stay DRY. However, removing isDeprecated (from this repository, we
would still supply it in license-list-data) has proven contentious for
reasons I don't understand. This commit punts on the removal for now
[2].
[1]: spdx#392 (comment)
[2]: spdx#392 (comment)
src/GFDL-1.1.xml
Outdated
| @@ -3,13 +3,11 @@ | |||
| <license licenseId="GFDL-1.1" isOsiApproved="false" | |||
| name="GNU Free Documentation License v1.1" | |||
| isDeprecated="true" deprecatedVersion="3.0"> | |||
| <obsoletedBy>GFDL-1.1-only</obsoletedBy> | |||
| <obsoletedBy expression="GFDL-1.1+">GFDL-1.1-or-later</obsoletedBy> | |||
There was a problem hiding this comment.
The or-later-ness of this identifier is not clear to me, because (as of list 3.0) the grant for GFDL-1.1 includes “or any later version”. Because there is no ONLY operator, I'm guessing that GFDL-1.1 means GFDL-1.1-only and that you'd need GFDL-1.1+ (pre-3.0) to mean GFDL-1.1-or-later, despite the wording we claimed in <standardLicenseHeader>. But we may want to update the standard license header and/or file an erratum (#598) for clarity going forward.
This issue also affects version 1.2 and 1.3 of the GFDL.
From [1]:
As a result, a number of licenses formerly included in the SPDX
License List have been deprecated as licenses, and correct usage
employs the License Expression Syntax as of v2.0.
So the sole reason for the deprecations seems to be "there's a better
way to say that now".
Telling people "use an expression instead" is less useful than saying
"use this expression instead: $SOME_EXPRESSION". This commit updates
the schema to allow us to recommend replacements. Consumers can use
logic like:
1. Parse a license expression to extract the short identifiers.
2. Look up obsoletedBy entries for the short identifiers.
3. If any obsoletedBy has an 'expression' attribute that matches the
source, the value of that obsoletedBy is the recommended
replacement for that expression. Otherwise, the value of the
obsoletedBy without an expression attribute is the recommended
replacement for the short identifier.
For example, the expression:
GPL-2.0+ WITH GCC-exception-2.0
could be parsed to either of the following short license identifiers:
* GPL-2.0+, in which case there would be a single obsoletedBy with no
expression attribute:
<obsoletedBy>GPL-2.0-or-later</obsoletedBy>
So the recommended replacement for GPL-2.0+ would be
GPL-2.0-or-later.
* GPL-2.0, in which case there would be two obsoletedBy values:
<obsoletedBy>GPL-2.0-only</obsoletedBy>
<obsoletedBy expression="GPL-2.0+">GPL-2.0-or-later</obsoletedBy>
The one with an 'expression' attribute set to 'GPL-2.0+' matches the
source, so the recommended replacement for GPL-2.0+ is
GPL-2.0-or-later.
The presence of an obsoletedBy element is sufficient to mark a
license/expression obsolete (as is the presence of an
deprecatedVersion attribute), so I'm in favor of dropping isDeprecated
to stay DRY. However, removing isDeprecated (from this repository, we
would still supply it in license-list-data) has proven contentious for
reasons I don't understand. This commit punts on the removal for now
[2].
[1]: spdx#392 (comment)
[2]: spdx#392 (comment)
From [1]: As a result, a number of licenses formerly included in the SPDX License List have been deprecated as licenses, and correct usage employs the License Expression Syntax as of v2.0. So the sole reason for the deprecations seems to be "there's a better way to say that now". Telling people "use an expression instead" is less useful than saying "use this expression instead: $SOME_EXPRESSION". This commit updates the schema to allow us to recommend replacements. The recommended consumer algorithm is documented in the schema annotation. The maxOccurs="unbounded" value shows up in an XSD 1.1 spec example [2], and both minOccurs and maxOccurs must be set explicitly for obsoletedBy to override the defaults (1 for both attributes [3]). The presence of an obsoletedBy element is sufficient to mark a license/expression obsolete (as is the presence of an deprecatedVersion attribute), so I'm in favor of dropping isDeprecated to stay DRY. However, removing isDeprecated (from this repository, we would still supply it in license-list-data) has proven contentious for reasons I don't understand. This commit punts on the removal for now [4]. [1]: spdx#392 (comment) [2]: https://www.w3.org/TR/xmlschema11-1/#all-mg [3]: https://www.w3.org/TR/xmlschema11-1/#declare-element [4]: spdx#392 (comment)
|
Rebased around #586 and #599 with 390fc63 → 9ba7946. The Node tests are currently choking with: which is mentioned in albanm/node-libxml-xsd#12. But |
|
Maybe we need a wrapper to attach a |
|
Ah, despite |
|
@goneall, thoughts about <obsoletedBy>
<alternative>…</alternative>
<alternative>…</alternative>
</obsoletedBy> |
I kind of like the structure of the wrapper. This could allow us to add more meaning to the nested element names. For example, we could have |
|
On Fri, Mar 23, 2018 at 09:27:27PM +0000, goneall wrote:
For example, we could have
```<alternativeExpression>...</alternativeExpression>``` for a
license expression and ```<alternativeId>...</alternativeId>``` for
alternative license ID's.
I don't think we need that, because you can distinguish IDs from
expressions by looking for an internal space. But I'll add the
wrapper to work around the XSD issues, and get this moving forward
again.
|
From [1]: As a result, a number of licenses formerly included in the SPDX License List have been deprecated as licenses, and correct usage employs the License Expression Syntax as of v2.0. So the sole reason for the deprecations seems to be "there's a better way to say that now". Telling people "use an expression instead" is less useful than saying "use this expression instead: $SOME_EXPRESSION". This commit updates the schema to allow us to recommend replacements. The recommended consumer algorithm is documented in the schema annotation. The maxOccurs="unbounded" value shows up in an XSD 1.1 spec example [2], and both minOccurs and maxOccurs must be set explicitly for obsoletedBy to override the defaults (1 for both attributes [3]). The presence of an obsoletedBy element is sufficient to mark a license/expression obsolete (as is the presence of an deprecatedVersion attribute), so I'm in favor of dropping isDeprecated to stay DRY. However, removing isDeprecated (from this repository, we would still supply it in license-list-data) has proven contentious for reasons I don't understand. This commit punts on the removal for now [4]. [1]: spdx#392 (comment) [2]: https://www.w3.org/TR/xmlschema11-1/#all-mg [3]: https://www.w3.org/TR/xmlschema11-1/#declare-element [4]: spdx#392 (comment)
Taking advantage of the schema change from the previous commit.
|
@goneall, Travis is happy here :). Want to take a final look when you get time? |
Done. |
The Node tests were choking with:
Entity: line 65: element element: Schemas parser error : Element
'{http://www.w3.org/2001/XMLSchema}element': Invalid value for
maxOccurs (must be 0 or 1).
which is mentioned in [1]. Despite unbounded being in the 1.0 spec,
maxOccurs was restricted to 1 inside <all> in XSD 1.0. The
restriction was lifted in 1.1 [2]. The backing libxml issue is [3].
This commit works around the limitation by adding a wrapping
<obsoletedBys> to mirror our existing <crossRefs> wrapping
<crossRef>. In both cases, the wrapper adds no useful semantics, but
we need it to get the tests passing until we can find an XSD 1.1
validator.
[1]: albanm/node-libxml-xsd#12
[2]: https://www.w3.org/TR/xmlschema11-1/#ch_models
[3]: https://bugzilla.gnome.org/show_bug.cgi?id=765936
From here (whose source I could not find):
So the sole reason for the deprecations seems to be “there's a better way to say that now”.
Telling people “use an expression instead” is less useful than saying “use this expression instead:
$SOME_EXPRESSION”. This commit updates the eCos license (the only deprecated license currently in this repository) to do that, using theWITHexception syntax and the eCos exception label defined in SPDX 2.1 (and possibly in earlier versions).This is related to spdx/tools#73, although discussion there seemed to be doubling down on a deprecated boolean.