Managing Node Types

Node types are the building blocks of your structure—they define what kinds of content exist in your curriculum. Each node type represents a container or content type like Course, Unit, Lesson, Activity, or Assessment.

Before You Begin

You need:

• Admin role in your account
• An existing structure to add node types to
• Clear understanding of your content hierarchy
• List of content types you'll need (what containers exist in your curriculum)

If you don't have a structure yet, see Designing Structures.

What is a Node Type?

A node type defines:

• Display name: What authors see ("Lesson", "Activity")
• System name: API identifier (snake_case, immutable)
• Hierarchy role: Can it be a root? Which types can it contain?
• Attributes: What data it captures (via bundles or direct attributes)
• Visual identity: Icon for easy recognition

Think of node types as templates for content nodes. A "Lesson" node type defines what all lessons look like; actual lessons are content nodes created from that template.

Example:

Node Type: Lesson
├── Display Name: "Lesson"
├── System Name: "lesson" (used in API)
├── Is Root: No (must be inside a Unit)
├── Attributes: Title, Description, Duration, Learning Objectives
└── Allowed Children: Activity, Assessment


Creating a Node Type

Step 1: Open Your Structure

1. Navigate to Schema → Structures
2. Click on the structure you want to modify
3. You'll see the Structure Builder with:
   • Left panel: List of existing node types
   • Right panel: Hierarchy preview

Step 2: Add Node Type

1. Click Add Node Type button in the left panel
2. The Add Node Type form appears inline or in a modal
3. Fill out the fields (explained below)
4. Click Save Node Type

After creation:
- The new node type appears in the list immediately (via Turbo Stream)
- The hierarchy preview updates to show the new type
- The node type is ready to configure further

Step 3: Configure the Node Type

Node types require several fields:

Display Name (Required)

The human-readable name shown to authors.

Best practices:
- Use title case: "Course", "Unit", "Lesson"
- Be specific: "Learning Activity" not just "Activity"
- Match familiar terminology for your authors

Examples:
- ✅ "Course", "Unit", "Lesson", "Activity"
- ✅ "Learning Module", "Topic", "Exercise"
- ❌ "Type1", "Container", "Thing"

System Name (Required)

The API identifier in snake_case. This is auto-generated from the display name but can be edited.

Important rules:
- ⚠️ Cannot be changed after creation
- Must be unique within the structure
- Must be snake_case (lowercase letters, numbers, underscores)
- Used in API calls and internal references

Auto-generation:
- Type "Course Overview" in Display Name
- System Name auto-fills with "course_overview"
- You can manually edit before saving

Examples:
- Display Name: "Course" → System Name: "course"
- Display Name: "Learning Activity" → System Name: "learning_activity"
- Display Name: "Assessment (Formative)" → System Name: "assessment_formative"

Why it's immutable:
API clients and integrations depend on stable identifiers. Changing system_name after creation would break existing code.

Description (Optional)

Help text explaining when and how to use this node type.

What to include:
- Purpose of this type
- When authors should use it
- Any special considerations

Example:
```
Lesson - Single class period of instruction

Use for a complete lesson that can be taught in one class period.
Should include: introduction, instruction, practice, and closure.
Typically 45-60 minutes.
```

Icon (Optional)

Visual identifier for the node type. Can be an emoji or icon name.

Options:
- Emoji: 📚, 📖, 📝, 🎯, 🧪
- Icon names from available set: book, folder, document, collection, academic, lesson, activity, page, chapter, unit

Tips:
- Use consistent icon themes
- Pick icons that make sense at a glance
- Avoid similar icons for different types

Examples:
- Course: 📚 or book
- Unit: 📂 or folder
- Lesson: 📖 or lesson
- Activity: ✏️ or activity
- Assessment: 📝 or document

Is Root Type (Checkbox)

Determines if this type can be created at the top level of a curriculum (with no parent).

When to check "Is Root Type":
- Course (yes - curricula start with courses)
- Unit (no - units must be inside courses)
- Lesson (no - lessons must be inside units)
- Activity (no - activities must be inside lessons)

Rules:
- At least one node type must be a root (you cannot unmark the last root)
- Multiple root types are allowed (e.g., both "Course" and "Program" can be roots)
- Root types show a blue "root" badge in the list

Example configurations:

Single root:

Course (root) → Unit → Lesson → Activity


Multiple roots:

Course (root) → Unit → Lesson
Program (root) → Module → Session


Why this matters:
When authors create content, they can only create root-type nodes at the top level. Non-root types must be created inside other nodes.

Editing Node Types

Opening the Editor

1. In the Structure Builder, click on a node type in the left panel list
2. The right panel switches from Hierarchy Preview to Node Type Details
3. You'll see an editable form with all node type properties

Editable Fields

The following fields can be changed after creation:

Autosave Behavior

Node type details use autosave with 1-second debounce:

How it works:
1. Change a field value
2. Stop typing for 1 second
3. "Saving..." indicator appears
4. AJAX request saves the change
5. "All changes saved" confirmation appears

Visual feedback:
- Saving...: Gray spinner icon
- All changes saved: Green checkmark
- Failed to save: Red X with retry button

For checkboxes (like "Is Root Type"):
- Save triggers immediately on change
- No debounce for checkbox toggles

System Name is Read-Only

Once created, the system name cannot be changed. You'll see:

System Name
course

System name cannot be changed after creation

Why?
Changing the API identifier would break:
- API integrations
- Content references
- External systems using this structure

If you need to change it:
1. Create a new node type with the correct system name
2. Migrate content from old to new type (manual process)
3. Delete the old node type

Validation Errors

If you make an invalid change, autosave will:

1. Show "Failed to save" error
2. Display the validation message
3. Revert the field to its previous value (for checkboxes)

Example:
Trying to unmark the last root type shows:

❌ Failed to save
At least one root type is required per structure


The checkbox automatically reverts to checked.

Configuring Hierarchy Rules

Hierarchy rules determine which node types can contain which other types. This is how you build your content tree structure.

Allowed Children Section

When viewing a node type's details, scroll to the Allowed Children section. You'll see:

• Checkboxes for each other node type in the structure
• Currently allowed children are checked
• Bulk selection options ("Allow All", "Allow None")

Example:
For "Course" node type, you might see:
```
Allowed Children
Select which node types can be added inside a Course.

☐ Unit
☐ Lesson
☐ Assessment
```

Adding Allowed Children

1. Check the box next to the child type (e.g., check "Unit")
2. The relationship saves immediately (autosave)
3. "Saved" confirmation appears
4. Hierarchy preview updates to show the relationship

After allowing "Unit" as a child of "Course":
- Authors can create Units inside Courses
- The hierarchy preview shows: Course → Unit

Removing Allowed Children

1. Uncheck the box next to the child type
2. The relationship is removed immediately
3. Existing content is unaffected (orphaned nodes remain valid)
4. Authors cannot create new children of that type

Important:
Removing an allowed child does not delete existing content nodes. Content remains intact, but authors can't add new children of that type.

Self-Reference Prevention

Node types cannot contain themselves. The current node type is excluded from the checkboxes.

Example:
When viewing "Unit", you won't see "Unit" in the Allowed Children list—this prevents infinite nesting.

Circular Reference Warning

The system detects circular hierarchies but allows them with a warning.

Example of circular hierarchy:

Course allows Unit
Unit allows Lesson
Lesson allows Course (circular!)


What happens:
- You can check "Course" as an allowed child of "Lesson"
- A warning appears: "⚠️ This configuration creates a circular hierarchy"
- The relationship is saved anyway (soft warning, not blocking)
- Consider if this is intentional

When circular hierarchies might be valid:
- Self-nesting modules (Module can contain Module)
- Flexible content libraries
- Adaptive learning paths

When to avoid:
- Linear progressions (Course → Unit → Lesson)
- Fixed depth structures

Bulk Selection

For structures with many node types:

Allow All:
- Click "Allow All" button
- All checkboxes are checked
- Saves immediately
- Use when creating a flexible, anything-goes structure

Allow None:
- Click "Allow None" button
- All checkboxes are unchecked
- Saves immediately
- Creates a leaf node (cannot contain children)

Example use case:
"Activity" node type → Click "Allow None" → Activities become leaf nodes (no children allowed)

Hierarchy Preview Updates

After changing allowed children, the Hierarchy Preview refreshes to show:

• New parent-child relationships
• Updated tree structure
• Which types can nest where

Adding Attributes to Node Types

Node types get their attributes from two sources:

1. Attribute Bundles (recommended for reusable attributes)
2. Direct Attributes (for type-specific fields)

Using Attribute Bundles

Bundles are pre-defined sets of attributes that can be applied to multiple node types.

To apply a bundle:
1. View the node type details
2. Navigate to the Bundles section (if available in UI)
3. Select from available bundles
4. The bundle's attributes are now available on content nodes of this type

See Attribute Bundles for creating bundles.

Direct Attributes

Direct attributes are added to a single node type only (not shared via bundle).

When to use direct attributes:
- Type-specific fields unique to one node type
- Quick prototyping before creating a bundle
- Attributes that don't need reuse

When to use bundles instead:
- Attributes used across multiple node types
- Organizational consistency
- Easier updates (change bundle affects all types)

See the implementation details in Attribute Bundles.

Reordering Node Types

The order of node types affects how they appear in the Structure Builder list.

To reorder:
1. In the Structure Builder, find the node type to move
2. Use the drag handle or reorder controls
3. Move up or down in the list
4. Position saves automatically via acts_as_list

Order affects:
- Visual presentation in the admin UI
- Author experience when selecting types
- No impact on actual content hierarchy

Deleting Node Types

When You Can Delete

You can delete a node type if:

• No content nodes exist of that type
• You have Admin role
• It's not the last root type in the structure

When You Cannot Delete

You cannot delete if:

• Content nodes exist using this type (must delete content first)
• It's the last root type (structure requires at least one root)
• You don't have Admin permissions

How to Delete

1. Open the node type in the Structure Builder
2. Scroll to the bottom of the details panel
3. Look for the Delete Node Type button

If you see a warning instead:

⚠️ Cannot delete: 47 content nodes use this type


You must delete or migrate all content nodes of this type first.

If you see the button:
1. Click Delete Node Type
2. Confirm the deletion
3. The node type is removed from the structure
4. Hierarchy preview updates
5. All allowed child relationships are removed

⚠️ Warning: Deletion is permanent and cannot be undone.

What Gets Deleted

• The node type definition
• All allowed child relationships involving this type
• All attribute definitions directly on this type

What is NOT Deleted

• Content nodes (deletion is blocked if content exists)
• Attribute bundles applied to this type (bundles remain for other types)
• The structure itself

Alternative to Deletion

Instead of deleting:

Hide by renaming:
- Rename to "DEPRECATED - [Name]"
- Document why it's deprecated
- Prevent new content creation (remove from allowed children)

Migrate content first:
- Create a replacement node type
- Manually move content to the new type
- Delete the old type once empty

Node Types in Structure Variants

If your structure is a variant (inherits from a parent structure), node types behave differently.

Inherited Node Types

Characteristics:
- Defined in parent structure
- Appear in the effective schema
- Cannot be edited or deleted (inherited from base)
- Show a source indicator

What you can do:
- View details (read-only)
- See attributes and allowed children
- Add variant-owned children to inherited parents

What you cannot do:
- Edit display name, description, icon
- Change "Is Root Type" setting
- Delete the node type

Indicator in UI:
If you try to edit an inherited node type, you'll see:

❌ Cannot modify inherited node type.
Inherited from base - cannot remove.


Adding Node Types to Variants

Variants can add new node types not in the parent:

1. Open the variant structure
2. Click Add Node Type
3. Create the new type (as normal)
4. The type exists only in this variant

Example:
- Base structure: Course → Unit → Lesson
- Science variant: Course → Unit → Lesson → Lab Activity (added in variant)

System name uniqueness:
When adding to a variant, the system name must be unique across:
- This variant's own node types
- All ancestor structures' node types

Error if duplicate:

System name already exists in base structure 'K-12 Mathematics'


Allowed Children in Variants

Variants can add allowed children to inherited parent types:

Example:
- Base: "Lesson" allows "Activity"
- Variant: "Lesson" also allows "Lab Activity" (variant-owned child)

Restrictions:
- Can only add variant-owned children to inherited parents
- Cannot remove inherited allowed children
- Inherited relationships remain read-only

Best Practices

Start with Core Types

Begin with 3-4 essential types:
- Root type (Course, Program)
- Mid-level (Unit, Module)
- Leaf content (Lesson, Activity)
- Optional: Assessment

Expand later:
- Add specialized types as needs emerge
- Don't over-engineer upfront
- Keep it simple until you understand real usage

Why: Too many types confuse authors and create maintenance burden.

Use Clear, Descriptive Names

Good names:
- ✅ "Course" (everyone knows what this means)
- ✅ "Learning Activity" (clear purpose)
- ✅ "Formative Assessment" (specific type)

Poor names:
- ❌ "Container1" (meaningless)
- ❌ "CA" (abbreviations unclear)
- ❌ "Thing" (too vague)

Why: Authors see these names daily. Clarity matters.

Document with Descriptions

Include in description:
- Purpose: "Single class period lesson"
- When to use: "Use for 45-60 minute instruction blocks"
- Structure: "Should include: intro, instruction, practice, closure"

Example:
```
Unit - Multi-week instructional sequence

A unit is a collection of lessons organized around a topic or
set of related standards. Typically 2-4 weeks of instruction.

Should contain:
- 5-10 lessons
- Formative assessments
- Summative assessment at end
```

Think About Hierarchy Before Creating

Sketch it out:

Course (root)
└── Unit
└── Lesson
├── Activity
└── Assessment


Ask:
- What's the top level? (Course)
- What contains what? (Unit contains Lessons)
- Which types are leaves? (Activity, Assessment)

Create types in order:
1. Root types first (Course)
2. Mid-level types (Unit)
3. Leaf types (Lesson, Activity)
4. Configure allowed children last

Why: Building hierarchy top-down is clearer than bottom-up.

Use Consistent Icons

Pick a theme:
- Academic: 📚 Course, 📂 Unit, 📖 Lesson
- Folders: 🗂️ Course, 📁 Unit, 📄 Lesson
- Abstract: 🎯 Course, 🔷 Unit, 🔹 Lesson

Avoid:
- ❌ Mixing themes (📚 Course, 🍎 Unit, 🚀 Lesson)
- ❌ Similar icons for different types (📄 Lesson, 📃 Activity)
- ❌ Too many emojis (distracting)

Plan for Growth

Design for future types:
- Leave room in hierarchy for specialization
- Use bundles for attributes (easier to extend)
- Consider variants for regional needs

Example:
Instead of:

Lesson → Activity (rigid)


Use:

Lesson → [Activity OR Assessment OR Lab] (room to grow)


Test with Sample Content

After configuring node types:

1. Create a test curriculum
2. Add sample content using each type
3. Verify hierarchy rules work correctly
4. Confirm attributes appear as expected
5. Check author experience

If it's confusing, simplify before rollout.

Common Questions

Can I change a node type's system name after creation?

No. System names are immutable API identifiers. If you need to change it, create a new node type, migrate content, and delete the old one.

What happens to existing content when I delete a node type?

You cannot delete a node type if content exists. You must delete or migrate all content nodes of that type first.

Can I have multiple root types?

Yes. Multiple root types are allowed. Examples: "Course" and "Program" can both be roots, letting authors choose which to create at the top level.

Why can't I uncheck "Is Root Type"?

At least one node type must be a root. If this is the only root type, you cannot unmark it. Create or mark another root type first.

What happens when I remove an allowed child?

Existing content is unaffected. Authors simply can't create new children of that type. Existing child nodes remain valid.

Can I copy node types from another structure?

Not automatically. You must manually recreate the node type configuration. Consider using structure cloning or variants instead.

How many node types should I have?

Typical:
- Simple: 3-4 types (Course → Unit → Lesson)
- Moderate: 5-7 types (adds Activities, Assessments)
- Complex: 8-12 types (multiple activity types, specialized content)

Avoid: 20+ types unless absolutely necessary. More types = more complexity for authors.

Can authors see node types?

Authors see node types when creating content ("Add Lesson", "Add Activity"). They don't manage the types themselves—that's an admin function.

Can I rename a node type after creation?

Yes, you can change the Display Name. The System Name remains immutable. The display name is what authors see, so renaming won't break anything.

What's the difference between a node type and a content node?

• Node Type: Template/definition (like a class in programming)
• Content Node: Actual content instance (like an object of that class)

Example: "Lesson" is a node type. "Adding Two-Digit Numbers" is a content node of type Lesson.

Troubleshooting

"Cannot delete: X content nodes use this type"

Solution:
1. Navigate to Content → Curricula
2. Find curricula using this structure
3. Delete all content nodes of this type
4. Return to node type and try deletion again

Alternative: If you can't delete content, don't delete the node type. Rename it to "DEPRECATED" instead.

"System name has already been taken"

Solution:
- Choose a different system name
- Check existing node types in this structure for conflicts
- For variants: check parent structures for conflicts

Changes aren't saving

Check:
- Do you have Admin role? (Authors/Editors cannot edit structures)
- Is your internet connection active?
- Look for validation errors in red text
- Try refreshing the page and re-opening the node type

"At least one root type is required"

Solution:
- You're trying to unmark the last root type
- Create or mark another node type as root first
- Then you can unmark this one

Hierarchy preview doesn't update

Solution:
- Click outside the node type details to return to hierarchy preview
- Refresh the structure page
- Changes should appear after saving allowed children

Autosave shows "Failed to save"

Possible causes:
1. Validation error (check error message)
2. Network issue (check connection)
3. Session expired (refresh and log in again)

Solution:
- Read the error message
- Fix the validation issue
- Click "Retry" if network-related

Cannot find node type I just created

Check:
- Scroll down in the node types list (it may be at the end)
- Verify you're viewing the correct structure
- Refresh the page

Allowed children checkboxes are disabled

Reason:
You have Author, Editor, or Viewer role. Only Admins can modify structure settings.

Solution:
Contact your account administrator for proper permissions.

Next Steps

After configuring node types:

1. Attribute Bundles - Add attributes to capture data
2. Designing Structures - Complete structure design
3. Creating Curricula - Use your structure to build content

Related Documentation:
- Admin Overview - Your administrative capabilities
- Designing Structures - Structure design patterns
- Attribute Bundles - Create reusable attributes
- Team Management - Manage user roles