Skip to content

Comparison of ways to use vocabulary in content

Jump to bottom
Matthew Tylee Atkinson edited this page Oct 31, 2022 · 85 revisions

This relates to the issue Does personalization semantics work as an ARIA module?. Below are proposed approaches to use personalization semantics in content, with pros and cons for host languages, authors, and user agents. At the bottom is a direct comparison of the approaches by various characteristics.

Options

Note that the Related-vocabularies page mentions microformats (which are distinct from microdata).

RDFa

Use RDFa to attach personalization semantics to content. Requires a namespace URI which is proposed to be https://www.w3.org/ns/aui/.

Associated Issue #53

Example: Action property in HTML using RDFa without prefix

<html>
  <body vocab="https://www.w3.org/ns/aui/">
    <button property="action" content="undo">Revert</button>
  </body>
</html>

Example: Action property in HTML using RDFa with prefix

<html>
  <body prefix="aui: https://www.w3.org/ns/aui/">
    <button property="aui:action" content="undo">Revert</button>
  </body>
</html>
Pros Cons
Host Languages
  • Does not require explicit support from host language, if they support RDFa.
  • Not supported if RDFa not supported by host language.
  • Weak multi platform support. Not well bound to the DOM and can not support simple implementations such as CSS selectors or media queries.
Authors
  • Well-defined integration with other vocabularies.
  • Allows rich relation expression.
  • Complex to author, requires several attributes to add a simple property.
  • Default subject is the page, more complex to annotate an element in the page.
  • Authors have a lot more attributes to fill in. This also adds to the likelyhood of errors.
User Agents
  • May integrate easily with semantic indexing services such as search engines.
  • RDFa not processed in end-user agents.
  • Even simplistic processing requires looking at several attributes, and could be error-prone.
  • Namespace-aware processing (the correct way) is another layer of complexity in support, not generally available in end-user agents.
Support for different fetures
  • support sting terms and value pairs eg: meta property="og:title" content="The Trouble with Bob" - HTML only allows the content attribute on the meta element.
  • Not sure how you can implement everything such as as value paires are only in meta data

HTML Microdata

Use HTML Microdata to attach personalization semantics to content. Requires a vocabulary identification URI which is proposed to be https://www.w3.org/ns/aui/.

Example: Action property in HTML using HTML Microdata

<button itemscope itemtype="https://www.w3.org/ns/aui/" 
  itemprop="action" content="undo">Revert</button>
Pros Cons
Host Languages
  • Does not require explicit support from host language.
  • Only supported by HTML.
  • Weak multi-platform support. Not well bound to the DOM and can not support simple implementations such as CSS selectors or media queries.
Authors
  • Uses a potentially familiar language for custom semantic annotation.
  • Somewhat complex to implement, requires several attributes to attach a simple property.
  • Authors have a lot more attributes to fill in. This also adds to the likelyhood of errors.
User Agents
  • Microdata currently not well supported.
  • Requires processing of several attributes.
Support for different features
  • more support sting terms and value pairs
  • Not sure how you can implement everything such as may be complex for the author, name vlaue spairs follow stict alogithm see https://www.w3.org/TR/microdata/#values. Very limited solution space for tools and help. how to provide inline alteritive text?

aria- Attributes

Apply properties to content with attributes whose name is the property name prefixed by "aria-". Requires approval from the ARIA Working Group to create these attributes.

Associated Issue 54

Example: Undo action with aria attribute

<button aria-action="undo">Revert</button>
Pros Cons
Host Languages
  • No special support required if already supporting ARIA.
  • Not supported if ARIA in general not supported.
  • Not an available option if the ARIA WG does not accept the vocabulary as part of ARIA.
  • ARIA WG is unlikely to accept anything that is not part of their current direction including mapping the the accessibility API of the operating system and not changing the interface. They may accept compatible parts such as additional landmark roles.
Authors
  • Relatively simple to author, one attribute per property.
  • Authors interested in accessibility may already be familiar with ARIA.
  • Potential confusion with other ARIA features.
  • Authors have a lot more attributes to fill in. This also adds to the likelyhood of errors.
User Agents
  • Only simple attribute recognition required.
  • Potential confusion handling attributes since aria- attributes generally trigger accessibility API mapping response.
Support for different fetures
  • full support as we define it
  • NA

aui- Attributes

Apply properties to content with attributes whose name is the property name prefixed by "aui-". Requires approval from the Web Platform Working Group to create these attributes in HTML.

Associated Issue #33 - I believe this Issue may be able to be closed.

Example: Undo action with aui attribute

<button aui-action="undo">Revert</button>
Pros Cons
Host Languages
  • Straightforward to add attributes, or ignore unrecognized ones.
  • Attribute values are "cleaner" than the above option (no awkward semi-colon delimitation)
  • This will seem familiar to developers used to implementing aria-* style attributes
  • This will seem very familiar to angular developers (`
    `)
  • Great for modern frameworks (react, angular, etc) in which the "template" is built in a JavaScript file where relevant data will be available
  • Requires explicit support from host language maintainer to add in a valid way and discusion with web platforms.
  • Requires negotiation with maintainers of each host language.
  • Attribute bloat
  • A lot of attributes to remember (although character delimited key/value pairs have the same problem only within the purpose attribute's value)
Authors
  • Relatively simple to author, one attribute per property.
  • Less confusion with other attributes.
  • Another set of accessibility-specific prefixed attributes.
  • Authors have a lot more attributes to fill in. This also adds to the likelyhood of errors.
User Agents
  • Only simple attribute recognition required.
  • Requires looking for a new class of attributes.

Single Attribute

Apply all properties to content via values of a single new attribute, placeholder name purpose. In order to cram both properties and values into a single attribute value, property names and values would have to be concatenated, or the vocabulary rejiggered (directly or via mapping algorithm) to avoid use of values.

Example: Undo action in purpose attribute with concatenated value

<button purpose="action-undo">Revert</button>

Example: Undo action in purpose attribute with came case value

<button purpose="undoAction">Revert</button>

Example: Undo action in purpose attribute with valueless property as value

<button purpose="undo">Revert</button>

Example: Undo action in purpose attribute with valueless property as value, and prefix

<button purpose="aui-undo">Revert</button>
Pros Cons
Host Languages
  • Easier to support adding one attribute than many.
  • Less attribute namespace to be taken
  • Cramming both properties and values into an attribute value mean a more complex mapping from the vocabulary to language implementation.
  • Still requires negotiation of the new attribute.
  • Must be negotiated for each host language.
  • Can't support multiple properties on same element unless allowing token lists which is more complex to support.
  • On the surface this has less "attribute bloat" but it doesn't really offer any advantages over separating these out into their own attributes
Authors
  • Maybe relatively easy to support a single attribute.
  • Large set of values required for the attribute could be difficult to remember.
  • Supporting multiple properties on the same element more difficult.
  • We have seen implemetions get confuced when an attribute is overoaded and they do it incorrectly (As happened with our first implementions).
User Agents
  • Only one attribute to support.
  • Potentially more complicated attribute value parsing.
User Agents
  • Only simple attribute recognition required.
  • Potential confusion handling attributes since aria- attributes generally trigger accessibility API mapping response.
Support for different features
  • only supports some features
  • no idea how to support for text values. How to implement larger context such as symbol without making the model untestable

Single Attribute
(alternative notation: CSS-Style declaration of key/value pairs)

Apply all properties to content via values of a single new attribute, placeholder name purpose.

To accommodate the different types of values (which can be one of "string value", "token" (from a fixed list), or "URI"), this ideas proposes to use notation similar to inline CSS. While a completely new idea, text strings would be enclosed in ('text string') as part of the proposed new notation, and urls would borrow from the same pattern as CSS: url('path to file'); in either instance with or without the single '.

Example: Undo action in purpose attribute with concatenated values

<button purpose="action:undo; easylang:('Undo')">Return to the previous design</button>

Example: Form input(s)

<input type="text" name="telnum" aria-required="true" 
purpose="field:password; moreinfo:url('PasswordFAQ.html'); 
symbol:url('images/helpicon.png'); importance:critical;"/>

Example: Link to more help (with alternative icon support)

<a href="" purpose="destination:help; easylang:('Get Help'); 
messageimportance:critical; symbol:url('images/helpicon.png'); 
extrahelp:url('extrahelp.html');">Still having trouble?</button>
Pros Cons
Host Languages
  • Easier to support adding one attribute than many.
  • Utilizing a selector allows elements to share configuration (an attribute approach would force a lot of repeating assuming multiple elements would require identical config)
  • No attribute bloat whatsoever
  • Cramming both properties and values into an attribute value mean a more complex mapping from the vocabulary to language implementation.
  • Still requires negotiation of the new attribute.
  • Must be negotiated for each host language.
  • Separation of markup and configuration
  • Requires a separate entity? (assuming this would be either within a special "tag" (like css in `<style />`), or a separate file all together
Authors
  • Maybe relatively easy to support a single attribute.
  • Replicates common authoring pattern from CSS
  • Large set of values/value-pairs required for the attribute could be difficult to remember.
  • We have seen implemetions get confuced when an attribute is overoaded and they do it incorrectly (As happened with our first implementions). (unverified)
  • May be difficult to support in WYSIWYG editors (unverified)
User Agents
  • Only one attribute to support.
  • Potentially more complicated attribute value parsing.
  • slow performance due to parsing. (unverified)
User Agents
  • One simple? attribute recognition required.
  • attribute parsing required. not all implmentions may support this

Single Attribute with extra attributes for text content
(alternative notation: CSS-Style declaration of key/value pairs)

Apply all properties that give tokens to content via values of a single new attribute, placeholder name purpose.

purpose="simplification:critical; field:familyName" easylang="Last name"

To accommodate the different types of values fromm "token" (from a fixed list), or "URI"), this ideas proposes to use notation similar to inline CSS. Like the idea above, and urls would borrow from the same pattern as CSS: url('path to file'); in either instance with or without the single '.

However, unlike the above option string values may have a separate attribute

This has the advatage of making it easy to add a simple text or number free equivelent text. (a concern for the single attribute is that it is easy to make errors - This may be more of a problem for content authors with learning disabilities

3 attributes

3 attributes: Attribute for tokens, attribute for URIs and attribute for text

Apply all properties that give tokens to content via values of a single new attribute, placeholder name context. All text is added in a second attribute placeholder name easylang. more then one entery can be seperated by a space URIs are in a a third attribute placeholder name refrences. context="critical fieldFamilyName" easylang="Last name" refrences="blis.org/1046236"

Issues: does it fit with all the bellow? Is it confusing and will make author errors

Tokens (from https://raw.githack.com/w3c/personalization-semantics/value-list/vocabulary-list/index.html )

  • 2.1.1 action
  • 2.1.2.destination
  • 2.1.3field
  • 2.1.4simplification
  • 2.1.5distraction
  • 2.2.1.1Values for alternative content and content accessibility support
  • 2.2.1.2Values for types of help
  • Status (from Step Indicator Usage)
  • 2.3.2.1messageimportance

URI’s

  • 2.1.6symbol
  • 2.2.2.2.6moreinfo
  • 2.2.2.2.7extrahelp
  • 2.2.2.2.7.1Description
  • Steplocation – could we use href instied? (from Step Indicator Usage)

Text

  • 2.2.2.2.1literal
  • 2.2.2.2.2numerfree
  • 2.2.2.2.4explain
  • 2.2.2.2.5feedback
  • 2.2.2.2.3easylang
  • 2.3.2.2messagefrom
  • 2.3.2.3messagecontext
  • 2.3.2.4messagetime (restricted)
  • Step (from Step Indicator Usage) numeric

value pairs

Apply properties to content via values of a value pairs , such as clarificationType = "easylang", clarificationValue= "xyz "

Pros Cons
Host Languages
  • Easier to support adding two attributes than many.
  • Still requires negotiation of the new attribute.
  • Must be negotiated for each host language.
  • Can't support multiple properties on same element unless allowing token lists which is more complex to support.
Authors
  • Relatively easy to support a pair of attributes.
  • More complex than single attribute.
  • May not be feasible to support multiple properties on the same element.
User Agents
  • Only two attributes to support.
  • Potentially more complicated attribute value parsing (for example CSS selectors become more complex).
Support for different features.
  • Only supports one value pair per element

Native Host Language Features

Work with maintainers of host languages to add support for the personalization semantics vocabulary directly into the host language. Most simply this would involve creating attributes named for the personalization properties, but other approaches are possible.

Example: Undo action as native feature of button element in HTML

<button type="undo">Revert</button>

We discussed having this as a long term goal and making an additional note on how the vocabulary could be supported in host languages. However we do not expect to achieve the full use-cases in the native hosts and we will need implementation before we go to groups like HTML.

JavaScript Object

NOTE: This could be in JSON format as well (it'd look almost identical to the below code sample)

Code sample

{
  .foobar: {
    field: "password";
    moreinfo: url('PasswordFAQ.html'); 
    symbol: url('images/helpicon.png'); 
    importance: critical;
  }
}
Pros Cons
Host Languages
  • All of the pros for the CSS-Style declaration of key/value pairs
  • Already in JavaScript which assumes would be the language consuming this anyway
  • All of the cons for the CSS-Style declaration of key/value pairs
Authors
  • Developers are familiar with JavaScript so they'd be comfortable with the syntax (although not all web devlopers are JavaScript devlopers)
  • Much longer/more to write then the aui- multiple attribute
  • Not all web devlopers are JavaScript devlopers, and this is much harder / possible barrier for non Json/JavaScript devlopers, unless it is set up genericly and these become phudo css class names.
  • For each menu item (such as the link to the home page, and the link to contact us page) the author needs to create a separate object with a separate name. Much more to write for authors then any other option unless it has all been set up. If it has been set up there may also be errors where it is not set up correctly for this specific case. (We may/have used this for the user settings and prefrences but that is a very diffrent case).
User Agents

Data Set (data-* or data-aui-* attributes)

Code sample

<div
  data-aui-field="password"
  data-aui-moreinfo="PasswordFAQ.html"
  data-aui-symbol="images/helpicon.png"
  data-aui-importance="critical"
/>
Pros Cons
Host Languages
  • Modern frameworks all support passing data attributes through to the rendered html (react wouldn't throw any warnings)
  • All of the cons for the AUI attributes (aui-*)
  • What is the populer fraimworks change, so although this is populer now we do not know if it will be in the future
  • The data-* attributes is typicaly used to store custom data private to the application. This is not private and not custom - it seems to brake the data-* pardyme
Authors
  • This is a very common convention which means less push-back/resistance from developers implementing this
  • longer/more to write then the aui- multiple attribute
  • It is a common convention for some groups of developers but not for all, and not for less intence devlopers, who are our first implemetions, and we want to continue to meet them.
    • User Agents

    New Example showing AUI-Attributes, Single AUI Attribute+microSyntax and 3 AUI Attributes

    This is a contribed example of how a form might be marked up to allow for personalization. Here we show different possible approaches. With reference to the original form without any markup, the following examples all use the same personalization semantics:

    • EasyLang: Replace Given name with "First name"
    • EasyLang: Replace Surname with "Last name"
    • EasyLang: Replace Revert with "Clear Information"
    • EasyLang: Replace Submit with "Send Information"
    • Symbols: provide link to a "discard" symbol
    • Simplification: Set First/Last/Submit as Critical

    Note: In the 3 attribute example 'aui' will still contain microSyntax for all other possible attributes, and only aui-numbersFree and aui-EasyLang are split out due to their potential complexity requiring multiple sentences. In my example I do have EasyLang but didn't include aui-numbersFree but it would match the same pattern.

        <h2>Original - No Personalization</h2>
    <form>
      <label for="first">Given name:</label>   
      <input type="text" id="given" name="givenname">   <br>
      <label for="last">Surname:</label>
      <input type="text" id="sur" name="surname">       <br>
      <input type="button" value="Revert">  
      <input type="submit" value="Submit">
    </form>


<h2>Individual Attributes</h2>
    <form>
      <label for="given" aui-simplification="critical" aui-easylang="First name" aui-field="givenName">Given name:</label>   
      <input type="text" id="given" name="givenname">   
        <br>
      <label for="sur" aui-simplification="critical" aui-easylang="Last name" aui-field="familyName">Surname name:</label>   
      <input type="text" id="sur" name="surname">       
        <br>
      <input type="button" value="Revert" aui-easylang="Clear Information" aui-symbol="http://blisssymbolics.org/refnumber/18043" aui-action="undo">  
      <input type="submit" value="Submit" aui-simplification="critical" aui-easylang="Send Information" aui-action="submit">
    </form>

<h2>1 Attribute + microSyntax (Without Quotes)</h2>
    <form>
      <label for="given" aui="simplification:critical; easylang:(First name); field:givenName">Given name:</label>   
      <input type="text" id="given" name="givenname">   
        <br>
      <label for="sur" aui="simplification:critical; easylang:(Last name); field:familyName">Surname:</label>
      <input type="text" id="sur" name="surname">       
        <br>
      <input type="button" value="Revert" aui="easylang:(Clear Information); symbol=url(http://blisssymbolics.org/refnumber/18043); action:(undo)">  
      <input type="submit" value="Submit" aui="simplification:critical; easylang=(Send Information); action:(submit)">
    </form>
    
<h2>1 Attribute + microSyntax (With Quotes)</h2>
     <form>
      <label for="given" aui="simplification:critical; easylang:('First name'); field:givenName">Given name:</label>   
      <input type="text" id="given" name="givenname">   
        <br>
      <label for="sur" aui="simplification:critical; easylang:('Last name'); field:familyName">Surname:</label>
      <input type="text" id="sur" name="surname">       
        <br>
      <input type="button" value="Revert" aui="easylang:('Clear Information'); aui-symbol=url('http://blisssymbolics.org/refnumber/18043'); action:('undo')">  
      <input type="submit" value="Submit" aui="simplification:critical; easylang=('Send Information'); action('submit')">
    </form>
 
<h2>3 Attributes</h2>
    <form>
      <label for="given" aui="simplification:critical; field:givenName" easylang="First name">Given name:</label>   
      <input type="text" id="given" name="givenname">   
        <br>
      <label for="sur" aui="simplification:critical; field:familyName" easylang="Last name">Surname:</label>
      <input type="text" id="sur" name="surname">       
        <br>
      <input type="button" value="Revert" aui="symbol:url('http://blisssymbolics.org/refnumber/18043'); action=undo" easylang="Clear Information">  
      <input type="submit" value="Submit" aui="simplification:critical; action:submit" easylang="Send Information">
    </form>

    Overview

    Pros Cons
    Host Languages
    • Not asked to support an external vocabulary.
    • Large set of new features being asked to add.
    • Potential for token collision between personalization features and other existing or contemplated features.
    • Only supported on host languages which have negotiated this approach.
    Authors
    • Not using features that seem ancillary to the main language.
    • Makes personalization more mainstream.
    • (CL?) Supports multiple properties on the same element
    • Potential confusion between personalization and other aspects of the host language.
    • Different host languages could support personalization in different ways, or even different subsets.
    • Personalization not available for host languages that haven't accepted this approach.
    User Agents
    • No need to process non-native features.
    • Increases expectation to have out-of-the-box support for personalization.
    Support for different features
    • support for negotiated features
    • many features are likly to not be supported

    Overall Summary

    The table below compares approaches by various characteristics. The comparison is over-simplified to allow a binary "yes / no" for each feature, to facilitate overall coverage grokking. Features are worded, sometimes awkwardly, to result in a positive outcome being the one that gets an X for the feature.

    Michaels table

    Feature RDFa Microdata aria- aui- attribute attribute pair native
    Authoring
    Easy to author x x x x x
    No ambiguity between personalization and other features x x x x x x
    User Agents
    Easy for user agents to find properties x x x x
    Simple parsing of values x x x x
    Easy path to support via browser extensions x x x x x
    Host Languages
    Does not require special host language support x x x
    Same approach works in multiple host languages x x x x
    Integration with ARIA x
    Integration with HTML x x
    Easy extensibility of vocabulary x x x x x x
    Doesn't overload host language with many new features x x x x
    Functionality
    Multiple properties on same element x x x x x
    Integration with other vocabularies x x
    Likely search engine support for content alternatives x x
    Multiple properties on different elements working together x x x x x
    Typed value support x x x
    Strategy
    Avoid segration of "that accessibility stuff" x
    Clear path to joining other W3C personalization efforts x x x
    Likely stable approach not requiring later change to authored content x x x x x x

    Lisa's table

    issue RDFa Microdata aria- aui- attribute attribute pair native
    require explicit support from host language x - via aria x x x
    bound to the dom - so will work with easy user agents like css x x mid mid x
    multi platform support x x x x x
    authors - mistake prone XX xx x x
    author effort xx xx x x x x
    user agent error prone xx xx
    full feture support theroticaly possibe XX with pairs X theroticaly possibe

    External Implementations

    Resolved (27/08/2018) that this discussion is not needed to decide how to put vocabulary in content. However, it should be discussed later and there is a request for clear usecases and demo implementations.

    Decouples semantics from the DOM/presentation layer

    JSON-LD - JSON-based format to serialize Linked Data

    Taken from Issue #73 Low level imperative API

    JavaScript API - Accessibility Object Model

    Gives access to lower level APIs and enables the author to define bindings to HTML

    Taken from Issue #73 Low level imperative API

    Web Annotation

    Taken from Issue #84

    Input from Jason White - "A tool (e.g., custom user agent, proxy, browser extension) could maintain a list of trusted annotation providers, and match each page that the user accesses with a list of URIs of pages for which annotations are available."

    Additional Resources

    The following are interpreted to be suggested resources which may be of interest in the research of implementations. These references are more specific to defining taxonomy and/or semantics.

    Taken from Issue #74

    Clone this wiki locally