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

+1

On Wed, Jun 19, 2019 at 2:15 PM Katie Haritos-Shea <ryladog@gmail.com>
wrote:

> +1
>
> On Tue, Jun 18, 2019, 7:31 PM Janina Sajka (janina@rednote.net) <
> janina@rednote.net> wrote:
>
>> 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
>>
>>
>>

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