Taxonomy

The Taxonomy resource allows defining and structuring hierarchical concepts such as geographical locations (countries, regions), organizational levels of the educational system, or curriculum standards grouped by subject and level.

This structure is fundamental for organizing and filtering other resources within the system (such as rubrics and exercises). It is also the backbone of the CLI scaffolding pipeline, which uses taxonomy identifiers to discover, fetch, and auto-generate evaluation rubrics from official curriculum documents.

Schema

Metadata (metadata)

Field	Type	Required	Description
id	string	Yes	Unique identifier for the taxonomy (e.g., loc.es or std.intl).
type	string	Yes	The type of taxonomy. Common values: location_country, standard.
active	boolean	Yes	Indicates whether the taxonomy is active.
name	string	Yes	Human-readable name of the taxonomy (e.g., “Spain” or “International Standards”).
flag	string	No	(For locations only) Country flag emoji.
languages	string[]	No	List of supported languages (e.g., [es-ES]).
countryRef	string	No	Reference to which country it applies (e.g., global).

Specification (spec) - location_country Variant

When type: location_country, the spec block defines regions and organizational levels:

Field	Type	Description
regions	array	List of regions/states in the country. Each region contains id, name, active, languages, and flagAsset.
orgLevels	array	List of organizational levels (e.g., Primary, Secondary). Each contains id and name.

Specification (spec) - standard Variant

When type: standard, the spec block defines standards, levels, and subjects:

Field	Type	Description
standards	array	List of standards (e.g., IB, AP). Each contains id, name, active, as well as levels and subjects.
levels	array	(Within a standard) Educational levels covered (e.g., DP, MYP). Contains id, name, active.
subjects	array	(Within a standard) Subjects. Contains id, name, active, and applicableLevels (list of level ids).

Specification (spec) - bundle_course Variant

When type: bundle_course, the resource groups a full course offering under a single taxonomy node. This is the primary input for the CLI rubric scaffolding pipeline:

Field	Type	Description
displayName	string	Human-readable course name (e.g., “AP Spanish Language and Culture”).
taxonomyRef	string	Reference to the parent standard taxonomy (e.g., std.intl.ap.v1).
subject	string	Subject identifier (e.g., subj.intl.ap.spanish_language_and_culture).
educationLevel	string	Education level identifier (e.g., lvl.intl.ap.high).
units	array	Ordered list of course units. Each unit contains id, name, description, and suggested_hours.

Relationship to Rubrics

Taxonomy bundles are the source of truth for rubric generation. The taxonomy rubrics scaffold CLI command reads a bundle_course spec to derive the rubric structure:

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

Each unit in the bundle maps to one criterion in the generated rubric, inheriting id, name, description, and suggested_hours.

Usage Example

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/en/mad.svg
    - id: loc.es.cat
      name: Catalunya
      active: true
      languages: [ca-ES]
      flagAsset: assets/flags/en/cat.svg
  orgLevels:
    - id: org.lvl.es.infantil
      name: Infantil
    - id: org.lvl.es.primaria
      name: Primaria

Related CLI Commands

# Discover official source documents for a bundle
bash ce-cli.sh taxonomy sources discover --referenceCode bundle.us.ap.spanish_language.hl

# Download the curriculum PDF
bash ce-cli.sh taxonomy sources fetch --referenceCode bundle.us.ap.spanish_language.hl

# Generate rubric YAML (AI-powered levels from the PDF)
bash ce-cli.sh taxonomy rubrics scaffold --referenceCode bundle.us.ap.spanish_language.hl --ai true

See the CLI Tutorial for the full end-to-end walkthrough.