buildsUpon Validation Rules and Constraints

Overview

This document specifies the validation rules and constraints for the buildsUpon attribute in code examples. These rules ensure data integrity and prevent common errors.

Validation Rules

Rule 1: Reference Validity

Requirement: All step IDs in buildsUpon must reference existing examples on the same page.

Validation:

For each example with buildsUpon:
  For each step_id in buildsUpon:
    Assert: step_id exists in codeExamples[].id on the same page

Error handling:

• Build-time: Warn or error if a referenced example doesn't exist
• Runtime: AI agents should validate and warn users about broken references

Example:

{{< clients-example set="tutorial" step="advanced" buildsUpon="nonexistent" >}}

❌ Invalid - "nonexistent" doesn't exist on this page

Rule 2: No Circular Dependencies

Requirement: Examples must not have circular dependencies (A→B→A).

Validation:

For each example:
  Build prerequisite chain by following buildsUpon
  Assert: No example appears twice in the chain

Error handling:

• Build-time: Error and fail the build if circular dependency detected
• Runtime: AI agents should detect and warn about circular dependencies

Example:

Example A: buildsUpon="B"
Example B: buildsUpon="A"

❌ Invalid - Circular dependency (A→B→A)

Rule 3: Case Sensitivity

Requirement: Step IDs in buildsUpon are case-sensitive and must match exactly.

Validation:

For each step_id in buildsUpon:
  Assert: step_id matches codeExamples[].id exactly (case-sensitive)

Example:

Step ID: "set_get"
buildsUpon: "Set_Get"  ❌ Invalid - case mismatch
buildsUpon: "set_get"  ✅ Valid

Rule 4: Format Constraints

Requirement: buildsUpon must be a comma-separated list of valid step IDs.

Validation:

buildsUpon format: "step_id1, step_id2, step_id3"
- Separated by commas
- Optional whitespace around commas
- No empty values
- No duplicate values

Examples:

"set_get"                    ✅ Valid - single dependency
"set_get, setnx_xx"          ✅ Valid - multiple dependencies
"set_get,setnx_xx"           ✅ Valid - no spaces
"set_get, setnx_xx, mset"    ✅ Valid - three dependencies
"set_get, , setnx_xx"        ❌ Invalid - empty value
"set_get, set_get"           ❌ Invalid - duplicate

Rule 5: Foundational Examples

Requirement: Foundational examples (introducing a concept for the first time) should NOT have buildsUpon.

Validation:

If example is foundational:
  Assert: buildsUpon is not present or empty

Guidance:

• First example in a tutorial: no buildsUpon
• Variations/extensions: include buildsUpon
• Advanced patterns: include buildsUpon

Rule 6: Ordering Constraint

Recommendation (not enforced): Foundational examples should appear before dependent examples.

Guidance:

Page structure:
1. Foundational examples (no buildsUpon)
2. Intermediate examples (buildsUpon="foundational")
3. Advanced examples (buildsUpon="intermediate" or multiple)

Build-Time Validation

The build system should validate buildsUpon during Hugo build:

1. Extract all examples from the page
2. For each example with buildsUpon:
   • Check that all referenced step IDs exist
   • Check for circular dependencies
   • Check format constraints
3. Report errors and fail the build if validation fails
4. Report warnings for ordering issues

Runtime Validation (AI Agents)

AI agents should validate buildsUpon when consuming metadata:

def validate_buildsupon(page_metadata):
    """Validate buildsUpon references and constraints."""
    examples = page_metadata.get('codeExamples', [])
    example_ids = {ex['id'] for ex in examples}
    
    for example in examples:
        builds_upon = example.get('buildsUpon', [])
        
        # Rule 1: Reference validity
        for dep_id in builds_upon:
            if dep_id not in example_ids:
                warn(f"{example['id']}: references non-existent {dep_id}")
        
        # Rule 2: Circular dependencies
        if has_circular_dependency(example['id'], examples):
            error(f"{example['id']}: circular dependency detected")
        
        # Rule 3: Case sensitivity (implicit in comparison)
        # Rule 4: Format constraints
        if not all(isinstance(dep, str) for dep in builds_upon):
            error(f"{example['id']}: invalid buildsUpon format")

Migration and Backward Compatibility

• Existing examples without buildsUpon: Treated as foundational (no change)
• Adding buildsUpon to existing examples: Safe operation, no breaking changes
• Removing buildsUpon: Safe operation, example becomes independent

Future Enhancements

Potential future improvements:

1. Cross-page references: Allow buildsUpon to reference examples on other pages
2. Conditional dependencies: Support "OR" dependencies (e.g., "understand A OR B")
3. Dependency metadata: Include reason for dependency in metadata
4. Automatic validation: Build-time validation with detailed error messages
5. Visualization: Generate dependency graphs for documentation