Oerschema Audit

OER Schema Audit (Read-Only Diagnostic)

Review authored content on an existing HAX site/page (or VitePress / JSON-LD / Docs-export content) against the OER Schema vocabulary and emit a diagnostic + remediation report. This skill diagnoses and recommends only — it does not edit pages, mutate site.json, or insert markup. It mirrors the hax-a11y-audit / hax-udl-audit pattern but operates through the OER Schema lens: does the authored content carry the correct semantic pedagogical structure that makes it discoverable and interoperable as an open educational resource?

The worldview in one paragraph

OER Schema is a vocabulary that extends schema.org with education-specific terms (Course, LearningObjective, Assessment, Rubric, etc.) so educational content is machine-readable and interoperable. The HAX ecosystem commits to applying OER Schema metadata to educational elements, and the UbD skill family already produces OER-schema-tagged unit skeletons — but no existing skill audits authored content to see whether the schema is present and correct. This skill fills that gap. It is distinct from a11y (technical access for people with disabilities), from UDL (pedagogical inclusivity), from content chunking (cognitive load), and from UbD unit audit (instructional-design alignment). It is also distinct from component-internal schema support (an element's own code not emitting microdata), which oerschema-integration-finder owns. This audit reports what is missing or mis-classified, cites the class/property, and recommends only real remediation in the right markup surface — never an invented tag or property.

When to Use

Trigger conditions:

• "Audit this page for OER schema" / "what schema should this lesson have"
• "Is this quiz marked up as the right OER class" / "does my site.json map to oerschema"
• "Check my VitePress directives against the vocabulary" / "is this JSON-LD valid OER schema"
• "Scan my site for content missing oerschema" / "which of these pages need OER schema"
• "What OER class should I use for a group project" (when the user is reviewing authored content)
• even when the user does not say "OER schema" or "audit" — if they question whether authored educational content carries the right semantic metadata, this is the skill

When NOT to use (with redirect):

• A web component's own code doesn't emit schema (the gap is in the element, not the page) → oerschema-integration-finder
• Technical WCAG access of the content → hax-a11y-audit
• Pedagogical inclusivity / multiple means → hax-udl-audit
• Page-scope cognitive load / chunking → hax-content-chunking-audit
• Unit alignment / backward design / are assessments aligned → hax-ubd-unit-audit
• Cognitive level of an objective/assessment (Bloom's) → grad-blooms
• Editing the OER Schema vocabulary itself (schema.ts) → oerschema-schema-author (repo-local)
• Validating schema.ts internal consistency → oerschema-validation (repo-local)

Scope: this skill is READ-ONLY

This skill diagnoses and recommends only. It produces a report. To apply remediation, hand off to the related skills and the hax CLI / hax-claudehax (see "Implementing the Recommendations" below). Never edit pages/*.html, site.json, VitePress markdown, or source files from within this skill.

Inputs

• a HAX site path: site.json (JOS tree) + pages/*.html, or a single page (JOS node / raw HTML / markdown)
• or a VitePress markdown file using ::: learning-objective / ::: assessment / ::: rubric / ::: practice / ::: instructional-pattern directives
• or a JSON-LD block (a <script type="application/ld+json"> or a standalone .jsonld)
• or Google Docs export HTML (the itemscope itemtype="http://oerschema.org/..." microdata the Apps Script add-on emits)
• optional pageSlug to scope the audit to one page (else audit every page and report site-level patterns)

Methodology

1. Ingest structure. Locate the content and identify which markup surface(s) are present:
   • HAX: site.json (JOS tree + metadata) + pages/<slug>.html (rendered content)
   • VitePress: ::: container directives (see references/markup-surfaces.md)
   • JSON-LD: <script type="application/ld+json"> blocks
   • Docs export: itemscope/itemtype/itemprop microdata
2. Load the vocabulary. Consult references/vocabulary.md for the class hierarchy and the property domain/range tables (derived from schema.ts v1.2.0). This is the single source of truth for what classes and properties exist and where each property is valid.
3. Run the OER Schema checks across authored content. For each page/block, evaluate:
   • Presence: pedagogical structures are present in the content but carry no OER Schema markup at all. A lesson page with heading "Lesson 3", a quiz section, learning objectives stated in prose, and a rubric table — but no itemscope/itemtype/itemprop or directives — is a presence gap. Identify the most specific class for each structure (see mapping refs).
   • Classification: schema is present but the class is wrong or too generic. A quiz tagged itemtype="http://oerschema.org/Task" should be Assessment (or Quiz, which subclasses Assessment). A unit page tagged LearningComponent could be the more specific InstructionalPattern → Unit. Report the current type and the recommended type.
   • Property/domain validity: a property is used on a class outside its domain. skill is domain LearningObjective — using itemprop="skill" on an Assessment is invalid. hasLearningObjective is domain InstructionalPattern — using it on a bare Task is invalid (a Task is an InstructionalPattern subclass, so it is valid via inheritance — use references/vocabulary.md and the inheritance rule before flagging). Report the property, the class it was used on, and the declared domain.
   • Range validity: a property's value type doesn't match its range. gradingFormat range is GradeFormat | Text — a raw number on gradingFormat should be a PointGradeFormat or text. assessing range is Activity — pointing assessing at a Quiz is invalid (Quiz is an Assessment, not an Activity). Report the property, the value, and the declared range.
   • subClassOf chain: a declared itemtype doesn't resolve. itemtype="http://oerschema.org/Foo" where Foo is not a class in the vocabulary. Report the unresolved type.
   • Inverse consistency: an inverse pair is used one-directionally without its partner, or a relationship that should be reciprocal is dangling (e.g. forComponent without a matching hasComponent on the parent). Note: forComponent/hasComponent declare themselves inverses in their comments but do not set the inverseOf field in schema.ts — flag the content gap (missing reciprocal link), not the vocabulary gap (which is oerschema-validation's job).
   • Rubric family integrity: a Rubric should have hasCriterion → RubricCriterion and rubricScale → RubricScale → hasLevel → RubricLevel. A rubric directive with levels but no scale, or criteria with no criterionWeight, is a structural gap.
   • ActionType usage: a Task/Practice/Activity with a typeOfAction value that is not one of the ActionType subclasses (Reading, Writing, Making, Researching, Listening, Watching, Reflecting, Discussing, Observing, Presenting, Assess). Report the invalid action value.
4. Map each finding to a concrete remediation in the right surface. Use references/markup-surfaces.md to pick the surface the content is already in (microdata for HAX pages / Docs export, ::: directives for VitePress, JSON-LD for structured-data blocks). Use references/hax-outline-mapping.md for site.json → class mapping and references/ubd-mapping.md when the content originated from a UbD unit. Every recommendation names the exact class, the exact properties, and the exact surface — so the post-audit conversation can apply it directly without re-deriving.
5. Apply the overlap / defer rules:
   • Component-internal schema gap: if the reason content lacks schema is that the rendering element doesn't emit microdata (e.g. a quiz-element with no itemtype), defer to oerschema-integration-finder (code fix), not this skill (content fix).
   • Vocabulary bug: if the schema is wrong because schema.ts itself has a broken subClassOf or missing inverseOf, defer to oerschema-validation / oerschema-schema-author.
   • Pedagogical alignment: if the issue is that the objectives/assessments don't align with desired understandings (not a schema problem), defer to hax-ubd-unit-audit.
   • Cognitive level: if the issue is the Bloom's level of an objective, defer to grad-blooms.
6. Determine the overall rating:
   • Covered: all pedagogical structures carry correct, domain/range-valid schema. Minor advisories (e.g. "consider the more specific Quiz over generic Assessment") may be noted but do not affect the rating.
   • Partial: some structures lack schema, or some properties are mis-classified, but the page has a recognizable semantic skeleton. Remediation is surgical.
   • Uncovered: a pedagogically dense page (lessons, objectives, assessments, rubrics) with zero OER Schema markup, or a structural break (every itemtype unresolved, or a rubric with no criteria/scale).
7. Emit the report (format below), then an "Implementation handoff" block.