URN Taxonomy Reference

Complete reference for Cascade URN (Uniform Resource Name) identifiers

URNs uniquely identify resources in Cascade Platform. This page documents all resource types and naming conventions.

URN Format


urn:cascade:resource_type:resource_name[:version]

Examples:
├── urn:cascade:activity:validate_order
├── urn:cascade:policy:loan_approval:v2
├── urn:cascade:schema:application_form
└── urn:cascade:service:notification

Component	Purpose	Example
`urn`	Scheme (always “urn”)	`urn`
`cascade`	Authority	`cascade`
`resource_type`	Type of resource	`activity`, `policy`, `schema`
`resource_name`	Unique name	`validate_order`
`version`	Optional version	`v1`, `v2`

Resource Types

Activities

URN Pattern: urn:cascade:activity:*

Activities are Go functions executable by workflows.


urn:cascade:activity:validate_order
urn:cascade:activity:check_credit
urn:cascade:activity:send_email

Naming:

Use snake_case
Describe action verb first: validate_, check_, send_
Be specific: check_credit not just check

Policies

URN Pattern: urn:cascade:policy:*

Policies are business rule definitions (OPA, DMN).


urn:cascade:policy:loan_approval
urn:cascade:policy:risk_assessment:v2
urn:cascade:policy:compliance_check

Naming:

Use snake_case
Describe what is being evaluated: approval, assessment, check
Version management: :v1, :v2 for breaking changes

Schemas

URN Pattern: urn:cascade:schema:*

Schemas are JSON Schema definitions for validation and UI.


urn:cascade:schema:application_form
urn:cascade:schema:loan_application:v3
urn:cascade:schema:address

Naming:

Use snake_case
Name what data: application_form, loan_details
Versioning: :v1, :v2 for schema changes

Services

URN Pattern: urn:cascade:service:*

Services are internal platform services.


urn:cascade:service:notification
urn:cascade:service:audit_log
urn:cascade:service:template_engine

Versioning Strategy

Version Numbers


urn:cascade:resource:name:v1       # Version 1 (default)
urn:cascade:resource:name:v2       # Version 2 (breaking change)
urn:cascade:resource:name          # Resolved to latest

When to Version

MAJOR (breaking change) - Create v2:

Policy: Changed input/output shape
Schema: Removed or renamed field
Activity: Changed function signature

MINOR (backward compatible):

Activity: Added optional parameter
Policy: Added new rule (same outputs)
Schema: Added optional field

NO VERSION CHANGE:

Bug fix only
Performance improvement
Logic refinement (same interface)

Migration Path


# Old workflows use v1
- resource: urn:cascade:policy:approval:v1
 
# New workflows use v2
- resource: urn:cascade:policy:approval:v2
 
# Both can coexist
# Default (no version) = latest = v2
- resource: urn:cascade:policy:approval  # → v2

Naming Conventions

Activity Names


✅ urn:cascade:activity:validate_order
✅ urn:cascade:activity:check_credit
✅ urn:cascade:activity:send_notification

❌ urn:cascade:activity:order_validation  (noun first)
❌ urn:cascade:activity:validateOrder     (camelCase)
❌ urn:cascade:activity:validate          (too generic)

Pattern: verb + noun, snake_case

Policy Names


✅ urn:cascade:policy:loan_approval
✅ urn:cascade:policy:fraud_detection
✅ urn:cascade:policy:compliance_rules

❌ urn:cascade:policy:approve_loan     (verb first)
❌ urn:cascade:policy:LoanApproval     (PascalCase)

Pattern: subject + action, snake_case

Schema Names


✅ urn:cascade:schema:application_form
✅ urn:cascade:schema:customer_profile
✅ urn:cascade:schema:address

❌ urn:cascade:schema:ApplicationForm   (PascalCase)
❌ urn:cascade:schema:form_application  (reversed)

Pattern: noun + descriptor, snake_case

Built-in URNs

System Activities

URN	Purpose
`urn:cascade:activity:noop`	No operation
`urn:cascade:activity:log`	Log message
`urn:cascade:activity:sleep`	Sleep/wait

System Policies

URN	Purpose
`urn:cascade:policy:allow_all`	Always allow
`urn:cascade:policy:deny_all`	Always deny

URN Resolution

How URNs Are Resolved


1. Check URN format
   urn:cascade:activity:my_activity
   ↓
2. Look up in registry
   Activities table → find implementation
   ↓
3. Load resource (activity, policy, schema)
   ↓
4. Execute/use in workflow

Unresolved URNs


- resource: urn:cascade:activity:nonexistent
 
# Error:
# ERR_INVALID_URN: Activity 'urn:cascade:activity:nonexistent' not found

Best Practices

✅ DO:

Use descriptive names
Follow snake_case convention
Version breaking changes
Document URNs in code
Use consistent prefixes

❌ DON’T:

Use camelCase or PascalCase
Create generic names
Reuse names across types
Change URN after deployment
Use special characters

Quick Reference

Type	Format	Example
Activity	`activity:verb_noun`	`activity:validate_order`
Policy	`policy:noun_action`	`policy:loan_approval`
Schema	`schema:noun_descriptor`	`schema:application_form`
Service	`service:noun`	`service:notification`

Updated: October 29, 2025
Version: 1.0