ORNs provide a way to universally identify resources. A resource could be a book, a part of a book, a quiz, an ancillary resource, or any other type of thing that we need to define. An ORN may include a UUID, but it will also provide the context necessary to identify the resource type based on the identifier.
ORN are defined in IRI format. We use this format for a few reasons:
- we integrate with xAPI systems and that spec requires activities to be identified in IRI format
- the format makes it easy to include contextual information to recognize the types of resources
- its not necessarily required that the IRI actually resolve to anything if you tried to load it in a browser (many xAPI identifiers don't) but we have the option of someday introducing a little service that would know how to resolve metadata about resources or redirect you to view/manage interfaces for the resource.
IRI is a very open ended format, so for ORN we've decided to limit the structure to this:
eg:
https://openstax.org/orn/ancillary/031da8d3-b525-429c-80cf-6c8ed997733a
https://openstax.org/orn/assessment/031da8d3-b525-429c-80cf-6c8ed997733a
https://openstax.org/orn/content:book/031da8d3-b525-429c-80cf-6c8ed997733a
each resource type can use whatever identifier format is most useful. the ID should provide enough information to be able to locate the resource given the understanding of the ID format. It won't be expected that the knowledge of how to interpret these IRI will need to be reproduced in all the places that they are used, we may provide tools such as shared libraries, or a small microservice, to help interpret them in a centralized way.
for example identifying a learning objective with only a uuid or element id doesn't help you locate its definition, you need to know where in the content to find it, so we can create a better identifier by concatenating the source content with the learning objective id. eg:
https://openstax.org/orn/content:learning-objective/{book_uuid}:{page_uuid}:{element_id}
It would be fine for a resource type to include a version identifier on its id, for instance in our content it might look normal do do something like:
https://openstax.org/orn/content:book/031da8d3-b525-429c-80cf-6c8ed997733a@asdfb
But be careful before doing this by default, depending on usage it may be more correct to use the ORN to indicate the resource in general and not a single version in particular. For instance a typical usage of an ORN would be to indicate that a particular video is about or supports a certain part of the textbook content, the video would hold an ORN to the content, and then you can filter videos by content. In this case you don't want to have to update the video every time a new version of the content is published.
Openstax has a variety of content and activity types using different technologies and different formats. These resources are usually about other resources. This can be in a direct way, like exercises that assess the knowledge learned by reading a certain section of content or watching a certain video or performing a certain activity, or in a dependent way, like topics that build on knowledge from other topics. In any case, we have a need to be able to create a graph of our various content resources and that starts with being able to universally identify, recognize, and locate those resources.
use this repository to:
- create github issues and have discussions about how to identify different types of resources
- write code for the serialization and/or de-serialization of resources to IRI
- publish that code in re-usable libraries so that tools/apps can easily work with resources/iri to generate iri and extract metadata
- publish that code in a microservice so that tools/apps can choose to integrate with that instead of a library
- define a standard interface for resource metadata like name/description/etc