Skip to content

GC Semantic Web Implementation Guide

Jump to bottom
chrismajewski edited this page Sep 15, 2014 · 25 revisions

Introduction

This is an implementation guide for the W3C's "semantic web" attribute level extensions for the Government of Canada's Web Interoperability standard. This guide includes descriptions of core types, their key properties, type examples, general property standards and full page samples.

This document is written for implementers with an understanding of the Lite Resource Description Framework (RDFa Lite) and the schema.org vocabulary. Use examples directly from below. If you need a variation, modification, extension or less detail for your context, you should understand the proper syntax. You will also be required to follow all base design choices and property standards.

Examples in this document were validated and measured with the most modern tools available which are subject to change.

Base design choices

The interoperability and resiliancy of exposed data relies on a consistent implementation of the structure and the data used for key elements.

Explicit type definitions

Data types can be defined implicitly or explicitly. Implicit definitions do not specify type but instead rely on the Interpreter to infer intent. Without an in-depth understanding of what Interpreters will assume across all platforms unexpected consequences are inevitable.

To simplify the implementation and to encourage consistent results schema.org types are to be defined, as recommended, explicitly using the "typeof" attribute and proper nesting.

The following example demonstrates proper nesting. Each level's type is defined with "typeof".

	<span typeof="MatryoshkaDoll">
		<span typeof="name">Large Doll</span>

		<span typeof="MatryoshkaDoll">
			<span typeof="name">Medium Doll</span>

			<span typeof="MatryoshkaDoll">
				<span typeof="name">Small Doll</span>

				<span typeof="MatryoshkaDoll">
					<span typeof="name">Tiny Doll</span>
				</span>
			</span>
		</span>
	</span>

Strict key definitions

Key properties are the links between objects, the interoperability of exposed data relies on the existence and data consistency in those key fields. Authoritative sources and/or standards will be required for key fields to ensure consistency and maximize reliable linkages.

In the following example an Event defines three speakers which are linked to the three Person objects by matching email properties.

	<span typeof="Event">
		<span property="address" typeof="PostalAddress">...</span>

		<span property="performer" typeof="Person">
			<span property="givenName">John</span> <span property="additional">D</span> <span property="familyName">Doe</span>
			<meta property="email" content="John.Doe@parl.gc.ca" />	
		</span>

		<span property="performer" typeof="Person">
			<span property="givenName">Jane</span> <span property="additional">D</span> <span property="familyName">Doe</span>
			<meta property="email" content="Jane.Doe@parl.gc.ca" />	
		</span>

		<span property="performer" typeof="Person">
			<span property="givenName">Jim</span> <span property="additional">D</span> <span property="familyName">Doe</span>
			<meta property="email" content="Jim.Doe@parl.gc.ca" />	
		</span>
	</span>

	<p typeof="Person">
		<span property="givenName">John</span> <span property="additional">D</span> <span property="familyName">Doe</span>
		<span property="jobTitle">Manager</span>
	 
		<span property="location" typeof="Place">...</span>
		</span>

		<span property="telephone">(888) 123-4567</span>
		<a property="email" href="mailto:John.Doe@parl.gc.ca">John.Doe@parl.gc.ca</a>
	</p>

	<p typeof="Person">
		<span property="givenName">John</span> <span property="additional">D</span> <span property="familyName">Doe</span>
		<span property="jobTitle">Manager</span>
	 
		<span property="location" typeof="Place">
			<span property="address" typeof="PostalAddress">...</span>
		</span>

		<span property="telephone">(888) 123-4567</span>
		<a property="email" href="mailto:John.Doe@parl.gc.ca">John.Doe@parl.gc.ca</a>
	</p>

	<p typeof="Person">
		<span property="givenName">John</span> <span property="additional">D</span> <span property="familyName">Doe</span>
		<span property="jobTitle">Manager</span>
	 
		<span property="location" typeof="Place">...</span>

		<span property="telephone">(888) 123-4567</span>
		<a property="email" href="mailto:John.Doe@parl.gc.ca">John.Doe@parl.gc.ca</a>
	</p>

Implementation

Core types

WebPage [schema.org]

The WebPage type is intended to expose the core elements HTML pages as to uniquely identify it, the freshness(need a better word) of it's content and the top task(s) it applies to.

Sole properties and additional navigational element
  • breadcrumb
  • mainContentOfPage
  • name
  • dateModified
  • SiteNavigationElement
Template
	<!DOCTYPE html>
	<html>
		<head>
			<title>Title of the page</title>
		</head>
		<body vocab="http://schema.org/" typeof="WebPage">
			
			<span property="breadcrumb">
				breadcrumb
				<!-- breadcrumb elements -->
			</span>

			<main property="mainContentOfPage">
				<h1 property="name">Name of document</h1>

				mainContentOfPage
				<!-- main content -->
			</main>

			<nav typeof="SiteNavigationElement">
				Navigation 
				<!-- navigational elements -->
			</nav>

			Date modified: <time property="dateModified" datetime="2013-07-01T00:00:01+00:00">2013-07-01</time>

		</body>
	</html>

PostalAddress [schema.org]

The PostalAddress type is intended to encapsulate a postal address as defined by Canada Post.

Key properties

For street address:

OR

For post office box:

Examples

Street address:

	<span typeof="PostalAddress">
		<span property="streetAddress">240, Sparks Street</span>,
		<span property="addressLocality">Ottawa</span>, 
		<span property="addressRegion">ON</span>,
		<span property="addressCountry">CANADA</span>
		<span property="postalCode">K1A 0G6</span>
	</span>

Rural route:

	<span typeof="PostalAddress">
		<span property="streetAddress">RR 6 STN Main</span>,
		<span property="addressLocality">Millarville</span>, 
		<span property="addressRegion">AB</span>,
		<span property="addressCountry">CANADA</span>
		<span property="postalCode">T0L 1K0</span>
	</span>

Post office box:

	<span typeof="PostalAddress">
		<span property="postOfficeBoxNumber">PO BOX 4001 STN A</span>,
		<span property="addressLocality">Ottawa</span>, 
		<span property="addressRegion">ON</span>, 
		<span property="addressCountry">CANADA</span>
		<span property="postalCode">V8X 3X4</span>
	</span>

Person [schema.org]

The Person type is intended to describe an individual. It is extendable for biographies, relationships and additional properties as described by schema.org.

Key properties
Examples

Minimum contact:

	<p typeof="Person">
		<span property="name">John D. Doe</span>
	    <a property="email" href="mailto:John.Doe@parl.gc.ca">John.Doe@parl.gc.ca</a>
	</p>

General contact sheet:

	<p typeof="Person">
		<meta property="name" content="John D. Doe"/>

		<span property="givenName">John</span> <span property="additional">D</span> <span property="familyName">Doe</span>
		<span property="jobTitle">Manager</span>
	 
		<span property="location" typeof="Place">
			<span property="address" typeof="PostalAddress">
				<span property="streetAddress">240, Sparks Street</span>,
				<span property="addressLocality">Ottawa</span>, 
				<span property="addressRegion">ON</span>,
				<span property="addressCountry">CANADA</span>
				<span property="postalCode">K1A 0G6</span>
			</span>
		</span>

		<span property="telephone">(888) 123-4567</span><br>
		<a property="email" href="mailto:John.Doe@parl.gc.ca">John.Doe@parl.gc.ca</a>
	</p>

"Care Of" minimal where person specific email not available:

John Doe, Director Generals Office c/o
	<p typeof="Person">
		Health Canada - General Information
		<meta property="name" content="Deptartment-name Info / Info Nom-de-Deptartement">
		<a property="email" href="mailto:Info@dept-dept.ca">Info@dept-dept.ca</a>
	</p>

"Care Of" where person specific email not available:

John Doe, Director Generals Office c/o
	<p typeof="Person">
		Deptartment-name - General Information
		<meta property="name" content="Health Canada Info / Info Santé Canada">
		<span property="location" typeof="Place">
			<span property="address" typeof="PostalAddress">
				<span property="streetAddress">240, Sparks Street</span>,
				<span property="addressLocality">Ottawa</span>, 
				<span property="addressRegion">ON</span>,
				<span property="addressCountry">CANADA</span>
				<span property="postalCode">K1A 0G6</span>
			</span>
		</span>

		Toll-free ( Canada ): <span property="telephone">(866) 123-4567</span><br>
		Telephone :  <span property="telephone">(613) 123-4567</span><br>
		TTY: <span property="telephone">(800) 123-4567</span><br>
		<a property="email" href="mailto:Info@dept-dept.ca">Info@dept-dept.ca</a>
	</p>

Organization [schema.org]

The Organization type is intended to describe an organization and may be extended to describe architectures.

Key properties
Examples

Minimum organization description:

	<p typeof="Organization">
		<span property="legalName">Parliament of Canada - Parlement du Canada</span>
	</p>

Expanded organization description:

	<p typeof="Organization">
		<span property="legalName">Parliament of Canada - Parlement du Canada</span>
	 
		<span property="location" typeof="Place">
			<span property="address" typeof="PostalAddress">
				<span property="streetAddress">Parliament of Canada</span>,
				<span property="addressLocality">Ottawa</span>, 
				<span property="addressRegion">ON</span>,
				<span property="addressCountry">CANADA</span>
				<span property="postalCode">K1A 0A9</span>
			</span><br>

			Toll-free ( Canada ): <span property="telephone">(866) 599-4999</span><br>
			Telephone :  <span property="telephone">(613) 992-4793</span><br>
			TTY: <span property="telephone">(613) 995-2266</span><br>
			<a property="email" href="mailto:info@parl.gc.ca">info@parl.gc.ca</a>
		</span>

	</p>

Place [schema.org]

The Place type is intended to describe a place or venu. It is extendable to anything from a small office to a conference center with multiple simultanious events.

Key properties

OR

Examples

Minimum place address:

	<span typeof="Place">
		<span property="address" typeof="PostalAddress">
			<span property="streetAddress">Parliament of Canada</span>,
			<span property="addressLocality">Ottawa</span>, 
			<span property="addressRegion">ON</span>,
			<span property="addressCountry">CANADA</span>
			<span property="postalCode">K1A 0A9</span>
		</span>
	</span>

Minimum place GeoCoordinates:

	<span typeof="Place">
		<span property="geo" typeof="GeoCoordinates">
			Latitude:<span property="latitude">45.4249</span>
			Longitude:<span property="longitude">75.6999</span>
		</span>
	</span>

Extended place example:

	<span typeof="Place">
		<span property="address" typeof="PostalAddress">
			<span property="streetAddress">Parliament of Canada</span>,
			<span property="addressLocality">Ottawa</span>, 
			<span property="addressRegion">ON</span>,
			<span property="addressCountry">CANADA</span>
			<span property="postalCode">K1A 0A9</span>
		</span><br>

		Toll-free ( Canada ): <span property="telephone">(866) 599-4999</span><br>
		Telephone :  <span property="telephone">(613) 992-4793</span><br>
		TTY: <span property="telephone">(613) 995-2266</span><br>
		<a property="email" href="mailto:info@parl.gc.ca">info@parl.gc.ca</a>		
	</span>

Event [schema.org]

The Event type is intended to describe an evnet. It is extendable from meetings with attendees to large scale events with performers.

Key properties
Examples

Minimum Event example:

	<span typeof="Event">
		<span property="name">Citizenship Ceremony</span>
	    Location: 
	    <span property="location" typeof="Place">
	        <span property="description">Corner Brook, Newfoundland & Labrador City Hall</span><br>
	        <span property="address" typeof="PostalAddress">
	            <span property="streetAddress">5, Park Street</span>,<br>
	            <span property="addressLocality">Corner Brook</span>,<br>
	            <span property="addressRegion">Newfoundland and Labrador</span><br>
	        </span>
	    </span><br>

	    <time property="startDate" datetime="2012-12-07T15:00:00-04:00">
	        Date: 2013-06-07 EST<br>
	        Time: 3:00 p.m.<br>
	    </time>
	</span>

Event with duration:

	<span typeof="Event">
		<span property="name">Citizenship Ceremony</span>
	    Location: 
	    <span property="location" typeof="Place">
	        <span property="description">Corner Brook, Newfoundland & Labrador City Hall</span><br>
	        <span property="address" typeof="PostalAddress">
	            <span property="streetAddress">5, Park Street</span>,<br>
	            <span property="addressLocality">Corner Brook</span>,<br>
	            <span property="addressRegion">Newfoundland and Labrador</span><br>
	        </span>
	    </span><br>

	    <time property="startDate" datetime="2012-12-07T15:00:00-04:00">
	        Date: 2013-06-07 EST<br>
	        Time: 3:00 p.m.<br>
	    </time>

	    Duration:<time property="duration" datetime="PT3H00M">3h</time><br>
	</span>

DataSet [schema.org]

The DataSet type is intended to describe single pools of data. It's extendable to include encoding, intended audience, geospacial effect and much more.

Key properties
Examples

Minimum dataset:

	<span typeof="DataSet">

		<span property="publisher" typeof="Organization">
			<span property="legalName">Parliament of Canada - Parlement du Canada</span>
		</span>
		<span property="name">Mean visitors attendance by hour</span>
	</span>

Extended dataset to include date modified:

	<span typeof="DataSet">
		<span property="publisher" typeof="Organization">
			<span property="legalName">Parliament of Canada - Parlement du Canada</span>
		</span>
		<span property="name">Mean visitors attendance by hour</span>

		Date modified: <time property="dateModified" datetime="2013-07-01T00:00:01+00:00">2013-07-01 00:00:01</time>
	</span>

DataCatalog [schema.org]

The DataCatalogue type is intended to describe collections of DataSets.

Key Properties
Examples

Minimum example:

	<span typeof="DataCatalog">

		<span property="publisher" typeof="Organization">
			<span property="legalName">Parliament of Canada - Parlement du Canada</span>
		</span>
		<span property="name">Visitor data</span>

	</span>

Extended datacatalog to include datasets, contact information and a modification date:

	<span typeof="DataCatalog">

		<span property="publisher" typeof="Organization">
			<span property="legalName">Parliament of Canada - Parlement du Canada</span>
		</span>
		<span property="name">Visitor data</span>


		<span typeof="DataSet">

			<span property="publisher" typeof="Organization">
				<span property="legalName">Parliament of Canada - Parlement du Canada</span>
			</span>
			<span property="name">Mean visitors attendance by hour</span>

		</span>

		<span typeof="DataSet">

			<span property="publisher" typeof="Organization">
				<span property="legalName">Parliament of Canada - Parlement du Canada</span>
			</span>
			<span property="name">Average visitors attendance by hour</span>

		</span>

		<span typeof="DataSet">

			<span property="publisher" typeof="Organization">
				<span property="legalName">Parliament of Canada - Parlement du Canada</span>
			</span>
			<span property="name">Maximum visitors attendance by hour</span>

		</span>

		<span typeof="DataSet">

			<span property="publisher" typeof="Organization">
				<span property="legalName">Parliament of Canada - Parlement du Canada</span>
			</span>
			<span property="name">Minimum visitors attendance by hour</span>

		</span>

		Date modified: <time property="dateModified" datetime="2013-07-01T00:00:01+00:00">2013-07-01 00:00:01</time>

		Toll-free ( Canada ): <span property="telephone">(866) 599-4999</span><br>
		Telephone :  <span property="telephone">(613) 992-4793</span><br>
		TTY: <span property="telephone">(613) 995-2266</span><br>
		<a property="email" href="mailto:info@parl.gc.ca">info@parl.gc.ca</a>

	</span>

GeoCoordinates [schema.org]

The GeoCoordinates type is intended to describe a point on or above earth by decimal latitude, longitude and elevation.

Key Properties
Examples

Minimum example:

	<span typeof="GeoCoordinates">
		Latitude:<span property="latitude">45.4249</span>
		Longitude:<span property="longitude">75.6999</span>		
	</span>

GeoCoordinates expanded to include elevation

	<span typeof="Place">
		<span property="geo" typeof="GeoCoordinates">
			Latitude:<span property="latitude">43.6426</span>
			Longitude:<span property="longitude">-79.3871</span>
			Elevation:<span property="elevation">625.09m</span>
		</span>
	</span>

Key property interactions

Undefined as of yet

Property standards

Canada Post Addressing Guidelines

Canada Post International Desitination Listing

Authoritative email

It would be preferable to have a central authority defining the email address but the Government Electronic Directory Service ( GEDS ) does not consistently expose email.

Until an authoritative source exists, implementers should ensure any email addresses are fully qualified.

Authoritative legalName

Undefined

ISO8601 date, time or duration

Datetime

A Treasury Board mandated ISO8601 date time such as 2012-12-07T15:00:00-04:00 representing December 7th 2012 at 15:00:00 with a time zone definition of -4 GMT ( EST ). If the timezone is not specified, assume it's local time.

Date

A Treasury Board mandated ISO8601 date such as 2012-12-07 representing December 7th 2012.

Time

A Treasury Board mandated ISO8601 time such as 15:00:00-04:00 representing 15:00:00 with a time zone definition of -4 GMT ( EST ). If the timezone is not specified, assume it's local time.

Duration

A Treasury Board mandated (ISO8601 duration)(http://en.wikipedia.org/wiki/ISO_8601#Durations) such as PT3H30M which describes 3 hours and 30 minutes.

Date time policies

Latitude, Longitude and Elevation

Latutude and Longitude are to be described, were possible, as decimal values.

Till there is clarification on elevation standards the unit is to be added in as data adjacent to the numerical value 1234m or 1.2km.

Full page samples

Implementation rolling out, examples will follow as WET advances.

  • TBS WIWG - HTML Data core implemented in WET 4.0
  • TBS MEWG T2 - Developing strategy for standards, potential replacement for Dublin Core

Tools

Code validator

Data visibility

Known issues

  • Care Of examples would be better described as Organization if organization had a contact point

Notes

  • A simplified document has been requested, is planed for end of November 2013
  • Version 1.0 requires a translation

Version

References

Clone this wiki locally