schema/ListedLicense: Document our XML semantics #586
Conversation
wking
force-pushed
the
xml-semantics
branch
2 times, most recently
from
be1af7e to
86fe5d8
Compare
wking
changed the title
There was a problem hiding this comment.
Excellent descriptions for the individual crossRefs and copyright elements. Overall, this helps add a lot of clarification to the users of the license XML format.
There are a couple change requests inline, most are legal related.
One other general recommendation would be to reference the license matching guidelines that the schema is based on somewhere in the schema annotation.
schema/ListedLicense.xsd
Outdated
| <annotation> | ||
| <documentation xml:lang="en"> | ||
| <xhtml:p> | ||
| <xhtml:code>standardLicenseHeader</xhtml:code> is the license steward's recommended text for per-file license grants. |
There was a problem hiding this comment.
IANAL, but from what I understand the term "grant" has specific legal meaning which may not be applicable to all situations where the license header is used.
Suggest changing "grant" to "notice" or "text".
There was a problem hiding this comment.
… from what I understand the term "grant" has specific legal meaning which may not be applicable to all situations where the license header is used.
What's the distinction between “grant” and “notice”? Maybe “Copyright 2018 me. All rights reserved” would be a notice but not a grant? That's fine, but since all of these are licenses, I expect all of our suggested headers will be license grants (although those license grants may also include copyright notices).
| <annotation> | ||
| <documentation xml:lang="en"> | ||
| <xhtml:p> | ||
| <xhtml:code>crossRefsType</xhtml:code> is a set of URIs for the license or exception. When the license steward has a URI devoted to the license, it must be the first entry in <xhtml:code>crossRefsType</xhtml:code>. The order in which the other child elements are listed is not significant. |
There was a problem hiding this comment.
Is the order of cross references agreed to and consistent? If not, I would just leave it as a set of URI's for the license or exceptions.
schema/ListedLicense.xsd
Outdated
| <annotation> | ||
| <documentation xml:lang="en"> | ||
| <xhtml:p> | ||
| <xhtml:code>altType</xhtml:code> represents alternative content, where the SPDX considers several alternatives legally equivalent. |
There was a problem hiding this comment.
This may be OK, but in practice we have a lot of .+ matches which really could include text not legally equivalent. Should we include something with a little more "wiggle room" in the language? For example - "represents alternative content commonly found in the license text, where the SPDX considers typical usage of the alternative text legally equivalent."
@jlovejoy thoughts?
schema/ListedLicense.xsd
Outdated
| <annotation> | ||
| <documentation xml:lang="en"> | ||
| <xhtml:p> | ||
| <xhtml:code>titleText</xhtml:code> is the title of the license/exception. |
There was a problem hiding this comment.
Do we want to add the titleText is always considered optional per the license matching guidelines?
There was a problem hiding this comment.
Do we want to add the
titleTextis always considered optional per the license matching guidelines?
I don't think we need to call that out, since I'd rather move towards having distinct markup for optionality (<alt> and <optional>) and semantic meaning (e.g. <h1>). It's my understanding that spdx/tools doesn't treat <titleText> as optional at the moment, is that the case?
There was a problem hiding this comment.
I just checked and the tools to convert the title to optional
wking
force-pushed
the
xml-semantics
branch
2 times, most recently
from
7d44198 to
deec602
Compare
Using annotations [1]. The xhtml namespace handling is from [2]. The reworded intro is based on our new README text. The ERE match semantics are from [3]. The rest of the text is mine, and in some cases (e.g. the crossRefs ordering) may be aspirational and not current. [1]: https://www.w3.org/TR/2012/REC-xmlschema11-1-20120405/structures.html#cAnnotations [2]: https://www.w3.org/TR/2012/REC-xmlschema11-1-20120405/structures.html#eg.import.html [3]: https://spdx.org/spdx-specification-21-web-version#h.2mjng0vqrghe
This license is the canonical source of the schema, and the canonical source of the XML which consumes that schema. I'd rather have it be the canonical source of the schema semantics as well, in which case there is no reason to reference external matching guidelines. I'd rather have the external matching guidelines reference this documentation as the canonical source. |
Also update mif-exception, which doesn't seem to have a steward, but which had two URIs packed into a single crossRef element.
Using annotations. The xhtml namespace handling is from here. The reworded intro is based on our new
READMEtext. The ERE match semantics are from here. The rest of the text is mine, and in some cases (e.g. thecrossRefsordering) may be aspirational and not current.I still have a number of types to document, but thought I'd put up the WIP PR so folks could see where I was planning to go.
Fixes #495.