Clarify default behavior: customizable defaults to true when not specified

Copilot · hotlong · Copilot · commit c9312eb8ba76 · 2026-01-09T08:33:22.000Z
Co-authored-by: hotlong &lt;50353452+hotlong@users.noreply.github.com&gt;
diff --git a/docs/spec/metadata-format.md b/docs/spec/metadata-format.md
@@ -79,7 +79,7 @@ Files should use **Snake Case** filenames (e.g., `project_tasks.object.yml`).
 | `description` | `string` | Internal description of the object. |
 | `fields` | `Map` | Dictionary of field definitions. |
 | `actions` | `Map` | Dictionary of custom action definitions. |
-| `customizable` | `boolean` | Whether this object can be modified or deleted. System objects (e.g., `user`, `session`) should be marked as `false`. Defaults to `true`. |
+| `customizable` | `boolean` | Whether this object can be modified or deleted. System objects (e.g., `user`, `session`) should be set to `false`. **Default: `true`** (if not specified, the object is customizable). |
 
 ## 4. Field Definitions
 
@@ -104,7 +104,7 @@ fields:
 | `searchable` | `boolean` | Hint to include this field in global search. |
 | `sortable` | `boolean` | Hint that this field can be used for sorting in UI. |
 | `description` | `string` | Help text or documentation for the field. |
-| `customizable` | `boolean` | Whether this field can be modified or deleted. System fields (e.g., `_id`, `createdAt`, `updatedAt`) should be marked as `false`. Defaults to `true`. |
+| `customizable` | `boolean` | Whether this field can be modified or deleted. System fields (e.g., `_id`, `createdAt`, `updatedAt`) should be set to `false`. **Default: `true`** (if not specified, the field is customizable). |
 
 ### 4.2 Supported Field Types
 
@@ -798,10 +798,45 @@ try {
 
 ### 9.6 Default Behavior
 
-If the `customizable` property is not specified:
-- **Objects**: Default to `true` (customizable)
-- **Fields**: Default to `true` (customizable)
+**When the `customizable` property is not specified, it defaults to `true` (customizable).**
 
-This ensures backward compatibility while allowing explicit protection of system metadata.
+This means:
+- **Objects without `customizable` property**: Can be modified and deleted
+- **Fields without `customizable` property**: Can be modified and deleted
+
+**Examples:**
+
+```yaml
+# Object without customizable - defaults to true (customizable)
+name: my_custom_object
+fields:
+  title:
+    type: text
+    # Field without customizable - defaults to true (customizable)
+  description:
+    type: textarea
+    # Field without customizable - defaults to true (customizable)
+```
+
+```yaml
+# Explicitly marking as non-customizable
+name: user
+customizable: false  # Must be explicitly set to false to protect
+fields:
+  email:
+    type: email
+    customizable: false  # Must be explicitly set to false to protect
+  createdAt:
+    type: datetime
+    customizable: false  # Must be explicitly set to false to protect
+  customField:
+    type: text
+    # No customizable property - defaults to true (customizable)
+```
+
+This default behavior ensures:
+1. **Backward Compatibility**: Existing objects and fields without the `customizable` property continue to work as before
+2. **Opt-in Protection**: System objects and fields must explicitly opt-in to protection by setting `customizable: false`
+3. **Safe Defaults**: User-defined metadata is customizable by default, only system metadata needs protection
 
 
diff --git a/packages/metadata/src/registry.ts b/packages/metadata/src/registry.ts
@@ -21,7 +21,7 @@ export class MetadataRegistry {
         // Check if the metadata is customizable before allowing unregister
         if (type === 'object') {
             const existing = this.getEntry(type, id);
-            if (existing && existing.content.customizable === false) {
+            if (existing && !this.isObjectCustomizable(existing.content)) {
                 throw new Error(`Cannot delete system object '${id}'. This object is marked as non-customizable.`);
             }
         }
@@ -35,7 +35,7 @@ export class MetadataRegistry {
             for (const [id, meta] of map.entries()) {
                 if (meta.package === packageName) {
                     // Check if the metadata is customizable before allowing unregister
-                    if (type === 'object' && meta.content.customizable === false) {
+                    if (type === 'object' && !this.isObjectCustomizable(meta.content)) {
                         throw new Error(`Cannot unregister package '${packageName}'. It contains non-customizable object '${id}'.`);
                     }
                     entriesToDelete.push(id);
@@ -63,8 +63,31 @@ export class MetadataRegistry {
         return this.store.get(type)?.get(id);
     }
 
+    /**
+     * Helper to check if an object is customizable.
+     * If customizable property is not specified, defaults to true.
+     * @param obj The object configuration to check
+     * @returns true if object is customizable (can be modified/deleted)
+     */
+    private isObjectCustomizable(obj: any): boolean {
+        // Explicitly handle undefined: if not specified, default to true (customizable)
+        return obj.customizable !== false;
+    }
+
+    /**
+     * Helper to check if a field is customizable.
+     * If customizable property is not specified, defaults to true.
+     * @param field The field configuration to check
+     * @returns true if field is customizable (can be modified/deleted)
+     */
+    private isFieldCustomizable(field: any): boolean {
+        // Explicitly handle undefined: if not specified, default to true (customizable)
+        return field.customizable !== false;
+    }
+
     /**
      * Validates if an object can be modified based on its customizable flag.
+     * Objects without the customizable property default to true (customizable).
      * @param objectName The name of the object to check
      * @returns true if the object can be modified, throws an error if not
      */
@@ -74,7 +97,7 @@ export class MetadataRegistry {
             return true; // Object doesn't exist yet, allow creation
         }
         
-        if (entry.content.customizable === false) {
+        if (!this.isObjectCustomizable(entry.content)) {
             throw new Error(`Cannot modify system object '${objectName}'. This object is marked as non-customizable.`);
         }
         
@@ -83,6 +106,7 @@ export class MetadataRegistry {
 
     /**
      * Validates if a field can be modified based on its customizable flag.
+     * Fields without the customizable property default to true (customizable).
      * @param objectName The name of the object containing the field
      * @param fieldName The name of the field to check
      * @returns true if the field can be modified, throws an error if not
@@ -98,7 +122,7 @@ export class MetadataRegistry {
             return true; // Field doesn't exist yet, allow creation
         }
         
-        if (field.customizable === false) {
+        if (!this.isFieldCustomizable(field)) {
             throw new Error(`Cannot modify system field '${fieldName}' on object '${objectName}'. This field is marked as non-customizable.`);
         }
         
diff --git a/packages/metadata/test/customizable.test.ts b/packages/metadata/test/customizable.test.ts
@@ -8,6 +8,85 @@ describe('Metadata Customizable Protection', () => {
         registry = new MetadataRegistry();
     });
 
+    describe('Default behavior when customizable is not specified', () => {
+        it('should treat objects without customizable property as customizable (default: true)', () => {
+            const objectWithoutFlag: ObjectConfig = {
+                name: 'default_object',
+                fields: {}
+                // customizable is NOT specified - should default to true
+            };
+
+            registry.register('object', {
+                type: 'object',
+                id: 'default_object',
+                content: objectWithoutFlag
+            });
+
+            // Should allow validation (no error thrown)
+            expect(registry.validateObjectCustomizable('default_object')).toBe(true);
+
+            // Should allow unregister (no error thrown)
+            expect(() => {
+                registry.unregister('object', 'default_object');
+            }).not.toThrow();
+        });
+
+        it('should treat fields without customizable property as customizable (default: true)', () => {
+            const objectWithDefaultFields: ObjectConfig = {
+                name: 'test_object',
+                fields: {
+                    normalField: {
+                        type: 'text'
+                        // customizable is NOT specified - should default to true
+                    }
+                }
+            };
+
+            registry.register('object', {
+                type: 'object',
+                id: 'test_object',
+                content: objectWithDefaultFields
+            });
+
+            // Should allow field modification (no error thrown)
+            expect(registry.validateFieldCustomizable('test_object', 'normalField')).toBe(true);
+        });
+
+        it('should only protect when explicitly set to false', () => {
+            const mixedObject: ObjectConfig = {
+                name: 'mixed_object',
+                // customizable not specified - defaults to true
+                fields: {
+                    defaultField: {
+                        type: 'text'
+                        // not specified - defaults to true
+                    },
+                    protectedField: {
+                        type: 'text',
+                        customizable: false  // explicitly protected
+                    }
+                }
+            };
+
+            registry.register('object', {
+                type: 'object',
+                id: 'mixed_object',
+                content: mixedObject
+            });
+
+            // Object is customizable
+            expect(registry.validateObjectCustomizable('mixed_object')).toBe(true);
+            
+            // Default field is customizable
+            expect(registry.validateFieldCustomizable('mixed_object', 'defaultField')).toBe(true);
+            
+            // Protected field is not customizable
+            expect(() => {
+                registry.validateFieldCustomizable('mixed_object', 'protectedField');
+            }).toThrow(/Cannot modify system field 'protectedField'/);
+        });
+    });
+
     describe('Object-level customizable flag', () => {
         it('should allow registering and unregistering customizable objects', () => {
             const customObject: ObjectConfig = {
