Syllabus Syntax Tree (syllst) - Unist-based type definitions and validation schemas for language learning syllabi
npm install @syllst/coreSyllabus Syntax Tree - Unist-based type definitions for language learning syllabi.
A framework-agnostic syntax tree schema for representing structured learning content, similar to other Unist-based formats like MDX AST or text syntax trees.
This package provides type definitions and validation schemas for representing language learning syllabi as structured data. It is designed to be language-agnostic and framework-independent.
- Unist-based schema for language-agnostic syllabus representation
- TypeScript types for all syllabus node types
- Zod schemas for runtime validation
- Type guards for runtime type checking
- Lightweight - only depends on @types/unist and zod
``bash`
pnpm add @syllst/core
or with npm:
`bash`
npm install @syllst/core
or with yarn:
`bash`
yarn add @syllst/core
`typescript
import type {
LessonAstNode,
GrammarRuleNode,
VocabularySetNode,
VocabularyItemNode,
ExampleNode,
ExampleSetNode,
ExerciseNode,
} from '@syllst/core/types';
// Use types for your own data structures
const lesson: LessonAstNode = {
type: 'lesson',
id: 'lesson-01',
title: 'Basic Greetings',
order: 1,
children: [],
};
`
`typescript
import { validateLesson, LessonAstNodeSchema } from '@syllst/core/schemas';
import type { LessonAstNode } from '@syllst/core/types';
const lesson: LessonAstNode = {
type: 'lesson',
id: 'lesson-01-greetings',
title: 'Basic Greetings',
difficulty: 'beginner',
cefrLevel: 'A1',
children: [],
};
const result = validateLesson(lesson);
if (!result.valid) {
console.error(result.errors);
}
`
All nodes follow the Unist specification:
`typescript`
import type {
SyllabusRoot,
LessonAstNode,
GrammarRuleNode,
VocabularySetNode,
VocabularyItemNode,
ExampleNode,
ExampleSetNode,
ExerciseNode,
CharacterSetNode,
CharacterItemNode,
DialogueNode,
DialogueTurnNode,
DialogueParticipant,
PhonologicalRuleNode,
RuleConditionNode,
SyllablePatternNode,
PatternExampleNode,
WritingPatternNode,
} from '@syllst/core/types';
| Type | Description |
|------|-------------|
| SyllabusRoot | Root node with meta and chapters |ChapterNode
| | Chapter containing sections/lessons |SectionNode
| | Section containing lessons |LessonAstNode
| | Complete lesson with content |GrammarRuleNode
| | Grammar explanation with examples |VocabularySetNode
| | Set of vocabulary items |VocabularyItemNode
| | Single vocabulary word |ExampleSetNode
| | Set of example sentences |ExampleNode
| | Single example sentence |ExerciseNode
| | Practice exercise |CharacterSetNode
| | Alphabet/character set |CharacterItemNode
| | Single character |DialogueNode
| | Conversation with turns |DialogueTurnNode
| | Single dialogue turn |PhonologicalRuleNode
| | Phonological rule (tone, sound change, etc.) |RuleConditionNode
| | Single condition→result case in a rule |SyllablePatternNode
| | Syllable structure pattern (live/dead, CV/CVC) |PatternExampleNode
| | Concrete example of a syllable pattern |WritingPatternNode
| | Writing system rule (positioning, stroke order) |ContentNode
| | Markdown/text content |MetadataNode
| | Key-value metadata |
| Type | Values |
|------|--------|
| CEFRLevel | A1, A2, B1, B2, C1, C2 |GrammarDifficulty
| | beginner, intermediate, advanced |CharacterType
| | consonant, vowel, tone-mark, number, symbol, diacritic, modifier, punctuation, radical, logograph, syllable-block (+ string escape hatch) |PhonologicalRuleType
| | tone, sound-change, assimilation, elision, liaison, sandhi (+ string escape hatch) |ExerciseType
| | fill-in-blank, multiple-choice, translation, etc. |ContentFormat
| | markdown, text, html, glost, glost-dialogue |
`typescript
import {
isLessonAstNode,
isGrammarRuleNode,
isVocabularySetNode,
isSyllabusRoot,
isPhonologicalRuleNode,
} from '@syllst/core/types';
if (isLessonAstNode(node)) {
// TypeScript knows node is LessonAstNode
console.log(node.title);
}
`
Runtime validation schemas for all node types:
`typescript
import {
validateNode,
validateLesson,
validateDialogue,
formatValidationErrors,
} from '@syllst/core/schemas';
// Validate any node
const result = validateNode(someNode);
if (!result.valid) {
console.log(formatValidationErrors(result.errors));
}
// Validate specific types
const lessonResult = validateLesson(lesson);
const dialogueResult = validateDialogue(dialogue);
// Strict mode throws on error
validateLesson(lesson, { strict: true });
`
Base Schemas:
| Schema | Description |
|--------|-------------|
| PointSchema | Unist position point (line, column, offset) |PositionSchema
| | Unist position (start, end) |CEFRLevelSchema
| | CEFR levels (A1-C2) |GrammarDifficultySchema
| | beginner, intermediate, advanced |ExerciseTypeSchema
| | fill-in-blank, multiple-choice, etc. |
Node Schemas:
| Schema | Description |
|--------|-------------|
| LessonAstNodeSchema | Complete lesson validation |GrammarRuleNodeSchema
| | Grammar rule with examples |VocabularySetNodeSchema
| | Vocabulary set with items |VocabularyItemNodeSchema
| | Single vocabulary item |DialogueNodeSchema
| | Dialogue with turns |DialogueTurnNodeSchema
| | Single dialogue turn |ExerciseNodeSchema
| | Exercise with questions/answers |ExampleNodeSchema
| | Example sentence |CharacterSetNodeSchema
| | Character/alphabet set |CharacterItemNodeSchema
| | Single character |PhonologicalRuleNodeSchema
| | Phonological rule |RuleConditionNodeSchema
| | Rule condition case |SyllablePatternNodeSchema
| | Syllable pattern |PatternExampleNodeSchema
| | Pattern example |WritingPatternNodeSchema
| | Writing system pattern |
`typescript
import {
getSchemaForNodeType,
validateNode,
validateLesson,
validateSyllabus,
validateDialogue,
validateBeforeContentLayer,
formatValidationErrors,
} from '@syllst/core/schemas';
// Get schema by node type
const schema = getSchemaForNodeType('lesson');
// Validate for ContentLayer generation
const { valid, errors } = validateBeforeContentLayer(lesson);
`
``
src/
├── types/
│ ├── nodes.ts # Unist node type definitions
│ ├── extensions.ts # Extension types (CMI5, SCORM, etc.)
│ └── index.ts # Re-exports
├── schemas/
│ ├── base.ts # Base Zod schemas (Point, enums)
│ ├── nodes.ts # Node Zod schemas
│ ├── extensions.ts # Extension Zod schemas
│ └── index.ts # Validation utilities
└── index.ts # Main exports
This package is designed to work with various processing and content packages:
- Processor packages - MDX parsing, transformation pipelines (separate packages)
- Content packages - Language-specific syllabi using this syntax (separate packages)
- Extension packages - CMI5, SCORM, xAPI integrations (separate packages)
`bash`
npm run build
`bash`
npm test
Test Coverage:
| Test Suite | Tests | Description |
|------------|-------|-------------|
| base.test.ts | 86 | Base schemas (Point, Position, enums, CharacterType, PhonologicalRuleType) |nodes.test.ts
| | 70 | Node schemas (lesson, dialogue, vocab, phonological rules, patterns, etc.) |index.test.ts
| | 41 | Validation functions and error formatting |
Total: 197 tests
`bash``
npm run typecheck
Contributions are welcome! Please feel free to submit a Pull Request.
MIT