Re: Official response to RDF-ISSUE-163: Determine if @type overloading is acceptable for JSON-LD 1.0

Hi Simon, thanks for the response and taking the time to think deeply
about your feedback and provide concrete suggestions (we don't often get
those!) :)

What follows below is an official response to your suggestions.

On 10/22/2013 05:29 AM, Simon Grant wrote:
> As the terms "type" is systematically ambiguous, it would seem to me
> to be sensible not to use the term "type" alone, but instead one of
> the terms "node type" or "value type", consistently in the
> documentation, even though they are still implemented through the
> same keyword, "@type".

Let me first start by saying that you make a very good point about
terminology. Confusion over the dual-use of @type was something that we
were concerned about when we made the change a few years ago. You are
underscoring that the concern we had was not unfounded. So, in
principle, the group agrees with your general concern and approach to
addressing the issue. So much so that I think we already make this
distinction in the document. See the definition of "@type":

https://dvcs.w3.org/hg/json-ld/raw-file/default/spec/PR/json-ld/20131105/index.html#syntax-tokens-and-keywords

Granted, this isn't exactly what you're asking for and I do understand
the nuance of what you're saying. The complication arises because of a
series of discussions that various groups at the W3C had regarding
JSON-LD and RDF terminology alignment. There was quite a bit of debate
that went into this terminology (as in months and months of debate). So
we have to be very careful when talking about changes to how we use the
terminology in the document.

This is further complicated by the fact that the JSON-LD specifications
are potentially going to be cleared for a vote by all 392 W3C member
companies in the next 12 hours, at which point the specs need to be
frozen. Making a set of changes like the ones you are proposing could
destabilize the specification and push the ratification of this
specification by the W3C back by a month or two. So, the question
becomes - what is the upside?

At present, as you rightly point out, the language could be better. The
editors did as much as they thought they could by adding notes into the
specification to point out the context-sensitivity of @type in an
attempt to address some of your concerns.

If we were to go a step further and apply the changes that you are
asking for, we run the risk of putting the ratification of the JSON-LD
specifications on hold until we get buy in from the various groups
working on these specifications because some of the changes in
terminology that you are suggesting have cascading effects between the
JSON-LD specifications as well as the RDF Concepts specification.

More specific responses to your suggestions below.

> To make concrete suggestions:
>
> 1. Change the heading of section 5.4 to "Specifying the Node Type".

We had considered doing this before, but decided not to since we didn't
want to make this section that specific.

> 2. Insert "node" into the first paragraph, to read "The type of a
> particular node can be specified using the @type keyword. In Linked
> Data, node types are uniquely identified with an IRI."

We did not want to be that specific in the opening section. The general
rule is that "In Linked Data, types are uniquely identified with an
IRI". I do understand that you're wanting to make this section more
specific, but we wanted to keep it general and high-level.

Getting into that amount of specificity that early in the document will
be lost on most readers that are reading the document for the first time.

> 3. I would suggest omitting example 14, as one could see this as
> beyond "the most basic features". If you want to leave it in, then I
> would rephrase the line above example 14 as something like "The node
> type may also be assigned through a term defined in the active
> context:" and insert "node" into the first line of the actual
> example, to read "EXAMPLE 14: Using a term to specify the node type"

Making this change would introduce the use of 'node type' before it is
defined formally in the document. We try very hard to not use
terminology before it's introduced in the document. There are times
where that general rule has to be broken, but this is not one of those
instances.

> 4. The paragraph concluding section 5 could then read something
> like: "This section only covers the most basic features associated
> with types in JSON-LD. Please note that the @type keyword is used in
> two distinct ways: first, as here, to specify the type of a node; and
> second, to express a value type (as described in section 6.4 Typed
> Values) and to coerce values to a specified value type (as described
> in section 6.5 Type Coercion). Specifically, @type cannot be used in
> a context to define a node type. For a detailed description of the
> differences, please refer to section 6.4 Typed Values."

This is good, I'll try to get clearance from the Director of the W3C to
make this change before publishing the document for a vote by the W3C
membership. There is a chance that this change will be denied for a
variety of reasons. In general, the document is supposed to be stable
when it goes into the transition call. Any changes are frowned upon this
late in the process.

> I find Section 6.4 to be fairly clear as it stands, except for the
> section either side of Example 23. Use of the terms "general" or
> "generally" may bring uncertainty, as the reader may then expect
> specific exceptions to a general rule. I would run the two paragraphs
>  above Example 23 together, to read: "The @type keyword is also used
> to associate a type with a node. The concept of a node type and a
> value type are different. A node type specifies the type of thing
> that is being described, like a person, place, event, or web page. A
> value type specifies the data type of a particular value, such as an
> integer, a floating point number, or a date." (which is then very
> clear and helpful)

We can remove the word "Generally". Running the two sentences together
would violate the way we do most of the examples in the document. We
typically give a simple introduction to the topic, provide an example,
and then explain the example in more detail after the example is shown
on the screen. It's debatable that running the two sentences together
would improve understanding, so the most we can do here is just remove
the word "Generally".

> In the paragraph below Example 23, there is this sentence: "As a
> general rule, when @value and @type are used in the same JSON object,
> the @type keyword is expressing a value type. Otherwise, the @type
> keyword is expressing a node type." I would suggest stating a clear
> and definitive rule here, not using the word "general". Can the
> "@value" keyword be used in a context, or not? That isn't immediately
> clear to me.

@value will not be processed by JSON-LD processor when used in a
context. We say "general" here because an author can do anything they
want to, including using the markup in ways that extend or augment the
JSON-LD specification. When we say "in general", that's what we're
trying to convey.

> If it is true to say that @value inside a context always indicates a
>  value type, then maybe that's the place to start.

It doesn't, so we shouldn't say this.

> This probably won't be right as I draft it, but you could start with
> this and modify it to suit: "The @type keyword expresses a value type
> either if it appears in an expanded term definition within a context,
> or as a key alongside the @value keyword in the same JSON object.
> Otherwise, the @type keyword expresses a node type, and this must be
> outside the context."

The language above is fine. Where did you want this change to be
made/stated? Keep in mind that we would need to get this change approved
and made in the next 48 hours if you want to see it in the spec.

Thanks again, Simon, for your very thorough feedback. We can try to make
some of the changes that we agree on above, but keep in mind that we
also don't want to risk endangering the publication of these
specifications as ratified W3C standards. It's clear to me that you were
able to understand the specification in extreme detail, so there is no
show-stopping problem here. The specification will be useful to the
global Web developer population as is, and all we're talking about here
are minor editorial changes to make the document easier to read for a
first-timer.

A response to this email in the next 48 hours would be appreciated due
to the time crunch that we're under. We'll raise your concerns and
proposed changes with the W3C Director in 12 hours.

-- manu

-- 
Manu Sporny (skype: msporny, twitter: manusporny, G+: +Manu Sporny)
Founder/CEO - Digital Bazaar, Inc.
blog: Meritora - Web payments commercial launch
http://blog.meritora.com/launch/

Received on Thursday, 31 October 2013 04:28:01 UTC