Note: This is not the latest SHOE specification.

SHOE 0.9

Latest version of this document: http://www.cs.umd.edu/projects/plus/SHOE/spec.html

Table Of Contents

1. Introduction: What this specification is all about.
2. Terms: Explanatory ideas behind the specification.
3. Declaring Ontologies: How to create an ontology for later use.
4. Marking Up HTML Documents Using Ontologies: How to use created ontologies in existing HTML documents.

This specification describes an extension to HTML which provides a way to semantically describe important information about HTML or other World-Wide-Web documents. Currently, there is no effective way to do this, making it difficult for user-agents or search index robots to understand exactly what a document is, why it's there, and its relationships with other documents. In particular, this specification describes:

• A hierarchical classification mechanism for HTML documents and optionally non-HTML documents or subsections of HTML documents.
• A mechanism for specifying relationships between classified elements and other classified elements or specific kinds of data (numbers, dates, etc.)
• An simple way to define ontologies containing rules about the above.

The intent of this specification is to make it possible for user-agents, robots, etc., to gather truly meaningful information about web pages and documents, enabling significantly better search mechanisms and knowledge-gathering.

The general way one goes about this is as follows:

• First, define an ontology describing valid classifications of web objects, and valid relationships between web objects and other web objects or data. This ontology may borrow from other ontologies.
• Annotate HTML pages to describe themselves, other pages, or subsections of themselves, as having attributes as described in one or more ontologies.

We're playing a bit fast-and-loose with the term "ontology" here. In this specification, "ontology" simply means an ISA hierarchy of classes/categories, plus a set of atomic relations between these categories. Categories inherit relations defined for parent categories. This specification does not as yet define any other forms of relationships (transitive closures, inverses, negations, etc.).

User agents following this specification should be aware that assertions made by HTML pages are not facts, but claims. I.e., if element x claims that element y is related with relation r to element z, then the user-agent should not be entering r(y,z) into its database (i.e., "Now I know that y is related to z with the relationship r!!"). Instead, it should be entering something along the lines of r(x,y,z) into its database (i.e., "x is claiming that y is related to z with relationship r."). This is an important distinction: it's perfectly fine for HTML pages out there to be making completely false claims; one shouldn't simply accept them as truth. For similar reasons, HTML pages can only make assertions, not retractions.

2 Terms

Category

An element under which HTML page instances or subinstances can be classified. Category names are element names, and may be prefixed. Categories may have parent categories (with ISA links). Categories define inheritance: if an instance is classified under a category, it is eligible to be in the domain or range of relations defined for that category or any of its parent (or ancestor) categories.

Data

Data which can be placed in the domain or range of a relationship but is not an instance. Data must be of the following types:

Strings (STRING type keyword)

HTML String Literals, as defined in the HTML specification.

Numbers (NUMBER type keyword)

Numerical constants of the form (approximately) [+|-]digit*['.'digit*][[e|E [+|-|]digit*]]. I.e., numbers like "2", "2.0", "-1.42350123e+4", etc.

Dates (DATE type keyword)

Syntax currently undefined.

Booleans (TRUTH type keyword)

HTML String Literals of the form "YES" or "NO", case-sensitive.

Categories (CATEGORY type keyword)

Category names.

Relationships (RELATION type keyword)

Relation names.

Element

A category or relationship name, or one of the following reserved keywords (all caps): STRING, NUMBER, DATE, TRUTH, CATEGORY, or RELATION. Element names are case-sensitive, and may contain only letters, digits, or hyphens.

Instance

An element which may be classified under zero or more categories, and included in the domain or range of relationships (along with other forms of data). Some instances ("Page Instances") are associated with World-Wide-Web documents, and more typically, HTML documents. Other instances ("subinstances") are associated with subsections of HTML page instance documents. Instances form the most common data entities in databases built up from this specification.

Key

A string which uniquely defines an HTML Page Instance or a subinstance. Determining a key (and hence the instance in question) is sometimes difficult. Documents which do not or cannot follow this spec do not have unique keys. Therefore, the unique key of such a document is defined to be an absolute URL of the document. Unfortunately, there may be several absolute URLs for a document, so a single URL is not a unique key. This cannot be helped.

It is up to you to decide on the keys for your documents. The accepted method for creating a unique key is to base the key on a single URL for the document. For example, the document located at http://www.cs.umd.edu/ may have a unique key of "http://www.cs.umd.edu/", or perhaps of "http://mimsy.cs.umd.edu/", or perhaps "http://www.cs.umd.edu:80".

Each subinstance must have a key unique to themselves and different from all subinstances and documents in the World Wide Web, including that of their parent page instance (their parent document). To determine keys for subinstances, you may add to an absolute URL (of the subinstance's HTML document) a suffix such as "#key1" or "#subinstance-1", etc. This is also an acceptible method for assigning keys to Page Instances if there is some worry that a Page Instance's key may conflict with a key of a completely different instance previously located at the same URL.

Ontology

As defined in this specification, a description of valid classifications for HTML page instances and subinstances, and a description of valid relationships between such instances and other instances, or with specific types of data (strings, numbers, dates, boolean values, categories, or relationships).

Prefix

A small string attached at the beginning of an element, separated with a period ("."). Prefixes may also be attached to already-prefixed elements, forming a prefix chain. A prefix indicates the ontology from which the element (or prefixed element) following it is defined.

Relation (Relationship)

An element which defines a relationship between two other elements. Relation names are element names, and may be prefixed. Relations may be between two instances, or between an instance and data, or (improperly) between two data elements. In this specification, all relations are binary relations. Relations have a domain (the element the relation is "from") and a range (the element the relation is "to").

Rule

A formal rule in an ontology defining valid classifications (categories) or valid relationships that can be asserted.

Unique Name

A string which uniquely defines an ontology. Unique Names are different from Keys in that they do not uniquely define instances but rather the ontologies which the instances may use. Further, several different versions of an ontology may have the same unique name so long as they have different Version numbers.

Version (Version Number)

A string which describes the version of an ontology. Versions are case-sensitive, and may contain only letters, digits, or hyphens.

Before an HTML document can be marked up with classifications and relationships, it must have one or more available ontologies from which to draw these classifications and relationships. This chapter describes the HTML tags which allow one to create such an ontology.

This chapter contains:

1. Defining An Ontology: Creating and ending an ontology.
2. Adding Ontology Declarations: Describing what classifications and relationships are valid in your ontology.

An HTML document may contain any number of ontology definitions. Each definition provides a unique name and version number for the ontology, which together must be unique from all other ontology definitions that do not describe the exact same ontology as this (i.e., that aren't the same ontology).

This section contains:

1. Declaring An Ontology Definition: Creating your ontology.
2. Extending An Existing Ontology: How to avoid re-inventing the wheel.

Ontology definitions must contain a unique name different from all other ontology definitions that aren't exactly the same. Further, ontology definitions should be accompanied with a version which distinguishes the definition from previous versions of the definition. If the ontology completely subsumes certain previous versions (it contains all the rules defined in those versions), it may declare itself to be backward-compatible with those versions. To begin an ontology definition, use:

      <ONTOLOGY "ontology-unique-name"
          	VERSION="Version"
          	BACKWARD-COMPATIBLE-WITH="Version List">

"ontology-unique-name" (mandatory)

The ontology's unique name.

VERSION (mandatory)

The ontology's version.

BACKWARD-COMPATIBLE-WITH

A whitespace-delimited list of previous versions which this ontology subsumes.

To end an ontology definition, use (after all rules and extensions for the ontology):

      </ONTOLOGY>

An ontology may be declared to extend one or more existing ontologies. This means that it will use elements in those ontologies in its own rules. To distinguish between those elements and its own elements, an ontology must provide a unique prefix for each ontology it extends, which will be prefixed to elements borrowed from each particular ontology whenever they are referred to. To declare that this ontology is extending another ontology, use:

      <ONTOLOGY-EXTENDS "ontology-unique-name"
            VERSION="Version"
            BACKWARD-COMPATIBLE-WITH="Version List"
            [URL="URL"]>

"ontology-unique-name" (mandatory)

The extended ontology's unique name, as given in the ontology itself (that is, in its own HTML document).

VERSION (mandatory)

The extended ontology's version, as given in the ontology itself (that is, in its own HTML document).

PREFIX (mandatory)

The prefix you are assigning the extended ontology. All categories and relations from this ontology which are used in this document must be prefixed with this prefix. With respects to this document prefix must be different than all prefixes declared with either <USE-ONTOLOGY ...> or <ONTOLOGY-EXTENDS ...> tags.

URL

A URL that points to a document (preferably the official document) which contains the extended ontology.

Once an ontology is defined, we must populate it with valid classification and relationship rules.

This section contains:

1. Declaring Classification Rules: Defining what instances may be classified as.
2. Declaring Relationship Rules: Defining how instances may create relationships with each other and with data.
3. Renaming Rules: How to rename classification and relationship rules to get rid of prefixes.

Inside an ontology definition, an ontology may declare various new categories which instances can belong to. Categories should be subcategories (ISA) of one or more parent category. To declare a new category, or to add new parent categories for a category, use:

      <ONTDEF CATEGORY="category-name"
            [ISA="parent-category-list"]>

CATEGORY (mandatory)

The newly declared category or the category which is being given more parent categories.

ISA

A whitespace-delimited list of categories to define as parent categories of this category. Short for "is a".

Inside an ontology definition, an ontology may declare various new valid relationships between category instances or between category instances and data. To declare a relationship, use:

      <ONTDEF RELATION="relation-name"
            ARGS="element-list">

RELATION (mandatory)

The newly declared relationship name.

ARGS (mandatory)

The arguments of the relation. This should be a whitespace-delimited list of exactly two elements (this specification currently supports only binary relations). The first element defines the domain of the relationship, and the second element defines the range of the relationship. Elements can be either declared categories, or the following keywords representing various kinds of data elements (all caps):

STRING

Strings.

NUMBER

Numbers.

DATE

Dates and timestamps.

TRUTH

Boolean values (truths) of the form "YES" or "NO".

CATEGORY

Category names. This establishes a relationship not with category instances but with a categories themselves.

RELATION

Relationships. This establishes a relationship not with instances but with other relationships.

The last two elements are rare and should only be used in special circumstances.

To reduce the number of prefixes, an ontology is permitted to rename a category or relation reference to another name, so long as this name is not used in any other reference in the ontology. For example, an ontology could rename the category "cs.junk.person" (i.e., a category "person" declared in an ontology extended [with the prefix "junk"] by an ontology which is extended [with the prefix "cs"] by our ontology document) to simply "person", so long as "person" is not defined elswhere in the ontology to mean something else.

Ontologies are not permitted to rename (or rename elements to) the following keywords: STRING, NUMBER, DATE, TRUTH, CATEGORY, or RELATION. To rename an element, use:

      <ONTDEF RENAME="element-name"
            TO="new-element-name">

RENAME (mandatory)

The element's old name.

TO (mandatory)

The element's new name.

Any HTML document can be marked up, using existing ontologies, to declare itself or subparts of itself as belonging to certain categories, being associated with data, or having explicit relationships with other documents.

This chapter contains:

1. Instantiation: Declaring that the document uses the specification.
2. Using an Ontology: Declaring that the document uses one or more ontologies while classifying or declaring relationships.
3. Classification: Using an ontology and declaring categories for a document.
4. Declaring Relationships: Declaring relationships between the document and other data or documents.

HTML documents which follow this spec must declare themselves "page" instances and provide a unique key for themselves. Additionally, these documents may declare subsections of themselves as "sub-instances", each with a unique key.

This section contains:

1. Declaring A Page Instance: Indicating that a HTML document uses this specification.
2. Declaring A Subinstance: Declaring that a subsection of the HTML document has unique characteristics of its own.

A page instance is an HTML document that is marked up using this specification. Each page instance must have a unique key. By default, all instances are automatically of the category Page. To declare the document to be a page instance, you must add the following text to the HEAD section of the HTML document:

      <META HTTP-EQUIV="Instance-Key" CONTENT="Key">

Replace "Key" with the page instance's unique key.

To be conformant with this specification, a document must include this declaration.

Additionally, a page instance may provide a short (typically one-line) description of itself in human-readable form; this may be useful for the owners of user-agents trying to understand what the page instance really means. To declare this description, use:

      <META HTTP-EQUIV="Instance-Description" CONTENT="Description">

Replace "Description" with the page instance's description.

4.1.2 Declaring a Subinstance

A subinstance is a section of an HTML document that has been declared to be an instance of one or more instance categories, apart from those declared for the document (page instance) itself.

By default, all subinstances are of the category PageSubinstance, and automatically have the parentPage relationship linking them to their parent page instance. Subinstances should not be nested--that is, a subinstance should not be declared inside another subinstance. To declare the start of a subinstance, use the INSTANCE tag:

      <INSTANCE "Key" [DESC="Description"] [URL="URL"]>

"Key" (mandatory)

The unique key for the instance.

DESC

A string describing the instance in human-readable form; this will be useful for people trying to understand what your instances really mean.

URL

May tell user-agents exactly what URL to use to display this subinstance. Subinstances are best accompanied with an anchor tag of the form <A ... NAME=...>, where the NAME, where the URL would lead a prospective user-agent directly to this particular anchor.

To mark the end of the section of the document which this subinstance covers, use:

      </INSTANCE>

This section contains:

1. Declaring Ontology Usage: Indicating that you intende to use a specific ontology in your markup.

      <USE-ONTOLOGY "ontology-unique-name"
          	VERSION="Version"
          	PREFIX="Prefix"
	  	[URL="URL"]>

"ontology-unique-name" (mandatory)

The ontology's unique name, as given in the ontology itself (that is, in its own HTML document).

VERSION (mandatory)

The ontology's version, as given in the ontology itself (that is, in its own HTML document).

PREFIX (mandatory)

The prefix you are assigning the ontology. All categories and relations from this ontology which are used in this document must be prefixed with this prefix. With respects to this document prefix must be different than all prefixes declared with either <USE-ONTOLOGY ...> or <ONTOLOGY-EXTENDS ...> tags.

URL

A URL that points to a document (preferably the official document) which contains this ontology.

This section contains:

1. Declaring Categories: Classifying an instance with a category.

An instance may declare itself or another instance to belong to one or more categories, using the CATEGORY tag:

      <CATEGORY "prefixed.category.list" 
		[FOR="Key"]
		[URL="URL"]>

"prefixed.category.list" (mandatory)

A whitespace-delimited list of categories, each prefixed by the appropriate ontology from which it was derived. This is the list of categories the instance is declared to belong to.

FOR

Contains the key of the instance which is being declared to belong to these categories.

URL

Provides a URL where the instance in FOR may be found.

FOR is not mandatory. Therefore, to determine the key of the instance which will belong to these categories, follow the following rules:

• If neither FOR nor URL are declared, then the key is assumed to be that of the enclosing subinstance, or (if there is no enclosing subinstance) the page instance.
• If FOR is declared but not URL, then FOR provides the key. Declaring FOR but not URL is acceptable only if the key is for an instance declared in the same document.
• If URL is declared but not FOR, and the document the URL references does not or cannot conform to this specification, then the key value must be assumed to be an absolute version of the URL tag itself.
• If URL is declared but not FOR, and the document URL references does conform to this specification, then the key value is the page instance of the document the URL references.
• If both FOR and URL are declared, then FOR provides the key, and URL points to a document which contains the instance belonging to FOR's key.

This section contains:

1. Explicitly Declaring Relationships: The default mechanism for declaring relationships.
2. Marking Up Text Relationships: Wrapping relationships around body text.
3. Marking Up Link Relationships (unofficial): Embedding relationships in link tags.

      <RELATION "prefixed.relationship.list" 
            [FROM="Key"]
            [FROM-URL="URL"]		
            [FROM-TYPE="Type"]
            [FROM-CATEGORY="prefixed.category.list"]
            [TO="Key"]
            [URL="URL"]		
            [TYPE="Type"]
            [CATEGORY="prefixed.category.list"]>

It's possible to wrap existing HTML text and declare it to be a relationship. This is done by:

      <ATTRIBUTE "prefixed.relationship.list"
            [TYPE="Type"]> 	
      Attribute Text
      </ATTRIBUTE>

This is functionally the same as declaring

      <RELATION "prefixed.relationship.list" 
            TO="Attribute Text"
            [TYPE="Type"]>

TYPE declares the type of the enclosed text. If no TYPE is provided, it is assumed to be STRING. Note this is different from RELATIONs, where the TYPE is assumed by default to be INSTANCE; this is because typical data wrapped in an ATTRIBUTE will commonly be strings (people's names, terms, etc.).

In fact, because instance key names cannot be uniquely wrapped as text, the only valid TYPEs for ATTRIBUTE-wrapped text are "STRING", "NUMBER", "TRUTH", "DATE", "CATEGORY", and "RELATION".

4.4.3 Marking Up Link Relationships (unofficial)

This mechanism allows one to embed explicit relationships in tags with URL references like <LINK ...>, <A HREF= ...>, <IMG SRC= ...>, or <APPLET ...>. The full list of tags is undetermined. Further, adding subtags to existing tags is bad style, so this mechanism remains unofficial.

Some tags, like <LINK ...> and <A HREF= ...>, already the provide pseudo-relationship markers REL and REV. However, these markers are intended primarily for flat semantic information with no capability for classification. Further, this specification has little control over future semantic changes of these tags. Therefore, this specification uses its own distinct subtags RELATION and REVERSE.

The full embeddable subtag form is:

      <...     
            [RELATION="prefixed.forward.relationship.list"]
            [REVERSE="prefixed.reverse.relationship.list"]
            [CATEGORY="prefixed.category.list"]
            [TYPE="Type"]
            [KEY="Key"]
      >

Let "URL" be the URL provided in the particular link tag (for the <A ...> tag, it'd be the URL given in the HREF subtag, for example). Then the previous subtags are functionally the same as the following two declarations together:

      <RELATION "prefixed.forward.relationship.list" 
            [TO="Key"]
            [URL="URL"]		
            [TYPE="Type"]
            [CATEGORY="prefixed.category.list"]>

      <RELATION "prefixed.reverse.relationship.list" 
            [FROM="Key"]
            [FROM-URL="URL"]		
            [FROM-TYPE="Type"]
            [FROM-CATEGORY="prefixed.category.list"]>

Web Accessibility