---
title: Role
description: Role protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Role Schema (aka Business Unit / Org Unit)

Defines the organizational hierarchy (Reporting Structure).

COMPARISON:

- Salesforce: "Role" (Hierarchy for visibility rollup)

- Microsoft: "Business Unit" (Structural container for data)

- Kubernetes/AWS: "Role" usually refers to Permissions (we use PermissionSet for that)

ROLES IN OBJECTSTACK:

Used primarily for "Reporting Structure" - Managers see subordinates' data.

**NAMING CONVENTION:**

Role names MUST be lowercase snake_case to prevent security issues.

@example Good role names

- 'sales_manager'

- 'ceo'

- 'region_east_vp'

- 'engineering_lead'

@example Bad role names (will be rejected)

- 'SalesManager' (camelCase)

- 'CEO' (uppercase)

- 'Region East VP' (spaces and uppercase)

<Callout type="info">
**Source:** `packages/spec/src/identity/role.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { Role } from '@objectstack/spec/identity';
import type { Role } from '@objectstack/spec/identity';

// Validate data
const result = Role.parse(data);
```

---

## Role

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Unique role name (lowercase snake_case) |
| **label** | `string` | ✅ | Display label (e.g. VP of Sales) |
| **parent** | `string` | optional | Parent Role ID (Reports To) |
| **description** | `string` | optional |  |


---

