> For the complete documentation index, see [llms.txt](https://docs.openbrim.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openbrim.org/developers/llm-guides/ai-extends.md).
# Extends
## Overview
**Extends** is ParamML's mechanism for reusing and building upon existing objects. It implements **inheritance** - a core concept from Object-Oriented Programming (OOP).
**What you'll learn:**
* Basic Extends syntax
* Single and multiple inheritance
* Versioning library components
* Override mechanism (critical rules!)
* When to use Scoped="1"
* Top-level vs Group-level extends
* Type inheritance and compatibility
* Common patterns and best practices
***
## What is Extends?
The `Extends` attribute allows an object to inherit all parameters and sub-objects from one or more parent objects.
**Key concepts:**
* A **child** receives all parameters and sub-objects from its **parent(s)**
* Children can add new parameters and objects
* Children can override inherited content using `Override="1"`
* Extends is **transitive** (grandparent → parent → child)
* Extends supports **multiple inheritance** (multiple parents)
### Inheritance: The Underlying Concept
Inheritance means deriving a new object from an existing one. Think of it like:
* **Parent** = Base template
* **Child** = Specialized version with everything from parent + additions/changes
### Conceptual Example
```
Person
├── Employee
│ └── Engineer
└── Student
```
An **Engineer** includes all attributes from:
* Person (age, name)
* Employee (working\_hours, income)
* Engineer (field, position)
***
## Basic Syntax
Use the `Extends` attribute to inherit from another object:
```xml
```
**Critical rule:** Every object **must have** a `T` (Type) attribute, even when using Extends:
```xml
```
***
## Single Inheritance
### Example: Person → Employee → Engineer
**Base: Person**
```xml
```
**Child: Employee extends Person**
```xml
```
**Grandchild: Engineer extends Employee**
```xml
```
**Result:**
```
Person has: age, name
Employee has: age, name, working_hours, experience, income
Engineer has: age, name, working_hours, experience, income, field, position
```
***
## Multiple Inheritance
Use **array syntax** to extend from multiple parent objects:
```xml
```
### Example: Multiple Base Classes
```xml
```
**Best Practice:** Avoid duplicate parameter names across parent objects to prevent ambiguity.
***
## Versioning
Library components can have versions. Use `::v#` syntax:
```xml
```
### Version Syntax
```xml
```
**Rules:**
* ✅ Versioning applies **only to library components**
* ✅ No version = **latest version**
* ✅ Can mix versioned and non-versioned in array
* ❌ Cannot version local objects (in same file)
### Example
```xml
```
***
## Override="1"
`Override="1"` is used to **replace** content inherited from parent.
### Critical Rules
1. **Override is an object attribute** - can only be applied to objects, not parameters
2. **Two ways to override:**
* **A) Override at Extends level** (selective - only specified parameters)
* **B) Override named object in parent** (complete replacement - all parameters)
***
## Override at Extends Level (Selective Override)
When you use `Override="1"` at the Extends level, you **only override the parameters you define**. Other parameters are inherited as-is.
### Syntax
```xml
```
### Example
```xml
```
**Result:**
```
Child has:
- width = 150 (overridden)
- height = 200 (inherited)
- depth = 300 (inherited)
```
### Multiple Parameter Override
```xml
```
**Result:**
```
Child has:
- a = 10 (overridden)
- b = 2 (inherited)
- c = 30 (overridden)
- d = 4 (inherited)
```
***
## Override Named Object (Complete Replacement)
When you override a **named object** from the parent, you must **redefine all parameters** - nothing is inherited from the parent's version of that object.
### Syntax
```xml
```
### Example
```xml
```
**If you forget to redefine:**
```xml
```
**Result:** Employee.Info will only have `text`, not `status`.
***
## How to Override Parameters at Top Level
At `T="Project"` level, parameters cannot be overridden directly. You must:
1. **Group parameters in the parent**
2. **Override the group in the child**
### Wrong Approach
```xml
```
### Correct Approach
```xml
```
***
## Override Summary Table
| Override Location | Syntax | Must Redefine All? | Use Case |
| -------------------- | --------------------------------------------- | --------------------------- | --------------------- |
| **At Extends level** | `` | ❌ No - only what you define | Change few parameters |
| **Named object** | `` | ✅ Yes - all parameters | Replace entire object |
### Quick Decision Guide
**Want to change 1-2 parameters?**
```xml
```
**Want to completely replace an object?**
```xml
```
***
## Scoped="1"
`Scoped="1"` isolates the extended object's namespace.
### Rules
**Simple rule:**
* **Top level** (`T="Project"`): **No `Scoped="1"`**
* **Everything else**: **Use `Scoped="1"`**
### Top Level (No Scoped)
```xml
```
### Inside Objects (Use Scoped)
```xml
```
### Without Scoped (Top Level)
```xml
```
### With Scoped (Inside Object)
```xml
```
***
## When to Extend at Top vs Group Level
### Top Level (T="Project"): True Inheritance (IS-A)
Use when child **is a type of** parent:
```xml
```
**When to use:**
* True inheritance relationship
* Child is a specialized version of parent
* Type compatibility needed (see Type Inheritance and example below)
***
#### Type Compatibility Through Base Classes
A key reason for top-level inheritance is creating **type compatibility** - allowing input parameters to accept multiple related component types.
**The Problem**
```xml
```
**The Solution: Base Class**
Create a **base class** that both girder types extend:
```xml
```
**Usage**
```xml
```
**Why This Works**
```
Type hierarchy:
- BaseGirder
├── SteelIGirder (types: BaseGirder, SteelIGirder)
└── PrecastIGirder (types: BaseGirder, PrecastIGirder)
Parameter constraint: T="BaseGirder"
Accepts: Any object with BaseGirder type
Result: Both SteelIGirder and PrecastIGirder accepted ✅
```
**Pattern Summary**
**When you need a parameter to accept multiple component types:**
1. ✅ Create a **base class** with common interface (exported parameters)
2. ✅ Extend base class to specialized types
3. ✅ Use base class as parameter type: `T="BaseClass"`
4. ✅ All specialized types now accepted by parameter
**Benefits:**
* Single parameter definition works with multiple component types
* Type safety maintained (can't pass unrelated components)
* Common interface guaranteed through base class exports
* Easy to add new specialized types later
***
### Group Level (T="Group"): Reusing Logic (HAS-A)
Use when object **uses** parent's calculations:
```xml
```
**When to use:**
* Reusing calculations from library
* Not a true inheritance relationship
* Want to namespace the extended content
***
### Decision Guide
| Scenario | Use | Example |
| --------------------------- | ----------- | -------------------------------------- |
| Child is specialized parent | Top level | `SteelBeam` extends `Beam` |
| Using calculation library | Group level | Using `AASHTOCode` in `ColumnCheck` |
| Need type compatibility | Top level | `BaseGirder` accepted by `Cross_Frame` |
| Namespacing needed | Group level | Multiple calculations in same object |
***
## Transitive Inheritance
Inheritance is **transitive** - children inherit from entire ancestor chain.
### Example
```xml
```
**Result:**
```
Base has: a
Middle has: a, b
Child has: a, b, c
```
### With Overrides
```xml
```
**Result:**
```
Base.Config.value = 100
Middle.Config.value = 200
Child.Config.value = 300
```
**Process:**
1. Base is created
2. Middle extends Base, applies overrides
3. Child extends Middle (with its overrides), applies its own overrides
***
## Type Inheritance
A child inherits all **types** from its parent.
### Type Chain
```xml
```
### Why This Matters
Parameters with type constraints accept compatible types:
```xml
```
**Rule:** Child types are **compatible** with parent types (polymorphism).
***
## Extending Objects Inside Other Objects
You can extend objects at any level, not just top level.
### Example: Extending Inside Volume
```xml
```
***
## Common Patterns
### Pattern 1: Base Class with Specializations
```xml
```
### Pattern 2: Reusing Calculation Logic
```xml
```
### Pattern 3: Selective Parameter Override
```xml
```
### Pattern 4: Multiple Base Classes for Modularity
```xml
```
### Pattern 5: Version-Specific Extensions
```xml
```
***
## Extends vs Instances
**Critical distinction:**
| Feature | Extends (Inheritance) | T="..." (Instances) |
| ---------------- | -------------------------- | ------------------- |
| **Purpose** | Inherit structure | Create instance |
| **Syntax** | `Extends="Parent"` | `T="ComponentName"` |
| **Use with** | Core objects | Library components |
| **Common types** | `T="Project"`, `T="Group"` | User components |
| **Can combine?** | ❌ No | ❌ No |
### Extends (Inheritance)
```xml
```
**Use for:**
* ✅ True inheritance (is-a relationship)
* ✅ Reusing calculation logic
* ✅ Core objects (`T="Project"`, `T="Group"`, `T="Section"`)
### Instances (T="...")
```xml
```
**Use for:**
* ✅ Creating instances of library components
* ✅ Building compositions (has-a relationship)
* ✅ User-developed components
### Cannot Combine
```xml
```
**Rule:** Use **either** `Extends` (inheritance) **or** `T="ComponentName"` (instance), never both.
***
## Best Practices
### 1. Avoid Parameter Name Conflicts
**❌ Bad - duplicate parameters:**
```xml
```
**✅ Good - unique parameters:**
```xml
```
### 2. Use Scoped="1" Consistently
```xml
```
### 3. Use Versioning for Stability
```xml
```
### 4. Choose Override Strategy Wisely
```xml
```
### 5. Group Parameters for Overriding
```xml
```
### 6. Document Inheritance Chains
```xml
```
### 7. Choose Inheritance Level Wisely
```xml
```
### 8. Keep Inheritance Hierarchies Shallow
```xml
Base → Middle → Child
Base → L1 → L2 → L3 → L4 → L5 → Child
```
Deep hierarchies are harder to understand and maintain.
### 9. Remember Override Rules
**Quick reference card:**
```
Override at Extends level:
← Only overrides param1
← Other parameters inherited
Override named object:
← Must define param1
← Must define param2
← Nothing inherited from parent's Config
```
***
## Common Mistakes
### ❌ Mistake 1: Missing T Attribute
```xml
```
### ❌ Mistake 2: Trying to Override Parameters Directly
```xml
```
### ❌ Mistake 3: Forgetting to Redefine All When Overriding Object
```xml
```
### ❌ Mistake 4: Missing Scoped="1" Inside Objects
```xml
```
### ❌ Mistake 5: Combining Extends and Instance Creation
```xml
```
***
## Summary
### Key Concepts
| Concept | Description |
| -------------------- | -------------------------------------------------------- |
| **Extends** | Inherit parameters and objects from parent |
| **Multiple** | `Extends="[A, B, C]"` - inherit from multiple parents |
| **Versioning** | `Extends="Component::v3"` - use specific version |
| **Override="1"** | Replace inherited content (objects only, not parameters) |
| **Scoped="1"** | Namespace extended content (use except top level) |
| **Transitive** | Child gets everything from entire ancestor chain |
| **Type inheritance** | Child carries all parent types |
### Override Rules (Critical!)
| Override Type | Syntax | Redefine All? | Use When |
| ----------------- | ----------------------------------- | ---------------- | --------------------- |
| **Extends level** | `` | ❌ No - selective | Change few parameters |
| **Named object** | `` | ✅ Yes - complete | Replace entire object |
### When to Use
| Use Case | Syntax | Example |
| ------------------ | ---------------------- | ------------------------------ |
| True inheritance | Top-level Extends | `Column` extends `Base_Column` |
| Reuse calculations | Group-level Extends | Using `AASHTOCode` |
| Multiple bases | Array syntax | `Extends="[A, B, C]"` |
| Specific version | Version syntax | `Extends="Base::v5"` |
| Change few params | Extends-level Override | `` |
| Replace object | Named Override | `` |
### Rules to Remember
1. **Must have T attribute** - every object needs `T`, even with Extends
2. **Override is for objects** - cannot override parameters directly
3. **Two override behaviors** - selective (Extends level) vs complete (named object)
4. **Cannot combine** `Extends` and `T="ComponentName"` (instance)
5. **Use `Scoped="1"`** except at top level (`T="Project"`)
6. **Avoid conflicts** in multiple inheritance
7. **Version for stability**, latest for development
8. **Transitive** - inherit entire ancestor chain
9. **Type compatible** - child accepted where parent expected
***
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.openbrim.org/developers/llm-guides/ai-extends.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.