WebSchemas/PropertyValuePairs

From W3C Wiki


This is an archived WebSchemas proposal for Property-Value Pairs in Schema.org for schema.org. See Proposals listing for more. Note: active schema.org development is now based at github



Outcome: Published as PropertyValue

http://schema.org/PropertyValue was added in release 2.0 in 2015, see http://schema.org/docs/releases.html

Proposal for Property-Value Pairs

Status: Prepared by Martin Hepp, mheppATcomputerDOTorg

Overview

This proposal defines a lightweight, generic pattern for exposing arbitrary property value pairs to schema.org. Such is often needed for exposing

  • product features,
  • EXIF image meta-data, and
  • additional features of places.

In the future, it could also serve as a generic extension mechanism for properties. The proposal mirrors a feature that will be added to the GoodRelations vocabulary for e-commerce information, which has already been added to schema.org.

Motivating Examples

Many Web sites contain additional, granular information about characteristics of the entities described in the respective pages that cannot be directly mapped to schema.org properties. In some cases, we can simply define additional properties for the respective schema.org types, but in many other cases, this is unfeasible. For instance, the eCl@ss standard defines more than 16,000 precise product properties for commodities. It is not possible nor desirable to add 16,000 properties to http://schema.org/Product nor to create tens of thousands of subclasses of http://schema.org/Product.

Respective information is frequently rendered tabular form, but the underlying data structure is that of a property-value pair, often augmented by unit of measurement information, and sometimes characterized by value references.

It would be very valuable to be able to expose as much of such property-value-type information, in particular for product features, by a respective lightweight mechanism in schema.org.

We all agree in here that standards for product types and properties and values are easier to process and in general better. However, the development and use of such standards is orthogonal to the proposed extension.

In a nutshell, the extension allows sites to expose product feature data if any of the following condition is met:

  1. There is no standardized property for the product characteristic (e.g. number of birds per cuckoo clock).
  2. There is no URI / Web vocabulary for the standardized property (as is the case for eClass properties, UNSPSC classes, and was to my knowledge for GPC).
  3. The site is not able to add the URI of the property to the data (e.g. because the back-end systems just provide property-value pairs to the Web application).
  4. The data available to the site is not sufficiently granular or incomplete and thus insufficient for populating the target data structure as specified in the product ontology (e.g. the ontology defines a product weight including batteries and the site data is weight excluding batteries).

With the proposed extension, sites can publish a wealth or product data even in such cases, which are very, very common.

Manufacturers of Commodities and Retailers

Most product detail pages of e-commerce sites, like BestBuy.com, and most product detail pages of manufacturers of products, like cars, consumer electronics, etc. contain a "Specifications" tab or section that lists quantitative and quantitative product features.
Examples:

iPhone 5 Specifications
Spec Value Description
LTE Band and Mode 4G LTE
Battery Type lithium-ion
Built-In GPS Yes
Touch Screen Yes
Operating System Apple iOS 7
Screen Size 4" Size of the screen, in inches, measured diagonally from corner to corner.
Bluetooth Version 4.0
Keyboard Type Virtual QWERTY
Front Facing Camera MP Rating 1.2
Rear Facing Camera MP Rating 8

Remarks:

  1. The total number of properties is potentially huge.
  2. Often, there is no global standard that precisely defines how the value of the property is measured.
  3. Even if there are such standards (like eCl@ss), many site owners are unable to map all of their local properties and values to such a standard.

EXIF Image Meta-data

Another area of application for this proposal is picture meta-data from the Exchangeable Image File Format (EXIF) and other meta-data formats for creative works (PDF of version 2.3 of the EXIF Standard). EXIF and proprietary extensions allow digital cameras and other devices to capture a lot of valuable meta-data about images that could be valuable for a Web site to expose. While some of the properties defined in EXIF can be mapped to existing or future properties defined in schema.org, there is a general need for a loosely-coupled mechanism for such meta-data, because

  1. the number of EXIF properties properties is large in comparison to the properties of http://schema.org/ImageObject,
  2. the current exifData property causes a loss of structural information about the property-values,
  3. the EXIF standard can evolve independently from schema.org and will thus create a constant need for alignment, and
  4. there are domain- or vendor-specific extensions of EXIF.

This has also been discussed on the public-vocabs mailing list on September 22/23, 2014.

Current Coding Practices

Current Web page markup typically uses simple lists, tables, or nested div structures for representing property-value information. 

<h5>Size and Weight</h5>
<ul>
<li>Desktop Form Factor</li>
<li>Width: 5.9 in (150.3 mm)</li>
<li>Height: 7.3 in (185.4 mm)</li>
<li>Depth: 10.3 in (262.3 mm)</li>
<li>Weight: 8.5 lb (3.9 kg) without hard drives, power supply, or packaging</li>
</ul>
<h5>Power and Cooling</h5>
<ul>
<li>External Power Supply:
<ul>
<li>AC Input – 100-240VAC~2A, 50-60Hz</li>
<li>DC Output – 12V, 12.5A, 150W max</li>
</ul>
</li>
<li>Dual, fixed, variable speed cooling fans</li>
</ul>

There is hope that the the property name, the unit information and the value, and the contextual information either come from multiple variables in the original templates, e.g. that the line 

<li>Width: 5.9 in</li>

actually comes from a template pattern like 

<li>{{property}}: {{value}} {{unit}}</li>

or that sites would be able to use local patterns to split the whole string into these components using regular expression assumed they have a reason to do so.

At least the split between property name and value is frequently already materialized at the level of HTML, e.g. by emphasizing the property name using <strong> or <span>. 

<ul>
<li><strong>Type: </strong> 3-speed, fully manual operation </li>
<li><strong>Motor: </strong> DC motor </li>
<li><strong>Drive Method Direct Drive: </strong> Direct drive </li>
<li><strong>Speeds: </strong> 33-1/3 RPM, 45 RPM, 78 RPM</li> 
</ul>

Design Principles

  1. Keep Data Structure and Semantics: Allow site owners to expose as much granularity and data semantics as locally available.
    • Example: If the back-end database holds value and unit code in two fields, the extension should allow to preserve that granularity.
    • Example: If the back-end database uses standard codes, like UN/CEFACT Common Codes, for units, it should be possible to publish those.
  2. No Lifting and Cleansing Barrier: Do not force site owners to lift or cleanse existing data.
    • Example: If the source data is not able to map a local property definition to a global standard, do not force them to. It is better to allow site owners to publish what they have than to create barriers.

Requirements

  • Support for
    • quantitative (e.g. "number of USB ports: 5") i.e. schema:QuantitativeValue,
    • qualitative (e.g. "type of interface: USB"), and
    • boolean values ("USB interface: yes")
  • Support for point values (e.g. "diameter: 5 cm") and ranges (e.g. "input voltage: 3 - 9 volts").
  • Support for units of measurement information, in one of the following forms:
    • natural language / text / unit symbol (e.g. volts or V)
    • standard unit codes, like UN/CEFACT Common Codes, from multiple standards (e.g. "VLT" for volts from UN/CEFACT or )
    • URIs for a unit of measurement, like http://qudt.org/vocab/unit#Volt
    • Custom Enumerations (e.g. "Cellular type: GSM / EDGE / 3G / HSPA / LTE") i.e. schema:Enumeration
  • Be able to preserve contextual information and conditions (e.g. "measured at 20 degrees Celsius", "at 8 Ohm", ...)

Extension Proposal

Git Repository

The specification of the proposal is available via the 'property-value-and-cars' branch of the following Git repository:

Note 1: The Git repository combines the specification for this proposal with the vehicles/automotive extension proposal due to the inherent dependencies.
Note 2: All older repositories like https://github.com/mfhepp/sdo-property-value and https://bitbucket.org/mfhepp/property-value-pairs-for-schema.org are no longer valid and have been closed or deleted to avoid confusion.

Live Demo on Appengine

Changes to Existing Elements

Extend domain / range of

Also, the textual description of these elements will be expanded to include the additional usages of the elements.

New Elements

New Class

New Properties

Notes:

Issues: I have thought long about the name for additionalProperty. For pure product features, "feature" would be a better keyword, but the application area of this proposal reaches further. "property" is catchy, but since we already have the class http://schema.org/Property, this is a potential cause of errors. Also, the new mechanism is not at the same level as the core schema.org meta-model. A nice aspect of additionalProperty is that is complements the existing additionalType keyword.

Relationship to http://schema.org/PropertyValueSpecification

The existing element http://schema.org/PropertyValueSpecification is a mechanism for specifying input and output constraints for potential actions (for background information, see the final proposal).

There is no conflict with the proposed generic property-value mechanism.

Markup Examples

ImageObject: EXIF Meta-data

Without Mark-up

<h2>Beach in Mexico</h2>
<img src="mexico-beach.jpg" />
By Jane Doe
Photographed in Puerto Vallarta, Mexico
Date uploaded: Jan 25, 2008
I took this picture while on vacation last year.
<!-- We assume the following EXIF meta-data is available, but currently not shown:

Exposure Time:    1/659 sec.
FNumber:          f/4.0
MaxApertureValue: 2.00
Metering Mode:    Pattern
Flash:            Flash did not fire.
-->

Microdata

<div itemscope itemtype="http://schema.org/ImageObject">
  <h2 itemprop="name">Beach in Mexico</h2>
  <img src="mexico-beach.jpg" itemprop="contentUrl" />
  By <span itemprop="author">Jane Doe</span>
  Photographed in
    <span itemprop="contentLocation">Puerto Vallarta, Mexico</span>
  Date uploaded:
    <meta itemprop="datePublished" content="2008-01-25">Jan 25, 2008
  <span itemprop="description">I took this picture while on vacation last year.</span>
<!-- Note: We do not split value strings in unit and value information, since this the raw EXIF data 
does not provide this granularity. If you are able to separate the unit, you can use the unitText property -->
  <div itemprop="exifData" itemscope itemtype="http://schema.org/PropertyValue">
      <meta itemprop="name" content="Exposure Time">
	  <meta itemprop="value" content="1/659 sec.">
  </div>
  <div itemprop="exifData" itemscope itemtype="http://schema.org/PropertyValue">
      <meta itemprop="name" content="FNumber">
	  <meta itemprop="value" content="f/4.0">
  </div>
  <div itemprop="exifData" itemscope itemtype="http://schema.org/PropertyValue">
      <meta itemprop="name" content="MaxApertureValue">
	  <meta itemprop="value" content="2.00">
  </div>   
  <div itemprop="exifData" itemscope itemtype="http://schema.org/PropertyValue">
      <meta itemprop="name" content="Metering Mode">
	  <meta itemprop="value" content="Pattern">
  </div>
  <div itemprop="exifData" itemscope itemtype="http://schema.org/PropertyValue">
      <meta itemprop="name" content="Flash">
	  <meta itemprop="value" content="Flash did not fire.">
  </div>
</div>

RDFa

<div vocab="http://schema.org/" typeof="ImageObject">
  <h2 property="name">Beach in Mexico</h2>
  <img src="mexico-beach.jpg" property="contentUrl" />
  By <span property="author">Jane Doe</span>
  Photographed in
    <span property="contentLocation">Puerto Vallarta, Mexico</span>
  Date uploaded:
    <meta property="datePublished" content="2008-01-25">Jan 25, 2008
  <span property="description">I took this picture while on vacation last year.</span>
<!-- Note: We do not split value strings in unit and value information, since this the raw EXIF data 
does not provide this granularity. If you are able to separate the unit, you can use the unitText property -->
  <div property="exifData" typeOf="PropertyValue">
      <meta property="name" content="Exposure Time">
	  <meta property="value" content="1/659 sec.">
  </div>
  <div property="exifData" typeOf="PropertyValue">
      <meta property="name" content="FNumber">
	  <meta property="value" content="f/4.0">
  </div>
  <div property="exifData" typeOf="PropertyValue">
      <meta property="name" content="MaxApertureValue">
	  <meta property="value" content="2.00">
  </div>   
  <div property="exifData" typeOf="PropertyValue">
      <meta property="name" content="Metering Mode">
	  <meta property="value" content="Pattern">
  </div>
  <div property="exifData" typeOf="PropertyValue">
      <meta property="name" content="Flash">
	  <meta property="value" content="Flash did not fire.">
  </div>  
</div>

JSON-LD

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "ImageObject",
  "author": "Jane Doe",
  "contentLocation": "Puerto Vallarta, Mexico",
  "contentUrl": "mexico-beach.jpg",
  "datePublished": "2008-01-25",
  "description": "I took this picture while on vacation last year.",
  "name": "Beach in Mexico"
  "exifData": {
    "@type": "PropertyValue",
    "name": "Exposure Time",
	"value": "1/659 sec."
  }
  "exifData": {
    "@type": "PropertyValue",
    "name": "FNumber",
	"value": "f/4.0"
  }
  "exifData": {
    "@type": "PropertyValue",
    "name": "MaxApertureValue",
	"value": "2.00"
  }
  "exifData": {
    "@type": "PropertyValue",
    "name": "Metering Mode",
	"value": "Pattern"
  }
  "exifData": {
    "@type": "PropertyValue",
    "name": "Flash",
	"value": "Flash did not fire."
  }    
}
</script>

Product: Point Value, with unit as text

<div itemscope itemtype="http://schema.org/Product">
  <img itemprop="image" src="camera123.jpg" />
  <span itemprop="name">Digital Camera 123</span>
  <div itemprop="additionalProperty" itemscope itemtype="http://schema.org/PropertyValue">
	  <span itemprop="name">Approx. Weight</span>
	  <span itemprop="value">450</span>
	  <span itemprop="unitText">gram</span>
  </div>  
</div>

Point Value, with unit as symbol

<div itemscope itemtype="http://schema.org/Product">
  <img itemprop="image" src="camera123.jpg" />
  <span itemprop="name">Digital Camera 123</span>
  <div itemprop="additionalProperty" itemscope itemtype="http://schema.org/PropertyValue">
	  <span itemprop="name">Approx. Weight</span>
	  <span itemprop="value">450</span>
	  <span itemprop="unitText">g</span>
  </div>  
</div>

Point Value, with unit as UN/CEFACT Common Code

<div itemtype="http://schema.org/Product">
  <img itemprop="image" src="camera123.jpg" />
  <span itemprop="name">Digital Camera 123</span>
  <div itemprop="additionalProperty" itemscope itemtype="http://schema.org/PropertyValue">
	  <span itemprop="name">Approx. Weight</span>
	  <span itemprop="value">450</span>
	  <meta itemprop="unitCode" content="GRM">g
  </div>  
</div>

Range, with unit as UN/CEFACT Common Code

<div itemscope itemtype="http://schema.org/Product">
  <img itemprop="image" src="camera123.jpg" />
  <span itemprop="name">Digital Camera 123</span>
  <div itemprop="additionalProperty" itemscope itemtype="http://schema.org/PropertyValue">
	  <span itemprop="name">Operating Voltage</span>
	  <span itemprop="minValue">100</span>-
	  <span itemprop="maxValue">250</span>
	  <meta itemprop="unitCode" content="VLT">volts
  </div>  
</div>


Open Interval, with unit as UN/CEFACT Common Code

<div itemtype="http://schema.org/Product">
  <img itemprop="image" src="camera123.jpg" />
  <span itemprop="name">Digital Camera 123</span>
  <div itemprop="additionalProperty" itemscope itemtype="http://schema.org/PropertyValue">
	  <span itemprop="name">Wifi range</span>: up to 
	  <span itemprop="maxValue">30</span> 
<!-- Note: The UN/CEFACT Common Code for foot is FOT --> 
	  <meta itemprop="unitCode" content="FOT">ft.
  </div>  
</div>

Multiple Intervals

<div itemtype="http://schema.org/Product">
  <img itemprop="image" src="camera123.jpg" />
  <span itemprop="name">Digital Camera 123</span>
  <div itemprop="additionalProperty" itemscope itemtype="http://schema.org/PropertyValue">
	  <span itemprop="name">Operating voltage</span>: 
	  <span itemprop="value">9-12</span> or
	  <span itemprop="value">100-250</span>
	  <meta itemprop="unitCode" content="VLT">volts
  </div>  
</div>

Range and Enumerated Values

<div itemscope itemtype="http://schema.org/Product">
  <img itemprop="image" src="camera123.jpg" />
  <span itemprop="name">Digital Camera 123</span>
  <div itemprop="additionalProperty" itemscope itemtype="http://schema.org/PropertyValue">
	  <span itemprop="name">ISO Sensitivity</span>: 
	  <span itemprop="value">100-6400</span>/
	  <span itemprop="value">12,800</span> (Hi-1)
	  <span itemprop="unitText">ISO</span>
  </div>  
</div>

Boolean Value

<div itemscope itemtype="http://schema.org/Product">
  <img itemprop="image" src="camera123.jpg" />
  <span itemprop="name">Digital Camera 123</span>
  <div itemprop="additionalProperty" itemscope itemtype="http://schema.org/PropertyValue">
	  <span itemprop="name">USB interface</span>:
	  <meta itemprop="value" content="True">Yes
  </div>  
</div>

Qualitative Value

<div itemscope itemtype="http://schema.org/Product">
  <img itemprop="image" src="camera123.jpg" />
  <span itemprop="name">Digital Camera 123</span>
  <div itemprop="additionalProperty" itemscope itemtype="http://schema.org/PropertyValue">
	  <span itemprop="name">Interface</span>:
	  <span itemprop="value">USB</span>
  </div>  
</div>

Qualitative Value (multiple)

<div itemscope itemtype="http://schema.org/Product">
  <img itemprop="image" src="camera123.jpg" />
  <span itemprop="name">Digital Camera 123</span>
  <div itemprop="additionalProperty" itemscope itemtype="http://schema.org/PropertyValue">
	  <span itemprop="name">Interfaces</span>:
	  <span itemprop="value">USB</span>, 
	  <span itemprop="value">Ethernet</span>
  </div>  
</div>

Notes:

  1. The value property should be used multiple times only for qualitative values, not for quantitative ones.
  2. If the site is unable to represent the individual values of a list of values as distinct HTML elements (e.g. span or div), one can also use delimiters like commas or slashes in the content:
<div itemprop="additionalProperty" itemscope itemtype="http://schema.org/PropertyValue">
	  <span itemprop="name">Interfaces</span>:
	  <span itemprop="value">USB, Ethernet</span>
</div>

Property ID for clarifying the meaning of a property: URI from external vocabulary

<div itemscope itemtype="http://schema.org/Car">
  <img itemprop="image" src="station_waggon123.jpg" />
  <span itemprop="name">Station Waggon 123</span>
  <div itemprop="additionalProperty" itemscope itemtype="http://schema.org/PropertyValue">
	  <span itemprop="name">Luggage Capacity (seats folded)</span>:
	  <span itemprop="value">500</span>
	  <meta itemprop="unitCode" content="LTR">liter
	  <link itemprop="propertyID" href="http://purl.org/vvo/ns#luggageCapacitySeatsFolded" />
  </div>  
</div>

Property ID for clarifying the meaning of a property: Code from eCl@ss Standard

<!-- The Property code 02-AAM226 is for "USB interface present" in eCl@ss 8.1 -->
<div itemscope itemtype="http://schema.org/Product">
  <img itemprop="image" src="camera123.jpg" />
  <span itemprop="name">Digital Camera 123</span>
  <div itemprop="additionalProperty" itemscope itemtype="http://schema.org/PropertyValue">
	  <span itemprop="name">USB Interface</span>:
	  <meta itemprop="value" content="True">Yes
	  <meta itemprop="propertyID" content="eclass81:02-AAM226">
  </div>  
</div>

Ratios

<div itemscope itemtype="http://schema.org/Car">
  <img itemprop="image" src="station_waggon123.jpg" />
  <span itemprop="name">Station Waggon 123</span>
  <div itemprop="additionalProperty" itemscope itemtype="http://schema.org/PropertyValue">
	  <span itemprop="name">Fuel consumption</span>:
	  <span itemprop="value">5</span>
	  <meta itemprop="unitCode" content="LTR">liter /
  	  <div itemprop="valueReference" itemscope itemtype="http://schema.org/PropertyValue">
	  	<span itemprop="value">100</span>
	        <span itemprop="unitText">km</span>
	  </div>
  </div>  
</div>

Value References

<div itemscope itemtype="http://schema.org/Product">
  <img itemprop="image" src="camera123.jpg" />
  <span itemprop="name">Digital Camera 123</span>
  <div itemprop="additionalProperty" itemscope itemtype="http://schema.org/PropertyValue">
	  <span itemprop="name">Operating Voltage</span>
	  <span itemprop="minValue">100</span>-
	  <span itemprop="maxValue">250</span>
	  <meta itemprop="unitCode" content="VLT">volts
	  at
  	  <div itemprop="valueReference" itemscope itemtype="http://schema.org/PropertyValue">
	     <span itemprop="value">50</span>
	     <span itemprop="unitText">Hz</span>
          </div>   
  </div>  
</div>

Multi-dimensional Values

Note: The domain of the value property has been changed to include PropertyValue recursively. This allows preserving the structure of multi-dimensional values (like 50 mm x 75 mm). 

<div itemscope itemtype="http://schema.org/Product">
  <img itemprop="image" src="camera123.jpg" />
  <span itemprop="name">Digital Camera 123</span>
  <div itemprop="additionalProperty" itemscope itemtype="http://schema.org/PropertyValue">
	  <span itemprop="name">Sensor Size</span>
	  <div itemprop="value" itemscope itemtype="http://schema.org/PropertyValue">
  	  	<span itemprop="value">23.2</span>
  	  	<span itemprop="unitText">mm</span>  
	  </div> x
	  <div itemprop="value" itemscope itemtype="http://schema.org/PropertyValue">
  	  	<span itemprop="value">15.4</span>
  	  	<span itemprop="unitText">mm</span>  
	  </div>
  </div>  
</div>

Grouping and Hierarchical Order of Properties

Note: A nice example of this in real Web pages is http://www.samsung.com/ae/consumer/tv-audio-video/dvd/dvd-player/DVD-D530/ZN-spec. 

<div itemscope itemtype="http://schema.org/Product">
  <img itemprop="image" src="camera123.jpg" />
  <span itemprop="name">Digital Camera 123</span>
  <div itemprop="additionalProperty" itemscope itemtype="http://schema.org/PropertyValue">
	  <strong itemprop="name">Focus/Autofocus</strong>
	  <div itemprop="value" itemscope itemtype="http://schema.org/PropertyValue">
		<span itemprop="name">Picture Control</span> 
  	  	<span itemprop="value">Landscape</span>
		<span itemprop="value">Monochrome</span>
		<span itemprop="value">Portrait</span>
	  </div>
	  <div itemprop="value" itemscope itemtype="http://schema.org/PropertyValue">
		<span itemprop="name">Single-point AF Mode</span>:
  	  	<meta itemprop="value" content="True">Yes
	  </div>	  
  </div>  
</div>

Comments and Feedback

Please post to the public-vocabs@w3.org mailing list.

Issues

  • Naming:
    • Maybe rename PropertyValue to NamedValue? (MH: Unconvinced)
    • Maybe rename additionalProperty to feature (MH: Unconvinced because it limits a future broader use without need)
  • Maybe define a new property schema:propertyName instead of reusing schema:name Kept the original
  • The naming of additionalProperty should be discussed. (some positive feedback already for keeping additionalProperty) Kept the original
  • One could extend the range of value to include PropertyValue itself, which would allow modeling properties that have multi-dimensional values. Implemented
  • Multiple qualitative values could be handled either via delimiters in the value or by allowing multiple values for the value property (MH: I am inclined to the latter). Implemented
  • Maybe allow value references (MH: I would allow that). Implemented
  • Maybe allow hierarchical structures / grouping of properties. Implemented
Retrieved from "https://www.w3.org/wiki/index.php?title=WebSchemas/PropertyValuePairs&oldid=98040"