There are a number of accessibility considerations implementers should be -aware of when processing data described in this specification. As with any web -standards or protocols implementation, ignoring accessibility issues makes -this information unusable to a large subset of the population. It is important -to follow accessibility guidelines and standards, such as [[WCAG21]], to ensure -all people, regardless of ability, can make use of this data. This is +aware of when processing data described in this specification. As with +implementation of any web standard or protocol, ignoring accessibility issues +makes this information unusable to a large subset of the population. It is +important to follow accessibility guidelines and standards, such as [[WCAG21]], +to ensure all people, regardless of ability, can make use of this data. This is especially important when establishing systems utilizing cryptography, which have historically created problems for assistive technologies.
@@ -4669,105 +4714,135 @@-There are a number of internationalization considerations implementers should be -aware of when publishing data described in this specification. As with any web -standards or protocols implementation, ignoring internationalization makes it -difficult for data to be produced and consumed across a disparate set of -languages and societies, which would limit the applicability of the -specification and significantly diminish its value as a standard. +There are a number of internationalization considerations implementers +are advised to be aware of when publishing data described in this specification. +As with any web standards or protocols implementation, ignoring +internationalization makes it difficult for data to be produced and consumed +across a disparate set of languages and societies, which would limit the +applicability of the specification and significantly diminish its value as +a standard. +
+ ++Implementers are strongly advised to read the +Strings on the Web: Language and Direction Metadata document +[[STRING-META]] published by the W3C Internationalization Activity as it +elaborates upon the need to provide reliable metadata about text in order to +support internationalization. Implementers are also urged to read the +Implementation Guidance [[VC-IMP-GUIDE]] for the latest information related to +this topic.
This section outlines general internationalization considerations to take into -account when utilizing this data model. +account when utilizing this data model and is intended to highlight specific +parts of the Strings on the Web: Language and Direction Metadata +document [[STRING-META]] that implementers might be interested in reading.
-When expressing human-readable text content in the data model, it is important -for presentation, accessibility, and further processing to specify the language -of the text, as follows: +Data publishers are strongly encouraged to read the section on +Cross-Syntax Expression in the Strings on the Web: Language and Direction +Metadata document [[STRING-META]] in order to ensure that the expression +of language and/or base direction information is possible across multiple +expression syntaxes such as [[JSON-LD]], [[JSON]], and CBOR [[?RFC7049]].
-@language feature, as described in [[!JSON-LD]] 1.1,
-Section 4.2.3: String Internationalization.
- rdf:HTML string literal type, as described in [[!JSON-LD]] 1.0,
-Section 4.2.1: Typed Values.
-This mechanism enables developers to use the internationalization features
-present in HTML to express language information. For example, consider the
-following key-value pair:
-
- -"nameHtml": "<span lang="jp">和美</span>" -- -
-If the JSON-LD Context expressed that any value associated with the
-nameHtml property as being of type rdf:HTML, then
-software agents rendering the property can deterministically identify the
-language in use.
-
+The general design pattern is to use the following markup template when +expressing a text string that is tagged with a language and, optionally, a +specific base direction: +
-+"property": { + "value": "The string value", + "lang": "LANGUAGE" + "dir": "DIRECTION" +} +
-When expressing human-readable text content in the data model, it is important -to be able to explicitly encode the text direction. JSON and its derived formats -use the UTF-8 encoding of [[Unicode]] for serializing and transmitting text. -This enables text direction to be directly determined in simple cases, -but the mechanism is insufficient for general use. +An example utilizing the design pattern above is shown below to express the +title of a book in the English language without specifying a text direction:
+
+"title": {
+ "value": "HTML and CSS: Designing and Creating Websites",
+ "lang": "en"
+}
+
+
-[[!JSON-LD]] supports the expression of text layout information using the
-rdf:HTML string literal type, as described in [[!JSON-LD]] 1.0,
-Section 4.2.1: Typed Values.
-This mechanism enables developers to use the internationalization features
-present in HTML to express language information. For example, consider the
-following key-value pair:
-
-
-"nameHtml": "<span dir="rtl" lang="ar">HTML و CSS: تصميم و إنشاء مواقع الويب</span>" +The next example uses a similar title expressed in the Arabic language with a +base direction of right-to-left: + + ++"title": { + "value": "HTML و CSS: تصميم و إنشاء مواقع الويب", + "lang": "+ar" + "dir": "rtl" +}+The text above would most likley be rendered incorrectly as left to right +without the explicit expression of language and direction as many systems will +use the first character of a text string to determine text direction.
-If the JSON-LD Context states that any value associated with the -
nameHtmlproperty is of typerdf:HTML, then software -agents have sufficient information to deterministically identify the text -direction of the language. + ++Implementers utilizing JSON-LD are strongly urged to +extend the JSON-LD Context defining the +internationalized property and utilize the Scoped Context feature of +JSON-LD to alias the
+@value,@language, and +@directionkeywords tovalue,lang, +anddir, respectively. An example of a JSON-LD Context snippet +doing so is shown below:+"title": { + "@context": {"value": "@value", "lang": "@language", "dir": "@direction"}, + "@id": "https://www.w3.org/2018/credentials/examples#title" +} ++
-In some situations it is common to use
-Ruby characters
-to ensure text information is clear and as useful as possible.
-[[!JSON-LD]] support for HTML data allows text to be encoded with ruby,
-supporting these cases.
+When multiple languages, base directions, and/or annotations are used in a
+single natural language string, more complex mechanisms are typically required.
+It is possible to utilize markup languages, such as HTML, to encode
+text with multiple language and/or base directions. It is also
+possible to use the rdf:HTML datatype to encode such values
+accurately in JSON-LD.
+
+Despite that possibility, implementers are strongly discouraged from encoding
+information as HTML because doing so 1) requires some version of an HTML
+processor, which increases the burden of processing language and/or base
+direction information, and 2) increases the security attack surface when
+utilizing this data model as blindly processing HTML could result in executing
+a script tag that an attacker injected at some point during the
+data production process.
-The W3C Internationalisation document [[string-meta]] gives more information -about the need to be able to provide reliable metadata about text to support -internationalization. +If implementers feel that they have to use HTML, or other markup languages +that are capable of containing executable scripts, to achieve a particular +use case, they are advised to analyze how an attacker would use the markup to +mount injection attacks against a consumer of the markup and deploy mitigations +for the identified attacks.