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

Hi Manu and all

Thanks for all your splendid work on the spec so far!

I can see the place where you have found yourselves, and I'm sorry that you
feel you have to reject further improvements because of constraints of time
and process stage. I have seen much worse than this in other
standardization forums that I shall not name! But it's still a pity and,
for reflection, it might be worth thinking about how this came about, so
that a process that is already very good can be further improved.

I am personally convinced that, in cases like this where a new spec is
being put around for adoption, every small improvement to understandability
is worth the effort. When it is already accepted, perhaps the pressure
becomes less.

You don't give me many options, do you? :) Let's see if I can isolate where
you have not pleaded "fait accompli" and respond accordingly in line.

On 31 October 2013 04:27, Manu Sporny <msporny@digitalbazaar.com> wrote:

> [...]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.


But that's what the section is in fact describing, so I'm surprised by
this. Maybe when it was considered before, the section was indeed trying to
do more, but now it isn't!

[...]
>
>> 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.


Well, the obvious response to this would be to define them formally,
earlier in the document, wouldn't it? OK, you're going to say, "but it's
too late .... ... ..."


> [...]
>
>> 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.


Well, but of course I am not suggesting an actual change to the spec, am I?
Just better clarification...


>
>
>  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".


Give it a go!

>
>
>  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.


That was my mistake, I meant @type not @value.

>
>
>  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.
>

In the place discussed: the paragraph below  Example 23, in place of the
part of that paragraph starting "As a general rule..." to the end.


> [...] It's clear to me that you were
> able to understand the specification in extreme detail, so there is no
> show-stopping problem here.


With respect, we were never talking about stopping the show, we were
talking about improving the chances of adoption of the spec by ironing out
confusion. I was only able to understand the spec in such detail by
spending very considerable time on it. I would like to spare others some of
that time.


> 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.
>

Hmm... :)

>
> 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.


Thanks! Let's hope the best possible version is the one that is finalized
-- best wishes and good luck for that!

Simon
-- 
from Simon Grant +44 7710031657 http://www.simongrant.org/home.html