This document lays out the product specs for the first incremental delivery of value towards the broader Content Tagging Strategy for the Open edX Platform. The aim of this MVP is to deliver value as quickly as possible by limiting scope. This will allow us to learn quickly and shape future direction based on how stakeholders use the new tools.
Key Use Cases
To focus scope of the MVP, we are focusing on the following use cases (selected from larger list) that emphasize reusability of content, including the ability to search for content based on tags:
As an Instructor, I want to see all the content I've got for a particular competency, or subject, or skill, or learning outcome.
I want to search and filter for content catered to individual learner needs or knowledge gaps.
I want to attach topic tags to questions I create in Content Libraries so it's easy for me to find questions and reuse them in different assessments.
I want to create components that I can reuse in different courses, and tag those components with the right subject, like ‘soil health’, so I can see quickly what the subject matter of the component is when I reuse it.
As a learning designer, I want to tag units for competencies and learning objectives so that I can check for alignment between unit learning objectives and the overall course objectives.
I want to pull in external taxonomies such as the Open Skills Management Network so I don't have to create my own taxonomies from scratch and can align my content with third-party, vetted taxonomies.
Taxonomy Management System (Instance & Organization levels)
Instance-Level Super User: Refers to anyone with the ability to create and manage taxonomies for an entire instance. This is particularly relevant in multi-tenant (i.e., multi-org) instances the platform. This user typically has admin controls through Django Admin. We are proposing that as part of this project, this user type can manage instance taxonomies within Studio to take advantage of what we build without having to go into Django Admin.
Org-Level Super User: Refers to anyone with the ability to create and manage taxonomies for an organization. We anticipate that this role will be assigned in the same way that one is granted the ability to create courses and libraries today.
Content Author: Refers to anyone with the Staff or Admin role on a Course Team within a Course and/or Library. These users will be able to manage tags using the tagging tool.
Learner: Refers to anyone engaging in learning on the LMS. Tags will not be visible to learners as part of this MVP.
In Scope / Out of Scope
Based on the above use cases, we are breaking down on high-level scope as follows:
Out of Scope
Taxonomy association at the Instance and organization level.
Personal or course-level taxonomy association.
Taxonomy authoring through a CSV/JSON import process.
[Stretch] Manual taxonomy creation directly in the platform.
Taxonomies will be made available to all courses and libraries within an organization.
Ability to free-form tag without an super user-defined field.
Ability to create both super user-defined fields for free-form tags and closed (super user-defined fields and values) taxonomies.
Ability to make it required for authors to add specific tags.
Ability to add/remove tags at unit (outline + libraries) and component (library only for now) levels.
Tagging at other levels.
Tags will be visible to authors in Studio.
Tags will not be visible to learners.
Tagging at unit and component level.
Search across courses and/or libraries.
Free text search and tag-level search at both library and course outline levels.
Analytics on learner engagement with tagged content.
We will create a product tour for new users.
Ability to programmatically add tags on components/units.
Features & Requirements
In order to realize this MVP, we believe the following features will be required. Refer to the following flow chart for more details: Tagging MVP Workflows
Studio Home Access to Taxonomy Management System
All users with Studio Home access have the ability to view taxonomies at the org level in the same way they can see Courses and Libraries today.
Taxonomy Management System
Designated instance-level super users have the ability to do the following across the instance:
Import new taxonomies from CSV and JSON files into an instance
View existing taxonomies
Edit fields:tags on existing taxonomies
Add fields:tags to existing taxonomies
Delete fields:tags to existing taxonomies
Turn taxonomies on/off (i.e., publish/make available to orgs)
Export taxonomies to CSV and JSON files
Designated org-level super users have the ability to do the following across the org:
Turn instance-level taxonomies on/off (i.e., publish/make available to courses in org)
Import new taxonomies from CSV and JSON files into an org
View existing taxonomies
Edit fields:tags on existing org-level taxonomies (not instance-level)
Add fields:tags to existing org-level taxonomies (not instance-level)
Delete fields:tags to existing org-level taxonomies (not instance-level)
Turn org-level taxonomies on/off (i.e., publish/make available to courses in org)
Export taxonomies to CSV and JSON files
All super user-created taxonomies can be set up as specific fields that content authors can free-form tags on or as closed taxonomies with defined field-value pairs.
The taxonomy authoring experience should include access to a downloadable template (example) and instructions for how to set up/import a taxonomy.
Super users can create hierarchical relationships (child and grandchild) between tags.
Non-super users have the ability to view existing taxonomies.
Content Authors can turn taxonomies (instance and org-levels) on/off at the course level.
Course Outline Unit-Level Tagging Tool
Course Outline Component-Level Tagging Tool
Libraries Component-Level TaggingTool
Content Authors can view/add/delete tags as part of their authoring workflow in three separate experiences. The component-level tagging experience should be aligned across Course Outline and Libraries, while the Unit Level one only exists for the Course Outline today but future expansion to the Library authoring experience should be considered.
Viewing/adding/deleting free-form tags associated with super user-defined fields. These free-form tags should include predictive suggestions in order to surface and recommend similar previously-used tags as the Content Author types.
Viewing/adding/deleting single-select tags associated with super user-defined closed taxonomies
Permissions for adding or editing tags follow the same logic and permissions structure as editing content.
Authors can search for content within their Course Outline using both freeform keyword search (i..e, not tag-related) and tag-specific search.
Include a facet for content type.
Authors can search for content within their Library using freeform keyword search (i..e, not tag-related).
Authors can search for content within their Library using tag-specific search.
Include a facet for content type.
This experience should mirror that in the Course Outline.
Course Library Reference Component Search
Authors can search by tag for content within their Library using tag-specific search from within the Library Reference Content xBlock.
Taxonomy Field Types
We use the following definition of field types throughout the document. The MVP should include all these types except for free-form.
Field (example names)
Content Author Experience
Open-ended option to allow any Content Author to add any desired tags; these are all collected in a single (invisible?) field for good data management
Anything Content Author wants to enter
Content Author just sees a field to add as many tags as desired and can free-form add. Could include predictive suggestions of existing tags as they type.
Core tags controlled at the platform level (and auto-generated from the codebase) in order to keep consistency across search and discovery and for general messiness control. Super users would not be able to change these.
Language, format/content type, organization
Specific set against each of these.
Many of these would not be visible but some might be integrated into facet search (e.g., content type). Most would not be editable (ex. Perhaps language?)
super user-defined fields
Super users can set up specific fields that authors can free-form enter tags on. These would typically be used for instances in which there could be many possible tags but super user wants them organized separately from free-form tags
Outcomes, Learning Objectives
Anything Content Author wants to enter
Content Author is presented with the field and can enter a single free-form value.
super user-defined closed taxonomies
Super users can set up specific fields that require closed taxonomies (including selecting from existing, uploading, manually creating). Includes ability to create child and grandchild hierarchies
Lightcast skills, state standards
Content Author is presented with the field and a drop-down (or other UI selection element) to select the value.
When a Content Author reuses components from a Library to a course, all associated tags will display in the course outline. Tags will not display in the LMS or in any learner-facing view.
When a Content Author exports a course to a Library, all associated tags will display with the content in the Library.
The tags and taxonomies that a Content Author sees are determined by the taxonomies chosen and configured for their Instance or their organization. So if Instance A uses the Lightcast Skills taxonomy and Instance B uses the Open Skills Management Taxonomy, each will only see the tags in the taxonomy configured for them.
Tags will not be associated with specific course runs or versions. When a tag is applied, it will remain with the component/unit for subsequent course runs. Tags added will not be applied to previous versions of the content.
The platform will identify a core set of fields and taxonomies that are established and standardized, such as “language”, “content format” and “organization”. The platform will control these taxonomies to mitigate messy data and so that these fields can be used for faceted searching in libraries.
These core fields may be auto-generated from core data models in content blocks.
The fields and taxonomies will be unchangeable by the user.
Many of these would not be visible but some might be integrated into facet search (e.g., content format, language). Most would not be editable.
When taxonomies update, super users have the option to edit existing taxonomies or create new taxonomies. There will be no version control to associate multiple versions of a taxonomy.
Technical Open Questions
We anticipate the following to some of the key questions that we will need answered during technical discovery.
Where should the taxonomy live? Should it integrate with the current Discovery tagging tool or be built as a standalone service.
What is the best way to address the needs of a multi-tenant/org instance in which we need the ability for specific users to be able to create centralized taxonomies that are available to all organizations in the instance, while other users are only permitted to create taxonomies that live at a specific org?
Current thinking: We would like for the same taxonomy system to be used but separate super user permissions between instance-level and org-level.
How might we handle the situations in which users need to add and/or delete rows from an existing taxonomy? Should we build the capability to manually add these into the UI or force users to do an export→edit→import workflow? If we choose the former, shouldn't we also allow users to simply leverage that same functionality to create simple taxonomies directly in the UI?
Current thinking: We think eventually full manual taxonomy creation and adding/deleting fields should be available but not sure if this is technically too much scope for MVP. If it is, are we okay with the MVP process involving more cumbersome export→edit→import workflow?
Successful Rollout: UI Considerations
We believe there is some risk in low adoption of this new feature upon initial rollout due to the lift involved in aligning on taxonomies and tagging content. We believe that organizations will need time to get used to thinking about this and that future feature enhancements (such as tagging APIs or AI-driven tagging) may lower the barrier. Therefore, we want to be conscious about how we might drive adoption and educate users during the MVP stage.
We are proposing the following to help drive adoption:
New User Product Tour: MVP should include a new user product tour that will be used to walk authors through the features of the new tagging system and present ideas on how they may use it. This tour may include a video of the features and be set to prominently display to them when first accessing the Taxonomy Management System. We should consider whether the tour will only be available to super users who can create taxonomies or whether to include a non-super user facing tour available within the Taxonomy Management System and/or Course Outline/Library that raises awareness of features and encourages them to talk to super users to get a taxonomy created. Risk here is that the Tagging Tool cannot be used until a taxonomy exists.
Taxonomy Management System Getting Started Guide: Within the Taxonomy Management System, we need to provide super users with the template to create taxonomies as well as links (and possibly templates) to suggested taxonomies they may want to leverage. These can be hosted on docs.openedx.org.
Product & UX/UI FAQ
The following represent our Product view of key questions. However, we look to the UX/UI and technical teams to validate these as needed.
Q: How many levels of hierarchy will we support in initial taxonomies?
Q: Can a taxonomy author upload multiple free-form field taxonomies at the same time using an import file?
Q: What kind of user experience for viewing taxonomies are we expecting for the following hypothetical – an org taxonomy that has one very large predefined taxonomy (e.g., Lightcast skills) with thousands of rows of fields:tags, one medium-sized super user-defined closed taxonomy with hundreds of fields:tags at three levels of hierarchy and then dozens of free-form admin- defined fields?
Q: Is it possible to re-upload/replace an existing taxonomy? If so, how?
Q: Will we pre-load some taxonomies that they can use into the system?
A: In looking at this as a possibility for MVP, we decided that it would be too difficult to try to identify the right taxonomies, pre-load them onto the platform, and commit to keeping them up to date. This would also mean that certain taxonomies would always be loaded into the platform in a completely different way. Extending the Taxonomy Management System to an instance-level superuser and providing recommendations on possible taxonomies to import would help seed this instead.
Q: How will tags update when someone tries to edit a tag on a component in a course outline that is also in a library and possibly used in other courses?
Q: Decision on tag relationships between components in a unit to that unit and vice versa
A: The logic for this should align with how this is handled for all other updates made to these shared components
The following features are not part of the MVP but may be added during future development of this product. They are offered here only for consideration as MVP platform decisions are made that may impact future opportunities.
Tagging Tool Development:
Open-ended free-form tags (and a strategy for data management)
Adding tags to subsections and sections directly in the course outline
Creating units, subsections and sections independently in Libraries and add tags as part of that authoring workflow
Taxonomies will support localization
Programmatic ways to bulk add tags (e.g., authoring APIs or AI-driven solutions)
Tagging Management System Development:
Map hierarchical or horizontal relationships
Enhanced controls such as locking down taxonomies
Content Management Experience Development:
Use tags to organize content into playlists, folders
Additional search filters
Tools to assess content and/or learner performance based on tags
Authors can add free-form tags on super user-defined fields.
UI where author is presented with the field and can enter a single free-form tag.
OER Commons has an author interface for “free form tags on super user-defined fields” here. The instance administrator would have already defined that “subject”, “education level” etc are fields that should be attached to the content. However, there’s no prescribed taxonomy attached, so authors can type anything they want in those fields. Maybe there’s predictive suggestions when they start typing.
Authors can choose from a tag from an super user-defined closed taxonomy.
UI where author is presented with the field and a drop-down (or other UI selection element) to select the value.
This is OER Commons interface for “super user-defined field with closed taxonomy”. So in this case, the admin has predefined “education level” as the field, and associated a taxonomy with 8 tags in it (“preschool”, “lower primary” etc). The author must choose one of those 8 fields. We can imagine taxonomies with hundreds of tags in them. In this case, maybe the drop down is alphabetical, or maybe there’s also predictive suggestions, but the suggestions are limited to terms in the taxonomy.