Re: @alt descriptions for Thing Descriptions

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

Received on Friday, 14 June 2019 16:21:15 UTC