Respec: WebIDL and data-dfn-for creates fragments with whitespace
Important info
- URL to affected spec: Based on https://json-ld.org/spec/latest/json-ld-api/. Minimal excerpt included here
- ReSpec version: 20.10.1
- Whittled down to minimal reproducible example
Description of problem
Anchors and references are generated with either %20 or space ().
Given the following document:
<!DOCTYPE html>
<html lang="en">
<head>
<title>DFN Whitespace Test</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
<script type="text/javascript" src="https://www.w3.org/Tools/respec/respec-w3c-common" class="remove"></script>
<script type="text/javascript" class="remove">
//<![CDATA[
var respecConfig = {
// specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
specStatus: "CG-DRAFT",
// if you wish the publication date to be other than today, set this
//publishDate: "2013-11-05",
copyrightStart: "2010",
// the specification's short name, as in http://www.w3.org/TR/short-name/
shortName: "dfn-whitespace-test",
edDraftURI: "https://example.com/",
// if you want to have extra CSS, append them to this list
// it is recommended that the respec.css stylesheet be kept
// extraCSS: [],
includePermalinks: true,
noRecTrack: true,
// editors, add as many as you like
// only "name" is required
editors: [{ name: "Gregg Kellogg"}],
// name of the WG
wg: "JSON for Linking Data W3C Community Group",
// URI of the public WG page
wgURI: "https://www.w3.org/community/json-ld/",
// name (with the @w3c.org) of the public mailing to which comments are due
wgPublicList: "public-linked-json",
// URI of the patent status for this WG, for Rec-track documents
// !!!! IMPORTANT !!!!
// This is important for Rec-track documents, do not copy a patent URI from a random
// document unless you know what you're doing. If in doubt ask your friendly neighbourhood
// Team Contact.
//wgPatentURI: "https://www.w3.org/2004/01/pp-impl/46168/status",
maxTocLevel: 2
///alternateFormats: [ {uri: "diff-20140116.html", label: "diff to previous version"} ]
};
//]]>
</script>
</head>
<body>
<section id="abstract"><p></p></section>
<section id="sotd"><p></p></section>
<section>
<h1>Reference</h1>
<p>Reference <a data-link-for="JsonLdErrorCode">colliding keywords</a>.</p>
</section> <!-- end of Expansion section -->
<section>
<h2>The Application Programming Interface</h2>
<section>
<h3>Error Handling</h3>
<section>
<h4>JsonLdErrorCode</h4>
<p>The <dfn>JsonLdErrorCode</dfn> represents the collection of valid JSON-LD error
codes.</p>
<pre class="idl">
enum JsonLdErrorCode {"colliding keywords"};
</pre>
<dl data-dfn-for="JsonLdErrorCode" data-sort>
<dt><dfn>colliding keywords</dfn></dt>
<dd>Two properties which expand to the same keyword have been detected.</dd>
</dl>
</section>
</section> <!-- end of Error Handling -->
</section> <!-- end of The Application Programming Interfaces -->
</body>
</html>
Note that the definition of _colliding keywords_ includes a whitespace in the anchor: dom-jsonlderrorcode-colliding keywords. References are either the same, or have the whitespace replaced with %20.
gkellogg
All 10 comments
Although indeed a bug, convention is to use a “-“ instead of spaces in enums. See:
https://w3ctag.github.io/design-principles/#casing-rules
Would that help?
marcoscaceres
on 3 May 2018
It may be now, but not when these error codes were originally created. In any case, it's in JSON-LD 1.0 and probably can't be changed for 1.1. ReSpec formerly generated reasonable fragment identifiers for these.
gkellogg
on 3 May 2018
Understood, but it’s also an indicator that something might not be right with the API. For example, the JsonLdErrorCode emun is trying to use enum values for error messages? That’s definitely not ok.
marcoscaceres
on 3 May 2018
Perhaps it's not how WebIDL intends it, but this is how jsonld.js uses it:
// context must be an object by now, all URLs retrieved before this call
if(!_isObject(ctx)) {
throw new JsonLdError(
'Invalid JSON-LD syntax; @context must be an object.',
'jsonld.SyntaxError', {code: 'invalid local context', context: ctx});
}
Other languages typically interpret this using their own semantics; in Ruby, each error has its own class, and the error code is in a class method:
# 3.3) If context is not a JSON object, an invalid local context error has been detected and processing is aborted.
raise JsonLdError::InvalidLocalContext, "must be a URL, JSON object or array of same: #{context.inspect}"
cc/ @dlongley
gkellogg
on 3 May 2018
@gkellogg, understood (hi @dlongley! :D). Let's treat this as a regression in ReSpec, which it definitely is. We can discuss API issues over on the JSON-LD Repo.
@sidvishnoi, this is a good one if you want to get your feet wet with the IDL code. You want to take it? I can point you to where the bug is likely happening.
marcoscaceres
on 3 May 2018
Ping, this seems to have gotten lost, and now causes problems to be noted when rendering, for example, https://w3c.github.io/json-ld-api. I did try to resurrect my ReSpec development environment to dive into the code, but got hung up with npm install errors I can't resolve.
gkellogg
on 4 Jul 2018
Let me know what errors you get with npm install. Will try to take a look later in the week. Taking tomorrow off because 4th of July.
marcoscaceres
on 4 Jul 2018
@gkellogg sent a PR:
https://github.com/w3c/respec/issues/1650
But it only deals with spaces... can you confirm that "@" and other symbols are ok?
marcoscaceres
on 5 Jul 2018
@marcoscaceres this would seem to an improvement, but URI path components are quite prescriptive, but for validation, this likely depends on if you validate as a URI/IRI or as a URL. The URL spec allows characters such as @, while URI is restricted to ALPHA / DIGIT / "-" / "." / "_" / "~", for the most part. For a Spec, the URL text would seem to be adequate.
gkellogg
on 8 Jul 2018
Fwiw, we use URLs.
marcoscaceres
on 9 Jul 2018
Related issues
marcoscaceres
·
4Comments
marcoscaceres
·
3Comments
marcoscaceres
·
6Comments
saschanaz
·
3Comments
deniak
·
5Comments
Most helpful comment
@gkellogg, understood (hi @dlongley! :D). Let's treat this as a regression in ReSpec, which it definitely is. We can discuss API issues over on the JSON-LD Repo.
@sidvishnoi, this is a good one if you want to get your feet wet with the IDL code. You want to take it? I can point you to where the bug is likely happening.