Taxonomy

El recurso Taxonomy permite definir y estructurar conceptos jerárquicos como ubicaciones geográficas (países, regiones), niveles organizativos del sistema educativo, o estándares curriculares agrupados por materia y nivel.

Esta estructura es fundamental para organizar y filtrar otros recursos dentro del sistema (como rúbricas y ejercicios). También es la base del pipeline de scaffolding CLI, que usa los identificadores de taxonomía para descubrir, descargar y auto-generar rúbricas de evaluación a partir de documentos curriculares oficiales.

Esquema (Schema)

Metadata (metadata)

Campo	Tipo	Requerido	Descripción
id	string	Sí	Identificador único de la taxonomía (ej. loc.es o std.intl).
type	string	Sí	El tipo de taxonomía. Valores comunes: location_country, standard.
active	boolean	Sí	Indica si la taxonomía está activa.
name	string	Sí	Nombre legible de la taxonomía (ej. “España” o “International Standards”).
flag	string	No	(Solo para ubicaciones) Emoji de la bandera del país.
languages	string[]	No	Lista de idiomas soportados (ej. [es-ES]).
countryRef	string	No	Referencia a qué país aplica (ej. global).

Especificación (spec) - Variante location_country

Cuando type: location_country, el bloque spec define regiones y niveles organizativos:

Campo	Tipo	Descripción
regions	array	Lista de regiones/estados del país. Cada región contiene id, name, active, languages y flagAsset.
orgLevels	array	Lista de niveles organizativos (ej. Primaria, Secundaria). Cada uno contiene id y name.

Especificación (spec) - Variante standard

Cuando type: standard, el bloque spec define estándares, niveles y materias:

Campo	Tipo	Descripción
standards	array	Lista de estándares (ej. IB, AP). Cada uno contiene id, name, active, además de levels y subjects.
levels	array	(Dentro de un estándar) Niveles educativos que cubre (ej. DP, MYP). Contiene id, name, active.
subjects	array	(Dentro de un estándar) Materias. Contiene id, name, active y applicableLevels (lista de ids de niveles).

Especificación (spec) - Variante bundle_course

Cuando type: bundle_course, el recurso agrupa una oferta de curso completa bajo un único nodo de taxonomía. Es la entrada principal del pipeline de scaffolding CLI:

Campo	Tipo	Descripción
displayName	string	Nombre legible del curso (ej. “AP Spanish Language and Culture”).
taxonomyRef	string	Referencia a la taxonomía de estándar padre (ej. std.intl.ap.v1).
subject	string	Identificador de materia (ej. subj.intl.ap.spanish_language_and_culture).
educationLevel	string	Identificador de nivel educativo (ej. lvl.intl.ap.high).
units	array	Lista ordenada de unidades del curso. Cada unidad contiene id, name, description y suggested_hours.

Relación con las Rúbricas

Los bundles de taxonomía son la fuente de verdad para la generación de rúbricas. El comando CLI taxonomy rubrics scaffold lee un spec bundle_course para derivar la estructura de la rúbrica:

bundle_course (Taxonomy)
    └── units[]  →  rubric criteria[]  →  BLOCK_RUBRIC (Capa C0)

Cada unidad del bundle se convierte en un criterio de la rúbrica generada, heredando id, name, description y suggested_hours.

Ejemplo de Uso

apiVersion: colabedu.ai/v1beta1
kind: Taxonomy
metadata:
  id: loc.es
  type: location_country
  active: true
  name: España
  flag: 🇪🇸
  languages: [es-ES]
spec:
  regions:
    - id: loc.es.mad
      name: Comunidad de Madrid
      active: true
      flagAsset: assets/flags/es/mad.svg
    - id: loc.es.cat
      name: Catalunya
      active: true
      languages: [ca-ES]
      flagAsset: assets/flags/es/cat.svg
  orgLevels:
    - id: org.lvl.es.infantil
      name: Infantil
    - id: org.lvl.es.primaria
      name: Primaria

Comandos CLI Relacionados

# Descubrir documentos oficiales para un bundle
bash ce-cli.sh taxonomy sources discover --referenceCode bundle.us.ap.spanish_language.hl

# Descargar el PDF curricular
bash ce-cli.sh taxonomy sources fetch --referenceCode bundle.us.ap.spanish_language.hl

# Generar el YAML de rúbrica (con niveles de logro generados por AI desde el PDF)
bash ce-cli.sh taxonomy rubrics scaffold --referenceCode bundle.us.ap.spanish_language.hl --ai true

Consulta el Tutorial del CLI para el walkthrough completo end-to-end.