Added a draft design for 'speakable' sections of a page.

See #1389
schemaorg · Oct 5, 2016 · a0fadde · a0fadde
1 parent e3f5e00
commit a0fadde
Show file tree

Hide file tree

Showing 2 changed files with 109 additions and 0 deletions.
diff --git a/data/ext/pending/issue-1389-examples.txt b/data/ext/pending/issue-1389-examples.txt
@@ -0,0 +1,52 @@
+TYPES: speakable, cssSelector, SpeakableSpecification
+
+PRE-MARKUP:
+
+An example of 'speakable' markup (JSON-LD only, initially).
+
+MICRODATA:
+
+TODO
+
+RDFA:
+
+TODO
+
+JSON:
+
+{
+ "@context": "http://schema.org/",
+ "@type": "WebPage",
+ "name": "Jane Doe's homepage",
+ "speakable":
+ {
+  "@type": "SpeakableSpecification",
+  "cssSelector": ["headline", "summary"]
+  },
+ "url": "http://www.janedoe.com"
+ }
+
+
+ TYPES: speakable
+
+ PRE-MARKUP:
+
+ An example of 'speakable' markup (JSON-LD only, initially).
+
+ MICRODATA:
+
+ TODO
+
+ RDFA:
+
+ TODO
+
+ JSON:
+
+ {
+  "@context": "http://schema.org/",
+  "@type": "WebPage",
+  "name": "Jane Doe's homepage",
+  "speakable": [ "#myhead1", "#thesummary"],
+  "url": "http://www.janedoe.com"
+  }
diff --git a/data/ext/pending/issue-1389.rdfa b/data/ext/pending/issue-1389.rdfa
@@ -0,0 +1,57 @@
+<div>
+
+  <div typeof="rdf:Property" resource="http://schema.org/speakable">
+    <span>Category: <span property="schema:category">issue-1389</span></span>
+    <span class="h" property="rdfs:label">speakable</span>
+    <span property="rdfs:comment">Indicates sections of a Web page that are particularly 'speakable' in the sense of being highlighted as being especially appropriate for text-to-speech conversion. Other sections of a page may also be usefully spoken in particular circumstances; the 'speakable' property serves to indicate the parts most likely to be generally useful for speech.
+
+The *speakable* property can be repeated an arbitrary number of times, with three kinds of possible 'content-locator' values:
+
+1.) *id-value* URL references - uses *id-value* of an element in the page being annotated. The simplest use of *speakable* has (potentially relative) URL values, referencing identified sections of the document concerned.
+
+2.) CSS Selectors - addresses content in the annotated page, eg. via class attribute. Use the [[cssSelector]] property.
+
+3.)  XPaths - addresses content via XPaths (assuming an XML view of the content). Use the [[xpath]] property.
+
+
+For more sophisticated markup of speakable sections beyond simple ID references, either CSS selectors or XPath expressions to pick out document section(s) as speakable. For this
+we define a supporting type, [[SpeakableSpecification]]  which is defined to be a possible value of the *speakable* property.
+    </span>
+    <span>domainIncludes: <a property="http://schema.org/domainIncludes" href="http://schema.org/WebPage">WebPage</a></span>
+    <span>rangeIncludes: <a property="http://schema.org/rangeIncludes" href="http://schema.org/SpeakableSpecification">SpeakableSpecification</a></span>
+    <span>rangeIncludes: <a property="http://schema.org/rangeIncludes" href="http://schema.org/URL">URL</a></span>
+    <link property="http://schema.org/isPartOf" href="http://pending.schema.org" />
+    <span>Source:  <a property="dc:source" href="https://github.com/schemaorg/schemaorg/issues/1389">#1389</a></span>
+  </div>
+
+  <div typeof="rdfs:Class" resource="http://schema.org/SpeakableSpecification">
+    <span>Category: <span property="schema:category">issue-1389</span></span>
+    <span class="h" property="rdfs:label">SpeakableSpecification</span>
+    <span>Subclass of: <a property="rdfs:subClassOf" href="http://schema.org/Intangible">Intangible</a></span>
+    <span property="rdfs:comment">A SpeakableSpecification indicates (typically via [[xpath]] or [[cssSelector]]) sections of a document that are highlighted as particularly [[speakable]]. Instances of this type are expected to be used primarily as values of the [[speakable]] property.</span>
+    <link property="http://schema.org/isPartOf" href="http://pending.schema.org" />
+    <span>Source:  <a property="dc:source" href="https://github.com/schemaorg/schemaorg/issues/1389">#1389</a></span>
+  </div>
+
+  <div typeof="rdf:Property" resource="http://schema.org/cssSelector">
+    <span>Category: <span property="schema:category">issue-1389</span></span>
+    <span class="h" property="rdfs:label">cssSelector</span>
+    <span property="rdfs:comment">A CSS selector.</span>
+    <span>domainIncludes: <a property="http://schema.org/domainIncludes" href="http://schema.org/SpeakableSpecification">SpeakableSpecification</a></span>
+    <span>rangeIncludes: <a property="http://schema.org/rangeIncludes" href="http://schema.org/Text">Text</a></span>
+    <link property="http://schema.org/isPartOf" href="http://pending.schema.org" />
+    <span>Source:  <a property="dc:source" href="https://github.com/schemaorg/schemaorg/issues/1389">#1389</a></span>
+  </div>
+
+  <div typeof="rdf:Property" resource="http://schema.org/xpath">
+    <span>Category: <span property="schema:category">issue-1389</span></span>
+    <span class="h" property="rdfs:label">xpath</span>
+    <span property="rdfs:comment">An XPath.</span>
+    <span>domainIncludes: <a property="http://schema.org/domainIncludes" href="http://schema.org/SpeakableSpecification">SpeakableSpecification</a></span>
+    <span>rangeIncludes: <a property="http://schema.org/rangeIncludes" href="http://schema.org/Text">Text</a></span>
+    <link property="http://schema.org/isPartOf" href="http://pending.schema.org" />
+    <span>Source:  <a property="dc:source" href="https://github.com/schemaorg/schemaorg/issues/1389">#1389</a></span>
+  </div>
+
+
+</div>