48-Hour Call for Consensus (CfC): WoT Thing Description CR Comments

Colleagues:

This is a Call for Consensus (CfC) to the Accessible Platforms Working
Group (APA) on draft comments to the Web of Things Working Group on
their Thing Description specification currently in Candidate
Recommendation (CR) status available here:

https://w3c.github.io/wot-thing-description/


***Draft Comment***

Dear Colleagues:

The Accessible Platform Architectures (APA) Working Group has review
your Thing Description specification and provides the following comment
and proposed actions on this document.

1.)	We have no substantive issues with specification itself.

2.)	We have two comments on the presentation of this document as
currently marked up which we request be edited before advancing further.

	a.)	All else being equal we would prefer SVG diagrams
	because it is possible now to make some SVG diagrams directly
	accessible to users of assistive technologies. We are simply
	noting this possibility at the moment while we review the
	viability of formally requesting a change to accessible SVG.
	Please rest assured we will not ask for this change if we're
	unable to help make this change happen to the satisfaction of
	both our WGs.

	b.)	The several diagrams in this document are lacking
	textual descriptions which makes it difficult for certain print
	disabled readers to understand data flow as you've diagramed.
	Again, we are proposing to work with you both on appropriate
	markup and on appropriate text for these descriptions.

	Here begins our current recommendation:


<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: We suggest using the second paragraph (start shown below), as 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>

This ends our suggested edits. Thank you for your consideration and
prompt response to our request.

Janina Sajka, Chair
Accessible Platform Architectures (APA Working Group
W3C Web Accessibility Initiative (WAI)

***Action to Take***

This CfC is now open for objection, comment, as well as statements of
support via email. Silence will be interpreted as support, though
messages of support are certainly welcome.

If you object to this proposed action, or have comments concerning this
proposal, please respond by replying on list to this message no later
than 23:59 (Midnight) Boston Time, Sunday 23 June.

NOTE: This Call for Consensus is being conducted in accordance with the
APA Decision Policy published at:

http://www.w3.org/WAI/APA/decision-policy

Thanks especially to Josh O'Connor for the hard work of creating the
suggested descriptions.

Janina

-- 

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


-- 

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

Received on Tuesday, 18 June 2019 23:31:02 UTC