Resource Hierarchies

What are Resource Hierarchies?

Resource hierarchies allow you to model parent-child relationships between resources. A folder contains documents, a project contains tasks, an order contains line items. These relationships enable hierarchical permission propagation and structured queries.

Hierarchy Edge Properties

Property	Type	Description
`parentResourceId`	`string`	The parent resource
`childResourceId`	`string`	The child resource
`relationshipType`	`string?`	Type of relationship (e.g., “contains”, “references”)
`cascade`	`CascadeModeEnum`	Permission inheritance: `inherit` or `none`
`createdAt`	`string`	When the relationship was created

Cascade Modes

The cascade property controls how permissions propagate through the hierarchy:

Inherit

A permission patterned to a parent resource can grant access to that resource’s descendants:

curl -X POST 'https://api.example.com/resource-hierarchy' \
  -d '{
    "parentResourceId": "resource_folder_123",
    "childResourceId": "resource_doc_456",
    "relationshipType": "contains",
    "cascade": "inherit"
  }'

With cascade: "inherit", when a child resource is evaluated and direct RBAC denies, the engine walks up the inherit edges to the child’s ancestors. Access is granted if the subject holds a permission whose resourceType matches the child’s type (or *) and whose resourcePattern is an ancestor’s resource id.

This is not “folder-read permission implies document-read”. The granting permission must be typed to the child (or *) and patterned to the ancestor’s id—e.g. a document-typed (or *) read permission with resourcePattern: "resource_folder_123" grants read on documents beneath that folder. A permission typed folder does not satisfy a document evaluation.

None

No permission inheritance—child resources require explicit access:

curl -X POST 'https://api.example.com/resource-hierarchy' \
  -d '{
    "parentResourceId": "resource_issue_1",
    "childResourceId": "resource_issue_2",
    "relationshipType": "references",
    "cascade": "none"
  }'

With cascade: "none":

Parent access does not grant child access
Each resource requires its own permissions
Ideal for references, links, dependencies

Creating Resource Hierarchies

# Create a folder
curl -X POST 'https://api.example.com/resources' \
  -d '{
    "resourceTypeId": "rtype_folder",
    "ownerScopeId": "scope_engineering",
    "externalResourceId": "folder-123",
    "displayName": "Engineering Docs"
  }'

# Create a document
curl -X POST 'https://api.example.com/resources' \
  -d '{
    "resourceTypeId": "rtype_document",
    "ownerScopeId": "scope_engineering",
    "externalResourceId": "doc-456",
    "displayName": "API Design Doc"
  }'

# Link document to folder
curl -X POST 'https://api.example.com/resource-hierarchy' \
  -d '{
    "parentResourceId": "resource_folder_123",
    "childResourceId": "resource_doc_456",
    "relationshipType": "contains"
  }'

Resource Type Hierarchies

Before creating resource hierarchies, define which resource types can contain which:

# Folders can contain Documents
curl -X POST 'https://api.example.com/resource-type-hierarchy' \
  -d '{
    "parentTypeId": "rtype_folder",
    "childTypeId": "rtype_document"
  }'

# Folders can contain Folders (nested)
curl -X POST 'https://api.example.com/resource-type-hierarchy' \
  -d '{
    "parentTypeId": "rtype_folder",
    "childTypeId": "rtype_folder"
  }'

# Projects can contain Tasks
curl -X POST 'https://api.example.com/resource-type-hierarchy' \
  -d '{
    "parentTypeId": "rtype_project",
    "childTypeId": "rtype_task"
  }'

Hierarchical Permission Patterns

Pattern 1: Grant Access to a Folder’s Contents

Grant read on everything beneath a folder by patterning a permission to the folder’s id (typed to the child, or *). The engine applies it automatically when a document inside is evaluated:

curl -X POST 'https://api.example.com/permissions' \
  -d '{
    "scopeId": "scope_org",
    "action": "read",
    "resourceType": "document",
    "resourcePattern": "resource_folder_123",
    "key": "document:read:resource_folder_123"
  }'

// Evaluate the DOCUMENT directly — the engine walks the inherit edge up to the folder
const decision = await bedrock.evaluate({
  actor: { subjectId: "subject_jane", subjectType: "user" },
  scopeId: "scope_engineering",
  action: "read",
  resource: { resourceId: "resource_doc_456" }  // inside folder_123
});
// allowed via the folder-patterned permission

Pattern 2: Nested Inheritance

Inheritance walks the full ancestor chain, so a permission patterned to a top-level container reaches everything beneath it (as long as the edges are cascade: "inherit"):

# Read anything under the workspace root
curl -X POST 'https://api.example.com/permissions' \
  -d '{
    "scopeId": "scope_org",
    "action": "read",
    "resourceType": "*",
    "resourcePattern": "resource_workspace_root",
    "key": "*:read:resource_workspace_root"
  }'

Inheritance is driven by the ancestor resourcePattern, not a condition. There is no resource.parentId or subject.accessibleFolders in the condition context—don’t model hierarchy access with a logic condition.

Common Hierarchy Patterns

Document Management

Workspace
└── Folder
    ├── Document
    │   └── Comment
    └── Folder (nested)
        └── Document

# Define type hierarchy
curl -X POST 'https://api.example.com/resource-type-hierarchy/batch' \
  -d '[
    {"parentTypeId": "rtype_workspace", "childTypeId": "rtype_folder"},
    {"parentTypeId": "rtype_folder", "childTypeId": "rtype_folder"},
    {"parentTypeId": "rtype_folder", "childTypeId": "rtype_document"},
    {"parentTypeId": "rtype_document", "childTypeId": "rtype_comment"}
  ]'

Project Management

Project
├── Epic
│   └── Issue
│       └── Subtask
└── Sprint
    └── Issue (linked)

E-Commerce

Store
└── Category
    └── Product
        ├── Variant
        └── Review

Construction

Job Site
├── Work Order
│   └── Task
└── Daily Log
    └── Entry

Querying Hierarchies

# Get children of a resource
curl -X GET 'https://api.example.com/resources/resource_folder_123/children'

# Get parent of a resource
curl -X GET 'https://api.example.com/resources/resource_doc_456/parent'

# Get all descendants (recursive)
curl -X GET 'https://api.example.com/resources/resource_folder_123/descendants'

Relationship Types

Use relationshipType to distinguish different kinds of relationships:

Type	Use Case
`contains`	Parent physically contains child (folder → document)
`references`	Parent references child (issue → linked issue)
`owns`	Parent owns child (user → created documents)
`depends-on`	Parent depends on child (task → blocking task)

# Different relationship types
curl -X POST 'https://api.example.com/resource-hierarchy/batch' \
  -d '[
    {"parentResourceId": "folder_1", "childResourceId": "doc_1", "relationshipType": "contains"},
    {"parentResourceId": "issue_1", "childResourceId": "issue_2", "relationshipType": "references"},
    {"parentResourceId": "task_1", "childResourceId": "task_2", "relationshipType": "depends-on"}
  ]'

Best Practices

Define type hierarchies first

Always define resource type hierarchies before creating resource instance hierarchies.

Use meaningful relationship types

Choose relationship types that reflect your domain model.

Avoid deep nesting

Very deep hierarchies can impact query performance. Consider flattening when possible.

Consider permission implications

Plan how permissions will propagate through your hierarchy before building it.

Ancestor Traversal

When evaluating permissions with cascade: "inherit", the engine traverses ancestors:

# Get all ancestors of a resource
curl -X GET 'https://api.example.com/resource-hierarchy/ancestors/resource_doc_456'

Response:

[
  {
    "id": "resource_folder_123",
    "displayName": "Engineering Docs",
    "cascade": "inherit"
  },
  {
    "id": "resource_workspace_root",
    "displayName": "Workspace",
    "cascade": "inherit"
  }
]

The evaluation engine checks permissions on each ancestor until access is granted or all ancestors are exhausted.

Getting Started

Core Concepts

Resources

Tags

Delegation

Use Cases

Modeling Guides

Resource Hierarchies

What are Resource Hierarchies?

Hierarchy Edge Properties

Cascade Modes

Inherit

None

Creating Resource Hierarchies

Resource Type Hierarchies

Hierarchical Permission Patterns

Pattern 1: Grant Access to a Folder’s Contents

Pattern 2: Nested Inheritance

Common Hierarchy Patterns

Document Management

Project Management

E-Commerce

Construction

Querying Hierarchies

Relationship Types

Best Practices

Ancestor Traversal

Next Steps

Resource Scope Links

Resource Policies

​What are Resource Hierarchies?

​Hierarchy Edge Properties

​Cascade Modes

​Inherit

​None

​Creating Resource Hierarchies

​Resource Type Hierarchies

​Hierarchical Permission Patterns

​Pattern 1: Grant Access to a Folder’s Contents

​Pattern 2: Nested Inheritance

​Common Hierarchy Patterns

​Document Management

​Project Management

​E-Commerce

​Construction

​Querying Hierarchies

​Relationship Types

​Best Practices

​Ancestor Traversal

​Next Steps

Resource Scope Links

Resource Policies

What are Resource Hierarchies?

Hierarchy Edge Properties

Cascade Modes

Inherit

None

Creating Resource Hierarchies

Resource Type Hierarchies

Hierarchical Permission Patterns

Pattern 1: Grant Access to a Folder’s Contents

Pattern 2: Nested Inheritance

Common Hierarchy Patterns

Document Management

Project Management

E-Commerce

Construction

Querying Hierarchies

Relationship Types

Best Practices

Ancestor Traversal

Next Steps