OPS Reference & Conceptual Map

ColabEdu’s OPS (Open Pedagogy Specification) architecture treats education as code (Pedagogy as Code). Every component of the pedagogical ecosystem—from statutory curriculum standards to exercise prompts or Socratic grading rubrics—is defined via a typed, immutable, and Git-auditable YAML specification.

To make the system immediately understandable for educators and engineers alike, specifications are grouped into four functional categories, cleanly separating the Open Standard schemas from the Partner Automation Tooling.

🏛️ The 4 Pedagogical Spec Categories

flowchart LR
    subgraph Cat1["1. Content & Learning"]
        IL["InteractiveLesson<br/>(Interactive Lesson)"]
        RL["ResourceLearning<br/>(OER Resource)"]
    end

    subgraph Cat2["2. Assessment & Grading"]
        BR["BlockRubric<br/>(C0 Rubric)"]
        RC["Recipe<br/>(C1 Orchestrator)"]
        EX["ExerciseSpec<br/>(C2 Assessments)"]
    end

    subgraph Cat3["3. Curriculum & Management"]
        CS["CourseSpec<br/>(Sovereign Course)"]
        PT["PathwayTemplate<br/>(Official Framework)"]
        TX["Taxonomy<br/>(Standards/Levels)"]
        CB["CourseBundle<br/>(Cohort Freeze)"]
    end

    subgraph Cat4["4. Governance & Roles (C3)"]
        DI["Directive<br/>(Classroom Directives)"]
        PE["Persona<br/>(AI Didactic Role)"]
    end

    Cat3 -->|"Structures"| Cat1
    Cat3 -->|"Weights"| Cat2
    Cat1 -->|"Practices via"| Cat2
    Cat4 -.->|"Constrains"| Cat2

1. For Content and Learning (Classroom Experiences)

Specifications designed for direct student interaction with learning material. These are not static texts: they are dynamic, stateful learning units with embedded formative checks.

Kind	Pedagogical Purpose	Designed by
InteractiveLesson	Multimedia interactive lessons. Organized in slides with Markdown, LaTeX math, adaptive branches (routes), and embedded widgets (`quiz_widget`, `mermaid_viewer`, `scratchpad_widget`).	Content Authors / LMS Importers
ResourceLearning	Curated Open Educational Resource (OER) pointers (videos, PhET simulations, open articles) annotated with a 3D pedagogical quality score (alignment, pedagogicalRichness, accessibility).	Curriculum Librarians / Educators

2. For Assessment and Grading

Specifications that ensure rigorous, reproducible, and curriculum-aligned assessment matching statutory standards or standardized exams (EBAU, AP, IB).

Kind	Pedagogical Purpose	Designed by
BlockRubric	The statutory source of truth (Layer C0). Defines official analytical criteria, qualitative achievement descriptors, and scoring bands.	Ministries, Quality Agencies, Exam Boards
Recipe	The pedagogical orchestrator (Layer C1). Connects target competencies, evaluation rubrics, report formatting, and feedback directives.	Instructional Designers / Dept Heads
ExerciseSpec	Concrete assessment instrument (Layer C2). Contains the stimulus material (passage, audio, chart) and associated prompt questions.	Teachers / Content Authors
AssessmentItem	Atomic interactive assessment component. An isolated item packaged for real-time frontend execution and evaluation.	Item Writers
ExerciseType	Agnostic interaction catalog. Standardizes interaction formats: free-text, multiple-choice, matching, ordering, virtual whiteboard, etc.	Educational Engineers

3. For Curriculum, Taxonomies, and Academic Governance

Specifications resolving course structure, territorial sovereignty, and academic cohort lifecycles.

Kind	Pedagogical Purpose	Designed by
CourseSpec	Sovereign course instance. Specializes an educational standard for a specific school and delivery track (`FULL_YEAR`, `INTENSIVE`, `EXAM_MASTERY`, `REMEDIATION`), with targeted misconception libraries.	Schools / Academic Coordinators
PathwayTemplate	Official curriculum framework. Structures a subject into units, estimated hours, and official exam component weights.	Standard Organizations (IB, College Board)
StandardSpec	Standard foundation spec. Holds overarching guidelines and diagnostic misconception libraries for an educational framework.	Educational Authorities
Taxonomy & TaxonomyIndex	Jurisdiction and grade hierarchy. Encodes countries, regions, organizational levels, and transversal competencies as GitOps code.	Governance Teams
SubjectArea	Unified subject taxonomy. Classifies and normalizes academic disciplines globally (Mathematics, Spanish, Sciences).	Catalog Administrators
CourseBundle	Immutable snapshot artifact. Packages courses and units to create immutable academic snapshots for cohort rollover or LMS export.	Academic Leadership / SysAdmins

4. For Governance and Classroom Roles (Layer C3)

Specifications establishing the ethical, didactic, and behavioral boundary of AI in education.

Kind	Pedagogical Purpose	Designed by
Directive	Classroom didactic directives. Teacher-imposed constraints (e.g., “Never give direct answers”, “Use Socratic counter-questions”).	Classroom Teacher
Persona	Pedagogical tone and character. Configures tutor demeanor (e.g., Empathetic Socratic Tutor, Formal Exam Grader).	School Counselors / Educators

5. Partner Tooling (Content Factory & Automation)

CuratorPlan: Persistent ingestion campaign tracking.
CuratorBatch: Declarative multi-stage pipelines (discover $\to$ parse $\to$ approval $\to$ ingest).
CurriculumRequirements: Quantitative target rules for CurriculumGapAnalyzer.
Gem: Modular AI configuration packages for domain-specific curation.

Canonical Universal Envelope (`colabedu/v1`)

# --- UNIVERSAL OPS ENVELOPE ---
api_version: "colabedu/v1"         # Formal schema version
kind: "BLOCK_RUBRIC"               # Resource type from SpecType enum
metadata:
  reference_code: "us.ca.c0.spanish_2.rubric.oral_presentation.v1"
  title: "California Spanish 2 — Oral Presentation Rubric"
  version: "1.0.0"                 # Semantic version
  authority: "DISTRICT"            # GLOBAL | NATIONAL | DISTRICT | SCHOOL | TEACHER
  tags: ["cde", "california", "spanish_2", "speaking"]

# --- POLYMORPHIC PAYLOAD ---
spec:
  # Internal fields strictly defined by 'kind'