Glossary Sample Resource Design

Introduction

Glossary resources are used to document established terminology, define terms, and collect terms into groups (known as glossaries). Because of the importance of glossaries across the application lifecycle, the elements defined in this document in support of glossaries are part of the Open Services for Lifecycle Collaboration namespace.

Referenced Namespaces:

  • http://example.org/xmlns/alm/v0.1/ - The Open Services for Lifecycle Collaboration Namespace (default -- unless otherwise specified, the elements and attributes defined in this specification are from this namespace).
  • http://purl.org/dc/elements/1.1/ - The "simple" Dublin Core Metadata Element Set Version 1.1

Summary of Resources:

  • Glossary Term - Identifies and defines a word or phrase intended to express a particular concept.
  • Glossary - Identifies and describes a collection of terms, usually relating to a specific subject.
  • Glossary-Term Link - Indicates that a specified term is considered part of specified glossary.

Resource Descriptions

Glossary Term

The glossary term resource contains the term name and one or more definitions for the term.

Example

&lt?xml version="1.0" encoding="utf-8"?> 
<term
        xmlns:jzalm="http://example.org/xmlns/alm/v0.1/"
        xmlns:dc="http://purl.org/dc/elements/1.1/"
        jzalm:abbreviation="ALM">
        <dc:title>Application Lifecycle Management</title>
        <jzalm:definition xml:lang="en_US">

             Management of the lifecycle of the application artifacts.
        </jzalm:definition>
        <jzalm:synonym alt="SDLC" href="http://example.org/glosary-term-1" />
</term>

XML Representation of Glossary Term Resource

XML Representation Summary: termElement
<term
  abbreviation = xsd:anystring
  >
  Content: (title+, (definition | synonym | relatedTerm)* )
</term>
Property Representation
{dc:title} The required string name of the term. This element may contain an xml:lang attribute to indicate the language of the definition; this allows a term to have definitions in multiple languages. The same term may have multiple name entries to indicate, for example, alternative spellings or names for the same term in multiple languages.
{abbreviation} The optional string giving the common abbreviation for the term.
{definition} The optional definition of the term. The value of the description must be suitable for use as the inside of an XHTML body. This element may contain an xml:lang attribute to indicate the language of the definition; this allows a term to have definitions in multiple languages. By making this element optional, it is possible for applications to identify glossary terms for which definitions are yet to be provided.
{synonym} The optional link to another term considered synonymous with the current term.
{relatedTerm} The optional link to another term related to the current term.

The synonym and relatedTerm elements have the same structure, containing an href attribute whose value is the URI of the synonym or related term.

XML Representation Summary: synonym and relatedTerm Elements
<(synonym | relatedTerm)   href = xsd:anyURI />
Property Representation
{href} The required URI of the synonym or related term.

Glossary

The glossary simply names and describes a collection of terms. Note that it describes the collection, not the terms themselves. In fact, it does not even contain links to the terms themselves; those are managed in the term-link resource, described later.

Example

<glossary
     xmlns:jzalm="http://example.org/xmlns/alm/v0.1/"
     xmlns:dc="http://purl.org/dc/elements/1.1">

     <dc:title>My Software Development Glossary</dc:title>

     <dc:description>All of the terms I like for the SDLC</dc:description>

     <jzalm:terms href="http://example.org/myglossary/terms" />
</glossary>

XML Representation of Glossary Resource

XML Representation Summary: glossaryElement
<glossary
  >
  Content: (terms, dc:title+, dc:description* )
</glossary>
Property Representation
{terms} The required link to the ATOM collection managing the collection of terms included in this glossary. The URI of the terms collection is stored in this element's required href attribute.
{dc:title} The required string title of the glossary.
{dc:desription} The optional description of the glossary. The value of the description must be suitable for use as the inside of an XHTML body.

Glossary Term-Link Resource

The link between a glossary and its terms are maintained in an ATOM collection. Therefore, the Term-Link Resource is simply an ATOM entry, where the atom:entry element's href attribute is the URL of the glossary term. Terms are added to a glossary by POSTing a Term-Link Resrouce to the collection's URI. Terms are removed from a glossary by DELETEing the corresponding entry; a GET on the ATOM Collection is sufficient for the client to obtain the list of terms in a glossary.

Design Rationale

With these three resource types, you can see that we are representing glossaries in a very fine-grained manner. This granularization supports several important use-cases:

  • Term re-use: Terms can easily be included in multiple glossaries through the creation of additional Glossary-Term Link resources.
  • Contained permissions models: Assuming an underlying permissions model that allows permissions to be controlled at the individual resource level, this granularization gives us some flexibility. Permission to alter a term's definition (i.e. to update a term resource) is not needed in order to include a term in a glossary; neither is permission to add terms to or remove them from a glossary needed to update the description of a glossary. In fact, permissions around updating glossary descriptions, term definitions, and the inclusion of terms into glossaries can easily be controlled independently.
  • Contained revision models: Inclusion of a term in a glossary does not imply creation of a new version of the term.

While other groupings of the glossary and term are possible, none have all three of these highly desirable characteristics. One could consider including all of the term links within the glossary itself. However, with very large glossaries, this would become unwieldy: clients would be forced to GET the entire glossary at a time. The design advocated in this sample document separates the concepts of term, glossary, and link into their own resource, and allows us to leverage ATOM (as described above) to manage the term-glossary link.