Re: @alt descriptions for Thing Descriptions

+1 to moving forward.

Joshue, I presume that the content itself would be semantically marked up
(correct?). i.e.

<!-- begin example -->

<p>This vocabulary contains three classes, they are:</p>

<fieldset>
   <legend>Link class</legend>
     <ul>
        <li>{href: anyURI</li>
        <li>  type: string [0..1]</li>
        <li>  rel: string [0..1]</li>
        <li>  anchor: anyURI} </li>
     </ul>
</fieldset>


<!-- End example -->

Note: I'm not 100% sure about the use of legend and fieldset here: the
semantics make sense on paper (at least to me), but not sure if there is a
practical utility to that grouping (I could not discern one in my quick
NVDA testing). Not a hill to die on.

Note 2: we could also maybe do this:

<p>This vocabulary contains three classes, they are:</p>

<p id="foo">Link class</p>
     <ul aria-labeledby="foo">
        <li>{href: anyURI</li>
...

But again, I'm not getting any practical utility from it (but... I really
want to ensure that "Link class" is a direct label to the list, and not an
inferred one. Janina, am I going too far? Does making "Link class" a nested
header help any further (feels wrong to me, but...))

I know, I know... John, put down the coffee, you've had enough... (in the
end, semantic markup is the goal - at least for me Josh)

JF


On Fri, Jun 14, 2019 at 11:21 AM Janina Sajka (janina@rednote.net) <
janina@rednote.net> wrote:

> Colleagues:
>
> If there is no disagreement with Josh's suggestion, I would like to
> start a CfC to test whether we have consensus to make this a formal APA
> comment on the Web of Things Thing specification.
>
> NOTE: The specification is a Candidate Recommendation (CR) currently,
> thus the desire to move expeditiously.
>
> Janina
>
> Joshue O Connor writes:
> > Hi Janina and all,
> >
> > Here is my pass at providing alternate text for the figures contained
> within
> > the Thing Description spec.
> >
> > I hope this is useful.
> >
> > Josh
> >
> > <Thing Description Alternate Text>
> > https://w3c.github.io/wot-thing-description/
> >
> > //Figure 1 TD Core Vocabulary
> >
> > Thing Class - Table contains:
> > @context: anyURI (or Array)
> > @type: string [0..*]
> > id: anyURI
> > title: string
> > description: string [0..1]
> > created: dateTime [0..1]
> > modified: dateTime [0..1]
> > support: anyURI [0..1]
> > base: anyURI [0..1]
> > security: string [0..1]
> >
> > NOTE: Each class is represented visually in it's own table.
> >
> > This 'root' thing class relates to and feeds the following class tables:
> >
> > Form class
> > {forms [0..*]
> > Link [0..*]}
> > MultiLanguage class
> > {titledescriptions [0..1]}
> > VersionInfo class
> > {version [0..1]
> > instance: string}
> >
> > SecurityScheme class
> > {securityDefinitions: [1..*] }
> >
> > PropertyAffordance class
> > {observable: boolean [0..1]
> > properties [0..*]}
> >
> > ActionAffordance class
> > {safe: boolean
> > idempotent: boolean [0..1]
> > actions: 0..*
> > events:0..1
> > input:0..1
> > output: 0..1}
> >
> > EventAffordance class
> > {data
> > subscription
> > cancellation}
> >
> > PropertyAffordance class also feeds the DataSchema class, as does the
> > Interaction Affordance class. The Interaction Affordance class feeds the
> > Multilanguage and Forms class.
> >
> > InteractionAffordance class
> > {uriVariable:[0..*]}
> >
> > PropertyAffordance class
> > {observable: boolean [0..1]
> > properties [0..*]}
> >
> > ActionAffordance class
> > {safe: boolean
> > idempotent: boolean [0..1]}
> >
> > EventAffordance
> >
> > // Figure 2 JSON schema vocabulary
> >
> > DataSchema Class - Table contains
> > @type: string [0..*]
> > title: string
> > description: string [0..1]
> > const: (any type) [0..1]
> > unit: string [0..1]
> > enum: (Array)[0..*]
> > readOnly: boolean
> > writeOnly: boolean
> > format:  string [0..1]
> >
> > StringSchema, BooleanSchema, NullSchema class all feed the DataSchema
> class.
> >
> > As does:
> >
> > ArraySchema class
> > {minitems: unsignedInt [0..1]
> > maxitems: unsignedInt [0..1]}
> >
> > ObjectSchema class
> > {required: string [0..*]
> > maxitems: unsignedInt [0..1]}
> >
> > NumberSchema class
> > {minimum: double [0..1]
> > maximum: double [0..1]}
> >
> > IntegerSchema class
> > {minimum: integer [0..1]
> > maximum: integer [0..1]}
> >
> > The DataScheme class property const: [oneOf: 0..*] feeds the
> MultiLanguage
> > class.
> >
> > MultiLanguage class
> > {titles: [0..1]
> > descriptions: [0..1]}
> >
> > Also ObjectSchema and ArraySchema feed items and properties properties to
> > the const property of the DataSchema class.
> >
> > //Figure 3 WoT security vocabulary
> >
> > SecuritySchema class - Table contains
> > @type: string [0..*]
> > scheme: string
> > description: string [0..1]
> > proxy: anyURI [0..1]
> >
> > The scheme property from the SecuritySchema class feeds the MultiLanguage
> > class. The MultiLanguage class contains:
> >
> > MultiLanguage class
> > {descriptions: [0..1]}
> >
> > The SecuritySchema class is fed by the following 10 classes:
> >
> > NoSecurityScheme class
> >
> > BasicSecurityScheme class
> > {in: string
> > name: string [0..1]}
> >
> > DigestSecurityScheme class
> > {gop: string
> > in: string
> > name: string [0..1]}
> >
> > APIKeySecurityScheme class
> > {in: string
> > name: string [0..1]}
> >
> > BearerSecurityScheme class
> > {authorization: anyURI[0..1]
> > alg: string
> > format: string
> > in: string
> > name: string [0..1]}
> >
> > CertSecurityScheme class
> > {identity: string [0..1]}
> >
> > PSKSecurityScheme class
> > {identity: string [0..1]}
> >
> > PublicSecurityScheme class
> > {identity: string [0..1]}
> >
> > PopSecurityScheme class
> > {authorization: anyURI[0..1]
> > alg: string
> > format: string
> > in: string
> > name: string [0..1]}
> >
> > OAuth2SecurityScheme class
> > {authorization: anyURI[0..1]
> > token: anyURI [0..1]
> > refresh: anyURI [0..1
> > scopes: anyURI [0..1]
> > flow: string }
> >
> > //Figure 4 Hypermedia controls vocabulary
> >
> > This vocabulary contains three classes, they are:
> >
> > Link class
> > {href: anyURI
> > type: string [0..1]
> > rel: string [0..1]
> > anchor: anyURI}
> >
> > Form class
> > { op: string [1..*]
> > href: anyURI
> > contentType: string
> > contentCoding: string [0..1]
> > subprotocol: string [0..1]
> > security: string [0..*]
> > scopes: string [0..*]}
> >
> > The contentCoding property feeds a response to the last class
> > ExpectedResource.
> >
> > ExpectedResource class
> > {contentType: string
> > response: 0..1 }
> >
> > //Figure 5 TD Serialization, TD and Thing on a light switch example
> >
> > The following figure can be described using an aria-describedby property
> -
> > as the paragraphs that follow it give a good overview of the contents of
> the
> > figure.
> >
> > <figure
> > id="fig-td-serialization-td-and-thing-on-a-light-switch-example"><img
> > src="images/model-theory-explainer.png">
> > <figcaption>Figure <bdi class="figno">5<!---0.037920%--></bdi> <span
> > class="fig-title"><a href="#dfn-td-serialization" class="internalDFN"
> > data-link-type="dfn">TD Serialization</a>, <a href="#dfn-td"
> > class="internalDFN" data-link-type="dfn">TD</a> and <a href="#dfn-thing"
> > class="internalDFN" data-link-type="dfn">Thing</a> on a light switch
> > example</span></figcaption>
> > </figure>
> >
> > NOTE: I suggest using the second paragraph (start shown below), is a good
> > description but as there is no ID associated with this <p> this will
> need to
> > be added to create a programmatic association between the figure and the
> > text that describes it.
> >
> > <p>An intelligent WoT client can be assigned the task of turning a light
> off
> > in ontological terms, using SAREF. [...]
> >
> > [...]
> >
> > </Thing Description Alternate Text>
> >
> > --
> > Emerging Web Technology Specialist/A11y (WAI/W3C)
> >
>
> --
>
> Janina Sajka
>
> Linux Foundation Fellow
> Executive Chair, Accessibility Workgroup:       http://a11y.org
>
> The World Wide Web Consortium (W3C), Web Accessibility Initiative (WAI)
> Chair, Accessible Platform Architectures        http://www.w3.org/wai/apa
>
>
>

-- 
*​John Foliot* | Principal Accessibility Strategist | W3C AC Representative
Deque Systems - Accessibility for Good
deque.com