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

Hi Manu

Thanks for this clear summary.

I've just re-read the current sections 5.4 and 6.4 and I confess I am left
still with some confusion. While the documentation is better than it was, I
still think that further improvement at this stage would greatly help new
authors and users of JSON-LD.

Here are some suggestions for further improvement.

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

To make concrete suggestions:

1. Change the heading of section 5.4 to "Specifying the Node Type".

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

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"

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

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)

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.

If it is true to say that @value inside a context always indicates a value
type, then maybe that's the place to start. 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."

Something like that would nail it for me.

Hope this is helpful!

Simon


On 22 October 2013 08:40, Manu Sporny <msporny@digitalbazaar.com> wrote:

> Hi Simon, Adrian,
>
> Thank you for your feedback on the JSON-LD specifications. This is an
> official response to RDF-ISSUE-163: Determine if @type overloading is
> acceptable for JSON-LD 1.0, which is being tracked here:
>
> http://www.w3.org/2011/rdf-wg/**track/issues/163<http://www.w3.org/2011/rdf-wg/track/issues/163>
>
> Both of you commented on the mechanism that JSON-LD uses to specify type
> information associated with a subject and an object. Simon noted that
> the meaning of @type can be confusing as it is sensitive to the context
> in which it is used. In general, when @type is used in a JSON-LD
> Context, it specifies the datatype for a particular value associated
> with a term. When used in a JSON-LD document body, it specifies the
> rdf:type of a subject.
>
> As both of you may or may not know, initially there were two separate
> mechanisms for this behavior. @type to set rdf:type, and @datatype to
> set the datatype for a particular value associated for a term. The group
> decided to reduce the number of special keywords that must be used and
> generalize the mechanism to just @type. This sets the type of a node in
> a graph. As Simon mentioned, this leads to a slight amount of confusion
> for first time authors, but experience has shown that a simple reading
> of the specification or a tutorial make the usage more clear.
>
> Both the JSON-LD group as well as the RDF WG have decided to keep the
> feature as-is for the time being, while adding some editorial text to
> clarify the use of @type in the JSON-LD Context vs. the JSON-LD document
> body.
>
> We believe this strikes the right balance between the choices that were
> in front of the groups. Please respond as soon as possible to this email
> to tell us whether or not you are satisfied with the decision of the group.
>
> -- 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/ <http://blog.meritora.com/launch/>
>



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