Improve keyword descriptions

[gkellogg]

• Improved @type keyword definition, and added Uses of JSON Objects section.
• Add a section on keywords to the grammar, and slight improvement to type values.

Addresses #77.

---

Preview | Diff

[gkellogg]

@azaroth42 I didn't see a way to significantly improve 4.2.1; perhaps the other changes do the job.

[msporny]

Overall good with editorial nits.

[msporny]

"type interpreted"? not familiar with that term? Did we rename "type coercion" to "type interpretation"?

[gkellogg]

@iherman had some pushback on the notion of "type coercion", and "type interpretation" seemed like it might be a better fit. What happens in this case, is that the @type in the term definition is what allows the string value to be interpreted as a dateTime. But, it should probably be "interpreted as" rather than "type interpreted as".

Personally, I could go either way on this. Strictly speaking, "coercion" would be when something of one type is converted to another type, perhaps automatically because of an operation such as addition or concatenation. In this case, arguably, the string has no inherent type, and it is interpreted as an xsd:string, in the absence of any more explicit @type declaration.

[msporny]

This makes it sound like an aliased @type MAY be used as a key in an expanded term definition... guessing other rules prevent this... probably don't need to change it, but my reading of the previous sentence and this sentence threw me a bit.

[gkellogg]

This is a pattern I came up with, and I'm happy to do something else. The first sentence says that it may be aliased when used in a node object or value object. The second is that it may be used unaliased as a key in an expanded term definition.

Suggestions for a clearer description welcome.

[msporny]

I wouldn't start by saying that this can be confusing. It's confusing to people that have deep knowledge, but for beginners I don't expect it is.

Things have types. Nodes have types. Values have types. You use @type to express that. That's not confusing.

The confusing part is probably the chording of @type with other things like @value and a node to get the expression you want... but we really only do that in one place that only experts tend to see.

In any case, I'd reword to something like:

The use of @type to define a type for both node objects and value objects addresses the basic need to type data, be it a literal value or a more complicated resource. Experts may find the overloaded use of the @type keyword for both purposes concerning, but should note that Web developer usage of this feature over multiple years has not resulted in its misuse due to the far less frequent use of @type to express typed literal values.

[gkellogg]

But, the fact is, for many it seems to be a confusing issue. But, I like your wording better!

[iherman]

@gkellogg I like what I see, but I have two more proposals

• I think it may be worth exchanging the order for 3.4 and 3.5. The new 3.5 could then very explicitly refer to the fact that @type is used to set a type on value objects and node objects, something that will have been described in the previous section. I would think that 3.5 should then have two subsections: one for node objects (which is the current content, essentially) and one for value objects, describing the usage of datatypes. These two sections together might then settle the original issue.
• You use the term map objects, which is fine, but this may just indicate that the term @container to denote all these objects may not be the right term and may be another source of confusion. We should keep the @container for lists or sets (and, of course, we should allow the old usage for, eg, language maps) but we should have a separate @map to define, well, the map objects. We should discuss that separately, though.

[gkellogg]

@iherman Your first point is well taken, and I'll make the suggested change.

Regarding changing @container to @map for new map objects, I disagree. The mold was cast when we used @container for language- and data-maps. Also, it would add additional steps to the context and expansion algorithms, to no great effect. I thought we had already discussed this on a call.

[gkellogg]

@iherman I made your suggested changes to "Use of JSON Objects" and "Specifying the Type".

[iherman]

@gkellogg thanks for the changes you made. Two more comments (just for nagging you:-)

• I think adding an example for datatype, ehem, value object type, would be good as well. Just to have this on an equal footing, so to way, with the node object type; it currently reads as some sort of a side remark.
• the second note in that section repeats information that is now part of the core text, and should be removed.

Thx!

[gkellogg]

I think adding an example for datatype, ehem, value object type, would be good as well. Just to have this on an equal footing, so to way, with the node object type; it currently reads as some sort of a side remark.

There are examples in the referenced sections, I don't see a point in repeating them, particularly as the section is mostly about typed objects. The "Specifying the Type" section is really about typing node objects, to make it clear, I discuss typing value objects and reference "Typed Values" and "Type Coercion". Do you really think we need to repeat that detail here?

The reason "Specifying the Type" is in the "Basic Concepts" section, as this is considered a basic concept, while typed values are considered advanced. Otherwise, we'd need a separate section "Describing Nodes". But, there's really not enough there do do that, IMHO.

the second note in that section repeats information that is now part of the core text, and should be removed.

I'll pare out some of the repeated detail, but the original purpose of the note is that this describes basic features. Instead, I'll reference the "Advanced Concepts" section.

[iherman]

@gkellogg first of all, I do not want to micromanage. As far as I am concerned this PR can be merged right away and it may be indeed enough to answer to #77. You are free to take or drop any of my comments.

That being said, I guess the main reason of my comment is this remark:

The reason "Specifying the Type" is in the "Basic Concepts" section, as this is considered a basic concept, while typed values are considered advanced. Otherwise, we'd need a separate section "Describing Nodes".

I do not feel that typing a node is a basic concept whereas typing a value is an advanced. To be more precise, I do not see why these two should be different. You are right that section 4.2 is already there, in particular 4.2.1, and I understand that you do not want to repeat things. My feeling is, however, that 4.2 and 3.5 should be on equal footing; I do not have a strong feeling whether 3.5 should be moved into the 'advanced' category, or 4.2. (or possibly 4.2.1. only) should be put into the basic section, but I would think these two should be somehow kept together.

Again, regardless from this, 👍 from me to merge at your discretion.