Tag Archives: K12OCX

K12 Open Content Exchange⤴

from @ Sharing and learning

I’ve been intending to write about the K12 Open Content Exchange project, and its metadata, but for various reasons haven’t got round to it. As I have just submitted a use case to the DCMI Application Profile Interest Group based on the projects requirements I’ll post that.

The project is being run by Learning Tapestry in the US, I am contracted to build the metadata specification in an iterative fashion based on experiences of content exchange between the partners (currently we are at iteration 1). I want to stress that this isn’t an authoritative description of all the project’s intents and purposes, or even all the metadata requirements, it’s a use case based on them, but I hope it gives a flavour of the work. The requirements section is more relevant if you’re interested in how to specify application profiles than for the OCX spec per se.

Problem statement

We wish to share relatively large amounts of content and curriculum materials relating to educational courses, for example: all the activities, student learning resources, teacher and parent curriculum guides, formative assessments, etc relating to one school-year of study in a subject such as mathematics.

We wish for the metadata to facilitate the editing, adaptation and reuse of the resources. For example teachers should be able to substitute resources/activities provided with other resources addressing the same objective as they see fit. Or course designers should be able pull out all the resources of a particular type (say activity plans), about a given topic, or addressing a specific learning outcome and use them in a new course. In some cases alternate equivalent content may be provided, for example online Vs offline content or to provide accessible provision for people with disabilities.

We wish for these to be discoverable on the open web at both broad and fine levels of granularity, i.e. whole courses and the individual parts should be discoverable via search engines.

We have decided to use the following vocabularies to describe the structure and content of the material: schema.org + LRMI, OERSchema and local extensions where necessary.

Stakeholders

  • Original content providers who create and publish curriculum and course materials using existing systems and already have (local) terminology for many aspects of resource description.
  • Content processors take the original content and offer it through their own systems. They also have (different) terminology for many aspects of resource description
  • Content purchasers wish to discover and buy content that meets their requirements
  • Course designers and Teachers use the content that has been purchased and wish to adapt it for their students
  • Parents wish to understand what and how their students are being taught
  • Learners want a seamless experience using high quality materials and ideas, in which all the work above is invisible.

Requirements

The application profile must reference evolving specifications: schema.org, OERSchema, various controlled vocabularies/concept schemes/encoding schemes and local extensions. If a local extension is adopted by one of the more widely recognised specifications it should be easy to modify the application profile to reflect this.

The application profile must include a content model that meets the following requirements for describing the structure of content:

  • identify the distinct types of entity involved (Course, Unit, Lesson, Supporting Material, Audience, Learning Objectives, Assessments etc)
  • show the hierarchy of the content (i.e. the Course comprises Units, the Units comprise Lessons, the Lessons comprise Activities)
  • show related content that is not part of the hierarchy but is related to (e.g. information about Units for teachers and parents, content to be used in the Activities)
  • show the ordering of sequential content
  • show options for alternative equivalent content

The application profile must specify optional (may), desired (should) and required (must) descriptive metadata as appropriate for each type of entity. For example

  • Activities must have a learning Time
  • an Activity should have a name
  • any resource may be associated with an Audience

The application profile must specify cardinality. for example:

  • Courses must have one and only one title
  • Units must have one or more Lesson
  • Units may have one or more Assessment

There may be alternative ways of satisfying a requirement

  • Courses must associated with either one or more Lesson or one or more Unit
  • If there is more than one Lesson in a Unit or Course, the Lessons must be ordered

The application profile must specify the expected type or value space for any property

  • this may be more restrictive than the base specification
  • this may extent the base specification
  • this may include alternatives (e.g. free text or reference concept from controlled scheme)

 

The post K12 Open Content Exchange appeared first on Sharing and learning.

HTML5 semantic sections with markdown⤴

from @ Sharing and learning

I’ve written a second extension for python markdown that will work with MkDocs. This one will let you put HTML5 semantic sectioning elements into the generated HTML. So, instead of just having <div>s in your generated HTML you can have, for example, an <article> or <chapter> divided into <sections>. Each of these can have an id attribute, and so can be identified, described in metadata (for example using embedded YAML) and linked to as a part of the page.  You can find the OCXSect extension on github, and you can read more about the development of it in some pages generated by MkDocs (that incidentally use the extension).

markdown that will generate HTML5 with semantic sectioning elements

What’s it do?

Markers of the form ~~X~~ and ~~\X~~ can be inserted in a markdown document at the beginning and end of what you want to be a section. The letter used will determine the type of HTML5 sectioning element is put into the HTML,<chapter>, <article>, <header>, <main>, <footer>, <section>, <nav> and <div> are currently supported (use the initial of the type of section you want). Text  after the letter will be used for the id attribute of the section. The choice of text is limited to ASCII A-Z, a-z, 0-9 !$-()+ so as to avoid unfortunate after effects if a non-URL safe character is used in what will become a fragment identifier in a URL. As a bonus, a textual representation of the structure is generated that can be useful for debugging.

So the markdown

~~C lesson1~~
~~H~~
#Markdown structure test
This is in the header section of a chapter. The chapter has id #lesson1. The header has no id.
~~/H~~
~~S section 1~~
#Activity 1
This is in a regular section (id #section1) of a chapter
~~/S~~
~~F~~
This is in the footer of the chapter
~~/F~~
~~/C~~

Generates the HTML

<chapter id="lesson1">
<header>
<h1>Markdown structure test</h1>
This is in the header section of a chapter. The chapter has id #lesson1. The header has no id.
</header>
<section id="section1">
<h1>Activity 1</h1>
This is in a regular section (id #section1) of a chapter
</section>
<footer>
This is in the footer of the chapter
</footer>
</chapter>

and the following representation of that structure:

|--chapter{'id': 'lesson1'}
    |--header
        |--h1
        |--p
    |--section{'id': 'section1'}
        |--h1
        |--p
    |--footer
        |--p

What’s it for?

The motivation for this extension, as with the previous one for generating metadata via YAML in markdown, is the K12 OCX project that I have been working on with people at Learning Tapestry. The aim of that project is to describe the structure and intent of curriculum and content material (CCM) for K12 in such a way as not only allows the exchange of CCM but also facilitates reuse and repurposing by editing and remixing. So rather than just say “here’s a load course material, use it as it is” we’re providing information about what the structure is, from course down to  activity, what all the pieces are and metadata to describe the content and role of those pieces. At some point that structuring happens within an HTML page, and so the pieces being described are sections of a page. For this we advocate using HTML5 sectioning elements that indicate the semantics of that section of the HTML, and JSON-LD metadata to describe the pedagogically significant sections. The sectioning part of this is actually quite similar to the ideas around textbook structure and elements I learned about from the Rebus community session run by the open textbook network.

We use MkDocs for documenting the K12OCX spec, and so in the spirit of eating our dog food I wanted to explore whether the spec could be exemplified to some extent by the documentation.

How’s it work

Essentially there are two parts to this extension, a python markdown treeprocessor that rearranges the HTML element tree after it has been generated, and a preprocessor that makes sure that the input is what we expect it to be.

The preprocessor runs through all the nodes in the HTML element tree, and recursively through the children of those nodes, replacing any p elements that indicate the start of a sectioning element (i.e . those that have text such as ~~S~~) with a new section into which subsequent nodes are moved until an element indicating the end of a section is reached.

This presupposes that the section start and end markers are in a paragraph by themselves, which will only happen if there is a blank line or block-level element the line before and after in the markdown before processing. The preprocessor does the user the favour of making sure that this is the case, while also making the input upper case, so that the original markers can be case-insensitive.

Take a look at my markdown notebook for this work for implementation details, or on github for the code.

Information about how to download, install, test and run the code in MkDocs are also on github. Please test it with caution, and let me know what you think.

Metadata for markdown / MkDocs⤴

from @ Sharing and learning

I’ve been experimenting with ways of putting JSON-LD schema.org metadata into HTML created by MkDocs. The result is a python-markdown plugin that will (hopefully) find blocks of YAML in markdown and insert then into the HTML that is generated. You can find the plugin on github, and you can read more about the development of it in some pages generated by MkDocs  (that incidentally use the plugin).

What’s it do?

Markdown is a widely used simple text format that allows formatting of text using inline markup, it’s a bit like the markup used on mediawiki/wikpedia. MkDocs is a python program that will build HTML pages out of markdown and templates. It’s geared towards the production of software/spec documentation, and we have been using it for documenting the metadata spec we’re creating for educational materials in the K12OCX project. (You’ll see the OCX part, Open Content Exchange, made it through to the plugin name.) Steve Midgley suggested that we might go further and use markdown to create the learning resources, somehow generating the metadata along with the HTML. MkDocs can be extended in a number of ways that would facilitate this, but most relevantly it uses the python markdown module, which has an API allowing for extensions.

YAML seemed like the obvious way of putting metadata into markdown. It’s another simple text format, for expressing key-value pairs, where the values can be lists or sets of other key-value pairs. It’s already used by MkDocs for specifying the site structure, and a number of extensions to python markdown already use it.

So the ocxmd extension for python markdown will look for blocks of YAML in a markdown document and replace them with blocks of JSON-LD in the HTML that is generated. It also provides the metadata as python dict in the markdown object. Feel free to try it out (cautiously) and let me know how it goes wrong / what it doesn’t do that it should / what it does that it shouldn’t …

How’s it work?

Quite simple really. I took inspiration from an existing YAML in markdown processor written by Nikita Sivakov (who’s probably a better programmer than me, so if his plug does what you want, use it, not mine). The YAML is separated before and after by a triple dash (‘—‘) on a line by itself. The plugin extends the python markdown Preprocessor so that it goes through the mark down document line-by-line looking for a triple dash. Until it finds one the text is copied into what will be returned as the ‘pure’ markdown document for further processing. When it finds a triple dash, it instead copies the lines into what will be processed as YAML (along with a few lines that will become the JSON-LD context). When it finds the closing triple dash, it processes the YAML using a python library, and then copies it into the markdown to be returned as JSON-LD between a couple of <script> tags. It also stores the python dict generated by the YAML processor as a new property in the markdown object. Then it goes back to reading line-by-line copying the text straight into what will be returned as markdown until it meets the end of file or the next triple dash.

If installed in a suitable python environment you can add it to the extensions available to MkDocs with an entry to the mkdocs.yml markdown_extensions block.

What does JSON-LD in YAML look like?

The metadata that we use for OCX is a profile of schema.org / LRMI,  OERSchema and few bits that we have added because we couldn’t find them elsewhere. Here’s what (mostly) schema.org metadata looks like in YAML:

"@context":
    - "http://schema.org"
    - "oer": "http://oerschema.org/"
    - "ocx": "https://github.com/K12OCX/k12ocx-specs/"
"@id": "#Lesson1"
"@type":
    - oer:Lesson
    - CreativeWork
learningResourceType: LessonPlan
hasPart:
  "@id": "#activity1-1"
author:
    "@type": Person
    name: Phil Barker