Documentation

About the Schema

The Open Educational Resource Schema, or OER Schema for short, is a Resource Description Framework (RDF) vocabulary which extends schema.org, Creative Commons and Dublin Core vocabularies. Our goal is to unify OER content on the web to a standard vocabulary in effort to enhance its discoverability in public and private indexes and allow content to be more easily remixed and re-purposed.

What is a Schema?

In short, a schema is just metadata, or information about information. While computers are great at processing and calculating great amounts of information, they lack contextual understanding innate to human beings. A schema, in our case an RDF vocabulary, allows developers to apply human concepts to marked-up information, typically using HTML, so that software applications can determine the context of the information and contextual relationships pieces of content have with one another. A schema ensures a common understanding about the information being processed.

How do I use the OER Schema?

Ideally, an Instructional Designer or Faculty Member won't have to worry about implementing the schema; rather, they should petition the content delivery platforms they use to implement this schema for them. However, if you are skilled in HTML or are a developer looking to implement this schema, you can follow along with some examples below.

Understanding Schema Relationships

Before we get into the meat and potatoes of how to implement the schema, it helps to understand how it is organized and how things relate to one another. After all, a good reason to use the schema is to build relationships between the parts of your content.

Looking at the schema page, you'll notice the a list of items, some nested deeper than others. These items are called types and the structured format they are listed in represents a hierarchical tree. At the top of this tree is the first type, named a Resource. Resource is the parent of all the types indented below it. Each child in the tree extends its parent, meaning it gains all of the properties of the parent and its parent's parents. A child can also be used in cases when its parent type is specified.

Types

Often times a type is thought of as an object or a noun. A type says what something is. When you apply a type to a section of content, you're saying that the content is of that type. In the case of the OER Schema, you could specify that something is a Course.

Properties

If a type is a noun, a property would be an adjective in that properties describe the type. Looking at Course, you'll notice a list of properties, some for the Course type itself and other inherited from the Resource type as well as external vocabulary types from schema.org.

A property is associated with one or more types and has a value and the value, itself, has a type. In the properties table for Course, there is an "Expected Type" column, which denotes the expected type for the value of the property. Sometimes this type is simply Text or Number, i.e. "Some Text" or "1", and other times the expected type is another type in the schema, like LearningComponent. In the case of LearningComponent, the value could be LearningComponent or any of its child types such as LearningObjective or Lesson.

Applying the Schema

In the following examples, we will use RDFa Lite 1.1 to apply the schema to HTML 5 markup. There are a number of ways to apply an RDF vocabulary to HTML. Some alternatives to RDFa Lite is HTML+RDFa 1.1 and Microdata. Whichever way you prefer is completely up to you.

RDFa Lite 1.1

RDFa is an acronym for Resource Document Framework in attributes. RDFa allows us to apply RDF vocabularies to HTML using attributes on HTML 5 tags. Which tags? Any tags. The attributes used in RDFa can be applied to any tag used to markup content, though more commonly <span> and <div> tags are used.

The following attributes are used to apply RDFa to HTML:

vocab=""

The vocab attribute specified the root URL of the vocabulary you would like to apply. The vocabulary is applied to the element itself and all child elements. For this reason, the vocab attribute is commonly applied to the <body> tag.

<!-- http://example.com/my-course.html -->
<body vocab="http://oerschema.org">
<!-- ... -->
</body>

typeof=""

The typeof attribute allows you to specify which type you want to apply to the element.

<!-- http://example.com/my-course.html -->
<body vocab="http://oerschema.org">
    <div typeof="Course">
        <h2>My Course</h2>
        <p>A description of my course.</p>
        <!-- ... -->
    </div>
</body>

property=""

The property attribute is used to specify which property to use for the associated type. The property attribute is placed on a child element whose parent makes use of the typeof attribte. The property attribute's value is the name of property to use. The property name must be a valid property name associated with the type referenced in the parent element's typeof attribute.

<!-- http://example.com/my-course.html -->
<body vocab="http://oerschema.org">
    <div typeof="Course">
        <h2 property="courseIdentifier">My Course</h2>
        <p property="description">A description of my course.</p>
        <img src="/path/to/my/image.jpg" property="http://schema.org/image">
        <!-- ... -->
    </div>
</body>

In the example above, we've create an object using the type Course located in the http://oerschema.org/ vocabulary. We've described the Course object using the courseIdentifier and description properties. The values of these properties is the content of their respective elements. So courseIdentifier's value is My Course and description's value is A description of my course.

Take notice of the <img> element. The value of the property attribute is a URL to a property found in schema.org. Since Course is a child of Resource which also extends http://schema.org/Thing, all of the properties of http://schema.org/Thing can also be used on Course, but since they exist in a different vocabulary, you have to provide the full URL path of the property. In this case, the value of the http://schema.org/image property is actually the value of the src parameter, /path/to/my/image.jpg. Later, you'll see how to use prefixes with the vocab attribute to make it easier to use multiple libraries.

resource=""

So far, we've created a Course object and applied some attributes to it. But how do we reference this object? Enter the resource attribute. Without the resource attribute, you must use the full URL of the HTML page as a reference, but this makes this complicated when there are multiple objects on a page and they need to reference one another.

What do I mean by reference? I mean create a relationship. The resource attribute allows an object to have be identified for use as a value of a property. Let's see an example:

<!-- http://example.com/my-course.html -->
<body vocab="http://oerschema.org">
    <div typeof="Course" resource="#my-course">
        <h2 property="courseIdentifier">My Course</h2>
        <p property="description">A description of my course.</p>
        <img src="/path/to/my/image.jpg" property="http://schema.org/image">
        <!-- ... -->
    </div>
</body>

First, notice the # prefix on the resource name. Essentially, the resource is the unique URL of the object. On the web, the URL gets you to the page, but a page anchor, which starts with the prefix #, takes you to the element on the page. So by prefixing our resource name with #, we're just saying that this is the element on the page with this ID.

Next, we need to put it to good use. In the following example, you'll see how the resource attribute and its value play a role with mapping a schema object as a value of a property in another object on the same page.

<!-- http://example.com/my-course.html -->
<body vocab="http://oerschema.org">
    <div typeof="Course" resource="#my-course">
        <h2 property="courseIdentifier">My Course</h2>
        <p property="description">A description of my course.</p>
        <img src="/path/to/my/image.jpg" property="http://schema.org/image">
        <!-- ... -->
        <link property="primaryInstructor" href="#instructor">
    </div>
    <div typeof="Person" resource="#instructor">
        <h2 property="name">Dr. Bob Jones</h2>
        <p property="description">An instructor at a university somewhere.</p>
    </div>
</body>

Now we've created another object, Person, as a sibling to Course. We want relate the Person as the primaryInstructor of the Course. In order to do so, we make use of the <link> tag. The <link> tag doesn't render any output to the page. Just like a <meta> tag, it's only for use as metadata on the page. More specifically, for the linking of resource.

In the example above, the <link> element is a child of the Course element and has the property attribute with a value of primaryInstructor. The href attribute on the <link> element is the URL of the resource to be used as the value of the primaryInstructor property on the Course object. Since they are on the same page, only the value of the resource attribute on the Person element is required to link the Person resource to the Course resource.

Let's pretend that this instructor, Dr. Jones, is teaching another course and also puts his course online. He could reference the Person object, #instructor, from the http://example.com/my-course.html my course page:

<!-- http://example.com/my-other-course.html -->
<body vocab="http://oerschema.org">
    <div typeof="Course" resource="#my-course">
        <h2 property="courseIdentifier">My Other Course</h2>
        <!-- ... -->
        <link property="primaryInstructor" href="http://example.com/my-course.html#instructor">
    </div>
</body>

Alternatively, he may want to use an <a> tag in place of the <link> tag. This will render a link on the page that students can see and click on.

<!-- http://example.com/my-other-course.html -->
<body vocab="http://oerschema.org">
    <div typeof="Course" resource="#my-course">
        <h2 property="courseIdentifier">My Other Course</h2>
        <!-- ... -->
        <a property="primaryInstructor" href="http://example.com/my-course.html#instructor">Instructor Bio</a>
    </div>
</body>

With respect to OER content, you may have an introduction page to your course, a syllabus page, multiple lesson or module pages and different supporting materials. Using the resource attribute with <link> and <a> elements to link resources together contextually helps to connect content pieces into a larger "sum of parts" that becomes a complete resource.

There may also be times when you want to apply metadata to content without having it render on the page, but the value is just basic text. The <meta> tag is very useful for this.

<!-- http://example.com/my-other-course.html -->
<body vocab="http://oerschema.org">
    <div typeof="Course" resource="#my-course">
        <h2 property="courseIdentifier">My Other Course</h2>
        <meta property="duration" content="3 Weeks">
        <!-- ... -->
        <link property="primaryInstructor" href="http://example.com/my-course.html#instructor">
    </div>
</body>

prefix=""

The prefix attribute allows multiple vocabularies to work together without collision. You may use the vocab to declare a primary vocabulary and prefix to include new vocabs with a namespace prefix. Just like vocab, prefix uses the base URL of the vocabulary, the difference is that the URL is prefixed with a namespace identifier and a ':'. The example below revises the example from the property attribute above:

<!-- http://example.com/my-course.html -->
<body vocab="http://oerschema.org" prefix="schema:http://schema.org/">
    <div typeof="Course">
        <h2 property="courseIdentifier">My Course</h2>
        <p property="description">A description of my course.</p>
        <img src="/path/to/my/image.jpg" property="schema:image">
        <!-- ... -->
    </div>
</body>

See how the URL, http://schema.org, is prefixed with schema: and the property value on the <img> element has the http://schema.org/ prefix replaced with the namespace prefix schema:?

Adding multiple prefixes is as easy as separating them with a space.

<!-- http://example.com/my-course.html -->
<body vocab="http://oerschema.org" prefix="schema:http://schema.org/ cc:http://creativecommons.org/ns dc:http://purl.org/dc/terms/">
    <!-- ... -->
</body>

Though a namespace prefix can be anything as long as it's unique to other vocabularies used along with it, there is a set of common name prefixes. It is recommended you stick to them.

The OER Schema is not yet on the above list, though we hope to rectify that soon. We prefer to use the prefix "oer:" when applicable.

Development and Requests

In the future, there will be documentation on how developers can contribute to the schema. For right now, you may fork us on GitHub and create a pull request at your own risk.

Non-developers and developers, alike, may make requests for changes and additions in the issue queue in our GitHub repository.