Oerschema Integration Finder

OER Schema Integration Finder (Read-Only Diagnostic)

Scan HAX ecosystem code — webcomponents, themes, CMS backends, the VitePress plugin, and the Google Apps Script add-on — for surfaces that render or consume pedagogical content but do not emit or consume OER Schema metadata, and emit a per-file hit-list of integration opportunities. This skill diagnoses and recommends only — it does not edit source. It mirrors the oerschema-audit pattern but operates on code, not authored content: where oerschema-audit asks "does this page have the right microdata?", this skill asks "does this element emit the right microdata?"

The worldview in one paragraph

OER Schema only lands in authored content if the rendering elements emit it. A HAX quiz element that renders questions but no itemscope itemtype="http://oerschema.org/Quiz" means every page using that element is silently uncovered — a code gap, not a content gap. The HAX ecosystem has many elements that render pedagogical structures (quizzes, outlines, objectives, rubrics, media playlists, syllabi) and several surfaces that transform content (the VitePress plugin, the Apps Script add-on, the CMS backends). This skill scans those code surfaces for missing schema emission or consumption and produces a hit-list that hax-webcomponent-dev can act on. It is distinct from oerschema-audit (authored content), from hax-a11y-audit (accessibility), and from hax-webcomponent-dev (which implements the fixes this skill identifies). It does not invent classes/properties — every recommendation cites a real OER Schema class from the v1.2.0 vocabulary.

When to Use

Trigger conditions:

• "Which of my webcomponents should emit OER schema" / "find assessment code without schema support"
• "Where in my codebase should oerschema be wired in" / "does the quiz element emit microdata"
• "Audit my components for OER schema integration opportunities"
• "What elements in HAX could expose OER schema but don't"
• "Does the VitePress plugin cover all the OER classes" / "does the Google Docs add-on emit rubrics"
• even when the user does not say "finder" or "OER schema" — if they ask which code surfaces should carry educational schema metadata, this is the skill

When NOT to use (with redirect):

• A specific page is missing schema (the gap is in authored content, not the rendering element) → oerschema-audit
• Implementing the schema emission in a component (writing the LitElement template / haxProperties) → hax-webcomponent-dev
• The OER Schema vocabulary itself needs new classes/properties → oerschema-schema-author
• schema.ts internal consistency → oerschema-validation
• Accessibility of a component → hax-a11y-audit / hax-webcomponent-dev

Scope: this skill is READ-ONLY

This skill diagnoses and recommends only. It produces a hit-list. To implement, hand off to hax-webcomponent-dev (for webcomponents), hax-site-building (for themes), or the relevant backend/plugin maintainer. Never edit source files from within this skill.

Inputs

• A codebase path to scan. Typical targets:
  • the webcomponents monorepo (e.g. ~/Documents/git/haxtheweb/webcomponents)
  • a single element directory (e.g. elements/<tag-name>)
  • a HAXcms theme directory
  • a CMS backend (PHP: haxcms-php; NodeJS: haxcms-nodejs)
  • the VitePress plugin (oerschema/vitepress-plugin/)
  • the Google Apps Script add-on (oerschema/google-apps-script/)
• optional scope flag: --surface=webcomponents|theme|backend|plugin|appsscript to limit the scan

Methodology

1. Identify the scan target and surface. Determine whether the path is a webcomponent, a theme, a backend, the VitePress plugin, or the Apps Script add-on — each has a different schema-emission mechanism (see references/component-patterns.md).
2. Load the vocabulary. Consult oerschema-audit's references/vocabulary.md (the v1.2.0 class
   • property tables) as the source of truth for what classes/properties exist. This skill does not duplicate that file; it references it.
3. For webcomponents, for each element:
   • Read the element's src/<tag>.js (LitElement class) and its render() / template. Look for itemscope, itemtype, itemprop in the template — the microdata emission surface.
   • Read its haxProperties / haxProperties.json / HAXSchema — the HAX editor integration surface. Does it expose a schema-relevant gizmo type or properties that map to OER classes?
   • Classify the element by what it renders (see references/component-patterns.md candidate list): assessment/quiz, outline/navigation, objective, rubric, syllabus, media, reading, activity. If it renders a pedagogical structure and emits no microdata, it is a hit.
   • If it emits microdata with a wrong/invalid itemtype or a property outside its domain, it is a mis-classification hit (use the vocabulary + inheritance rule to verify).
4. For themes, check whether the theme wraps page content in an OER class wrapper (e.g. a Course/Unit wrapper around the rendered page) or emits a site-level JSON-LD block. A theme that renders pages/*.html content with no surrounding OER class is a structural hit.
5. For CMS backends (PHP/NodeJS HAXcms), check whether the backend exposes OER Schema in its data model / API responses (site.json, page JSON, outline endpoints). A backend that serves outline data with no OER class mapping is a hit. Per PRAW rules, only the siteRoutes api/v1 system is in scope for NodeJS — do not flag the legacy src/routes/* (v0) endpoints.
6. For the VitePress plugin, compare the directives it implements against the OER class vocabulary. The plugin currently implements learning-objective, assessment, practice, rubric, rubric-criterion, rubric-scale, rubric-level, learning-component, instructional-pattern. Missing directives: no dedicated course, unit, module, lesson, quiz, submission, task, activity, project, learning-objective (present), syllabus, topic. Each missing directive for a class that authors would reasonably use is a plugin hit.
7. For the Apps Script add-on, compare the components it can insert (LearningObjective, Assessment, Practice) against the vocabulary. Missing: Quiz, Rubric family, Lesson wrapper, Task/Activity. Each missing component is an add-on hit.
8. For each hit, record: file path, the element/surface, what it renders, the recommended OER class + properties it should emit, and the implementation handoff (hax-webcomponent-dev for components, hax-site-building for themes, the relevant maintainer for backends/plugins).
9. Apply the overlap / defer rules:
   • If the gap is actually in authored content (the element emits microdata but the page didn't use it), defer to oerschema-audit.
   • If the element needs new vocabulary to emit the right class, defer to oerschema-schema-author.
   • If the gap is a component-internal accessibility issue, defer to hax-a11y-audit / hax-webcomponent-dev.
10. Determine the overall rating:
    • Wired: the scanned surface emits/consumes schema for all pedagogical structures it renders.
    • Partial: some pedagogical structures emit schema, others don't; or some emit mis-classified schema.
    • Unwired: the surface renders pedagogical content but emits zero OER Schema metadata.
11. Emit the hit-list (format below), then an "Implementation handoff" block.