operations:
  create:
    description: "Add component to page hierarchy"
    input:
      required: [page_id, component_type, order, props]
      optional: [parent_id]
    output: ComponentHierarchy
    acl_required: ["component:create"]
    errors:
      - NOT_FOUND: "Page or parent component not found"
      - VALIDATION_ERROR: "Invalid component type"
      
  read:
    description: "Get component by ID"
    input:
      required: [id]
    output: ComponentHierarchy
    acl_required: ["component:read"]
    errors:
      - NOT_FOUND: "Component not found"
      
  update:
    description: "Update component"
    input:
      required: [id]
      optional: [parent_id, component_type, order, props]
    output: ComponentHierarchy
    acl_required: ["component:update"]
    errors:
      - NOT_FOUND: "Component not found"
      
  delete:
    description: "Delete component and its children"
    input:
      required: [id]
    output: boolean
    acl_required: ["component:delete"]
    cascade: true
    errors:
      - NOT_FOUND: "Component not found"
      
  get_tree:
    description: "Get full component tree for a page"
    input:
      required: [page_id]
    output: ComponentHierarchy[]
    acl_required: ["component:read"]
    hierarchical: true
    errors:
      - NOT_FOUND: "Page not found"
      
  reorder:
    description: "Reorder components within same parent"
    input:
      required: [components]
    output: boolean
    acl_required: ["component:update"]
    batch: true
    errors:
      - VALIDATION_ERROR: "Invalid order array"
      
  move:
    description: "Move component to new parent"
    input:
      required: [id, new_parent_id, order]
    output: ComponentHierarchy
    acl_required: ["component:update"]
    errors:
      - NOT_FOUND: "Component or parent not found"
      - VALIDATION_ERROR: "Cannot move to descendant"
