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

+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
>
>
>