Referencia YAML OAS

La arquitectura OAS (Open Assessment Specification) v1beta1 de ColabEdu se configura enteramente a través de un esquema estructurado de archivos YAML. Esta aproximación Assessment as Code permite versionar, auditar y reproducir todo el ecosistema pedagógico.

En esta sección encontrarás la referencia técnica completa de cada Kind (tipo de recurso), desde taxonomías curriculares hasta lecciones interactivas generadas por AI.

Estructura base de cualquier spec YAML

Todos los recursos OAS comparten los mismos campos obligatorios:

apiVersion: colabedu.ai/v1beta1   # versión del esquema
kind: Recipe                       # tipo de recurso (ver tabla inferior)
metadata:
  referenceCode: global.c1.ib.spanish_b.sl.debate.v1
  title: "IB Spanish B SL — Debate Activity"
  version: 1.0.0
  authorityScope: GLOBAL           # GLOBAL | ES | MX | US | TENANT
  tags: [ib, spanish, sl]
spec:
  # contenido específico del tipo

Tipos de especificaciones disponibles

🏛️ Motor y Taxonomías

Kind	Descripción
Taxonomy	Define jerarquías geográficas, niveles organizativos y competencias.
SubjectArea	Clasificación de una materia a nivel local e internacional.
PathwayTemplate Nuevo	Template oficial de currículum (ej. IB Spanish B SL) con temas, subtemas y pesos de evaluación.

📐 Normativa Curricular — Capa C0

Kind	Descripción
BlockRubric	Estándares inmutables de aprendizaje, criterios de evaluación y descriptores por nivel. Ingestada automáticamente por el Curator desde documentos normativos.

📚 Recetas y Contenidos — Capas C1 y C2

Kind	Descripción
Recipe	Receta ensambladora que asocia competencias C0 con tipos de ejercicio y criterios para generar una evaluación C2.
ExerciseSpec	Evaluación generada o definida manualmente, lista para resolver por el alumno.
ExerciseType	Definición técnica del formato de interacción (`free_text`, `multiple_choice`, `grouping`…).
AssessmentItem	Componente atómico de evaluación interactiva, instanciado y empaquetado para el frontend.

🎓 Contenidos Interactivos y Recursos — Capa C2 Nuevo

Generados automáticamente por el Agente Curador a partir de documentos, paquetes LMS y recursos OER.

Kind	Descripción	Fuente típica
InteractiveLesson	Lección con slides, widgets embebidos (`quiz_widget`, `mermaid_viewer`, `scratchpad_widget`…) y routing adaptativo.	Paquetes Canvas `.imscc`, Moodle `.mbz`
ResourceLearning	Puntero anotado a recurso OER externo con `qualityScore` pedagógico de 3 dimensiones.	CK-12, Khan Academy, Procomún, Europeana

Estructura `InteractiveLesson` (resumen)

kind: InteractiveLesson
spec:
  learningObjectives: [...]
  slides:
    - id: intro_slide
      layout: title           # title | split | content | quote | full
      title: "Mitosis"
      markdown: "..."
      fragmentsCount: 1       # revelación progresiva
      embeddedWidget:
        type: quiz_widget     # quiz_widget | mermaid_viewer | scratchpad_widget | grouping_widget
        props:
          taskId: quiz_mitosis
          routes:
            on_success: slide_avanzada   # routing adaptativo
            on_fail: slide_repaso

Estructura `ResourceLearning` (resumen)

kind: ResourceLearning
spec:
  resourceUrl: "https://www.ck12.org/biology/mitosis/"
  resourceType: ARTICLE        # ARTICLE | VIDEO | INTERACTIVE | SIMULATION
  qualityScore:
    alignment: 0.92
    pedagogicalRichness: 0.87
    accessibility: 0.78
  learningObjectives: [...]
  tags: [mitosis, biology, cell-division]

🗂️ Orquestación ACA y Currículo

Tipo de Fichero	Descripción
CuratorPlan	Plan de ingesta persistente del ACA. Creado por CLI o REST API. Registra país, estándar, estado, ítems y configuración de la campaña.
CurriculumRequirements	YAML de requisitos curriculares (`ce-specs/catalog/requirements/`). Define cuántas specs de cada tipo (`BLOCK_CONTENT`, `BLOCK_RUBRIC`…) se necesitan por tema para completar un currículo. Usado por `CurriculumGapAnalyzer`.
Curator Batch YAML	Fichero declarativo de pipeline (`ce-specs/batches/`). Define etapas (`discover`, `fetch`, `parse`, `approval`, `ingest`) en un YAML y se ejecuta con `spec batch run`.

🤖 Inteligencia Artificial y Agentes — Capa C3

Kind	Descripción
Directive	Directrices de comportamiento que limitan o guían al motor LLM.
Persona	Perfiles de interacción del sistema (ej. Instructional Designer).
Gem	Módulos extendidos de IA con configuración y herramientas embebidas. El `gem.curator_lesson` v1.3.0 genera lecciones interactivas adaptativas.

Generación automática con el Agente Curador

Los tipos InteractiveLesson y ResourceLearning rara vez se escriben a mano: el Agente Curador los genera automáticamente desde tus documentos existentes.

# PDF o Canvas → InteractiveLesson con quiz routing adaptativo
curator curate \
  --source canvas_bio_mitosis.imscc \
  --output-type INTERACTIVE_LESSON \
  --adaptive \
  --sandbox

# Recurso OER → ResourceLearning anotada
curator curate \
  --source gs://bucket/ck12_bio.json \
  --source-type OER_RESOURCE \
  --output-type RESOURCE_LEARNING

→ Ver Capacidades del Agente Curador para el flujo completo.