section on document-level @language and @dir has confusing examples

[dbaron]

There are some issues with the examples in the section on document level @language and @dir that make it a bit confusing.

First, the example begins with a link whose text is "original example" but the link is broken; I think it should instead link to section 1.3.1.

Then it's worth noting that this section has three chunks of JSON, but it doesn't clearly identify which of them represent good practice and which of them represent bad practice.

There are a number of differences between the examples that seem to confuse things unnecessarily:

• the second example not only removes the default, but also (as it says) introduces overriding to fix places where that default was incorrect and the language and direction metadata in the first example were thus incorrect
• the third example reintroduces the default but uses the opposite default from the first example
• the third example also introduces an entirely separate concept that it doesn't even mention, by having the "title" be a multi-language array (or object? It's using incorrect syntax that's a blend of array and object syntax) that offers the title in multiple languages.
• the third example has an incorrect language on the publisher

It seems to me that:

• multiple parallel examples would probably be clearer if they showed the same semantics in different ways, rather than differing semantically
• it's probably worth introducing the concept of objects that offer an option in multiple languages (perhaps both with arrays and objects), but that may well be the most complex topic here and it probably shouldn't be slipped in in the third part of an example without being mentioned; I think it probably deserves its own subsection with distinct examples

(I got here from w3ctag/design-reviews#178.)

[aphillips]

@dbaron Thanks for the comments. Some of this is the result of recent document reorganization, which is still in progress.

I fixed the broken link.

The examples on \@language/\@dir are all "valid" examples, although a couple are demonstrative of why you want a default. I will try to clarify. I will also break out localizability/language negotiation.

[BigBlueHat]

Related to these examples, @language as a top-level key does not set the "default language" in JSON-LD as it is described here. The valid JSON-LD format is to use the @context space (as describe in the prose), so the example would start with:

{
  "@context": {"@language": "en"},
  ...
}

Also, we are not planning (currently) to support @dir as implied here in the examples because the underlying RDF-based processing model does not provide a means to describe a base direction for a string value. You can see the JSON-LD WG's discussions about it here: https://github.com/w3c/json-ld-syntax/issues/11

We determined that using embedded HTML restricted to text-level semantics (...through a method yet to be defined...or by implementers/consumers via purification) for any need for bi-directional or multi-language texts. It does require a minimal HTML parser, but it would co-exist with current foundational RDF-model foundations used in JSON-LD at this time.

It's the "best worst" option atm afawk. 😃