Core - XML metadata and directives problems
Issue #943
invalid
This is a collection of comments against the Core Final. (df504c1)
There are multiple problems with the XML metadata and directives.
1. Wrong Encoding
Currently, it states:
<?xml version="1.0" encoding="US-ASCII"?>
Since it has some international characters in it, it should be UTF-8 instead of US-ASCII
Proposes:
<?xml version="1.0" encoding="UTF-8"?>
2. Wrong IPR
Currently, it states:
<rfc category="std" docName="openid-connect-core-1_0" ipr="trust200902">
Obviously, it is wrong. The ipr cannot be trust200902.
Proposes:
<rfc category="std" docName="openid-connect-core-1_0" ipr="oidf">
3. Wrong Classification
Currently, it states:
<?rfc private="Final" ?>
This means that this is a private memo, where the value of the parameter is the title of the memo. This is not what we want. Thus, this directive must be removed.
Proposal: Remove this line.
Comments (2)
-
-
- changed status to invalid
We will leave this as-is
- Log in to comment
On 1: The encoding is correct. I verified that only US-ASCII characters are present in this specification in preparation for publishing the final version and I re-verified it now. The one specification that contains non-ASCII characters is dynamic registration and it does use the UTF-8 encoding.
On 2: ipr="oidf" is not supported by the standard versions of xml2rfc. Forcing editors to use non-standard versions of tools is a non-starter as far as I'm concerned. Maintaining and installing those tools then becomes an unnecessary tax on the working group and the editors and means that special expertise would needed to build a spec, rather than just going to http://xml2rfc.tools.ietf.org/old.html and using the standard version. We should only move off of the standard tools without a compelling reason to do so (which there isn't, because the existing specs are an existence proof that they work fine) and without a working group decision to do so.
It doesn't matter that document source code contains trust200902 because this has no effect on the output as used. It's the output that matters, and the current output is fine.
On 3: Likewise, the ?rfc private directive isn't metadata - it's source code used to produce a particular output - just as ?rfc iprnotified="no" is. Given the output is correct, by definition, there's nothing wrong with the input.
Finally, I'll add that if we were to adopt Nat's suggestion to use his xml2rfc variant, people should be aware that it currently emits two extra sections at the end of the document that are not present in the approved OpenID Connect specifications. This is an unnecessary change that we should not make as part of the errata process. (These two extra sections are "Full Copyright Statement" and "Intellectual Property". One of these duplicates the "Notices" section. The other is new, and, given that it deals with IPR, I believe should be the subject of a board decision before being included in any spec. Issue
#940requests their removal from the Migration spec.)Also see issue
#945for a related discussion on the current use of the non-standard xml2rfc version by the migration spec.