Entity Link Schema Extension Type

[mattbrailsford]

Summary

Introduce a new entityLinkSchema extension type that allows packages to declaratively register URL patterns and parameters for navigating to entity editors in the back office.

Problem

Currently, there's no standardized way to:

1. Discover how to construct a URL to edit/create/view an entity
2. Understand what parameters are required (e.g., an Order needs a Store ID)
3. Generate back office URLs without hardcoding patterns or loading workspace contexts

Each package (Commerce, Forms, Deploy, etc.) defines URL patterns in isolation. Code that needs to link to entities must either:

• Hardcode URL patterns (fragile, breaks on changes)
• Have direct knowledge of specific workspace implementations
• Load workspace contexts just to get URL information

This becomes especially problematic for:

• AI integrations that need to generate navigation links dynamically
• Cross-package linking (e.g., a dashboard linking to Commerce orders)
• External tools that need to deep-link into the back office

Proposed Solution

A new extension type that declaratively describes how to link to an entity:

interface ManifestEntityLinkSchema extends ManifestBase {
  type: 'entityLinkSchema';
  meta: {
    /** Entity type this link is for (e.g., "document", "uc:order") */
    entityType: string;

    /** Type of link */
    linkType: 'edit' | 'create' | 'view';

    /** Section containing this entity */
    section: string;

    /** URL pattern with :placeholders */
    pattern: string;

    /** Human-readable description of what this link does */
    description: string;

    /** Parameters required to construct the URL */
    parameters: UmbLinkParameter[];
  };
}

interface UmbLinkParameter {
  /** Parameter name matching placeholder in pattern */
  alias: string;

  /** Description of what this parameter represents */
  description: string;

  /** Whether this parameter must be provided */
  required: boolean;

  /** If this parameter references another entity type */
  entityType?: string;
}

Examples

Document (Simple)

{
  type: 'entityLinkSchema',
  alias: 'Umb.EntityLinkSchema.Document.Edit',
  name: 'Document Edit Link',
  meta: {
    entityType: 'document',
    linkType: 'edit',
    section: 'content',
    pattern: 'edit/:unique',
    description: 'Edit a document',
    parameters: [
      { alias: 'unique', description: 'Document ID', required: true },
    ],
  },
}

Nested Entity (e.g., Commerce Order)

Entities that exist within a parent context can express that through parameters:

{
  type: 'entityLinkSchema',
  alias: 'Uc.EntityLinkSchema.Order.Edit',
  name: 'Order Edit Link',
  meta: {
    entityType: 'uc:order',
    linkType: 'edit',
    section: 'commerce',
    pattern: 'uc:store/:storeId/uc:order/edit/:unique',
    description: 'View or edit an order',
    parameters: [
      { alias: 'unique', description: 'Order ID', required: true },
      { alias: 'storeId', description: 'Store the order belongs to', required: true, entityType: 'uc:store' },
    ],
  },
}

Collection View

{
  type: 'entityLinkSchema',
  alias: 'Uc.EntityLinkSchema.Orders.View',
  name: 'Orders Collection Link',
  meta: {
    entityType: 'uc:orders',
    linkType: 'view',
    section: 'commerce',
    pattern: 'uc:store/:storeId/uc:orders',
    description: 'View all orders for a store',
    parameters: [
      { alias: 'storeId', description: 'Store to list orders for', required: true, entityType: 'uc:store' },
    ],
  },
}

Deeply Nested Entity

{
  type: 'entityLinkSchema',
  alias: 'Uc.EntityLinkSchema.Region.Edit',
  name: 'Region Edit Link',
  meta: {
    entityType: 'uc:region',
    linkType: 'edit',
    section: 'settings',
    pattern: 'uc:store-settings/:storeId/uc:country/:countryId/uc:region/edit/:unique',
    description: 'Edit a shipping region',
    parameters: [
      { alias: 'unique', description: 'Region ID', required: true },
      { alias: 'countryId', description: 'Country this region belongs to', required: true, entityType: 'uc:country' },
      { alias: 'storeId', description: 'Store', required: true, entityType: 'uc:store' },
    ],
  },
}

Service API

A CMS service to query schemas and build URLs:

interface UmbEntityLinkService {
  /** Get schema for specific entity + link type */
  getSchema(entityType: string, linkType: 'edit' | 'create' | 'view'): ManifestEntityLinkSchema | undefined;

  /** Get all schemas for an entity type */
  getSchemasForEntity(entityType: string): ManifestEntityLinkSchema[];

  /** Get all registered schemas */
  getAllSchemas(): ManifestEntityLinkSchema[];

  /** Build URL from schema + parameters */
  buildUrl(entityType: string, linkType: 'edit' | 'create' | 'view', params: Record<string, string | null>): string | undefined;
}

Use Cases

1. AI-Powered Navigation

AI assistants can use the schema to understand what's needed to link to an entity:

// AI queries available link schemas
const schemas = linkService.getAllSchemas();
// → Discovers uc:order needs { unique, storeId }

// AI builds link with gathered parameters
const url = linkService.buildUrl('uc:order', 'edit', { unique: orderId, storeId });

The description and parameter entityType references help AI understand relationships without hardcoded knowledge.

2. Cross-Package Dashboards

A custom dashboard can link to entities from other packages without tight coupling:

// Dashboard doesn't need to know Commerce URL structure
const orderLink = linkService.buildUrl('uc:order', 'edit', {
  unique: order.id,
  storeId: order.storeId
});

3. External Deep Linking

External systems can query schemas via Management API to construct valid back office URLs.

4. Validation

The service can validate parameters before URL construction:

const schema = linkService.getSchema('uc:order', 'edit');
const missing = schema.meta.parameters
  .filter(p => p.required && !params[p.alias]);

Design Considerations

Why a Separate Extension Type?

Rather than embedding this in workspace manifests:

1. Decoupling - Link schemas can be registered independently of workspaces
2. Extensibility - Third parties can add schemas for core entities
3. Atomic - Each manifest represents one link type (follows Umbraco patterns)
4. Optional - Only register links that make sense (e.g., some entities can't be created manually)

Why Not Use Workspace Context?

Workspace contexts require instantiation. Link schemas are manifest metadata that can be queried without loading workspace APIs - important for lazy loading and external tools.

Parameter entityType Reference

When a parameter references another entity (e.g., storeId references uc:store), this metadata enables:

• AI understanding of entity relationships
• Potential UI for parameter selection (entity picker)
• Validation that referenced entity exists

Implementation Notes

Schema Discovery

The service subscribes to the extension registry:

class UmbEntityLinkService {
  #schemas = new Map<string, Map<string, ManifestEntityLinkSchema>>();

  constructor(extensionRegistry: UmbExtensionRegistry) {
    extensionRegistry.byType('entityLinkSchema').subscribe((manifests) => {
      this.#rebuildIndex(manifests);
    });
  }
}

URL Construction

Pattern placeholders are replaced with parameter values:

buildUrl(entityType: string, linkType: string, params: Record<string, string | null>): string | undefined {
  const schema = this.getSchema(entityType, linkType);
  if (!schema) return undefined;

  let url = schema.meta.pattern;
  for (const [key, value] of Object.entries(params)) {
    url = url.replace(`:${key}`, value ?? '');
  }

  return `/umbraco/section/${schema.meta.section}/workspace/${url}`;
}

Questions for Discussion

1. Link type extensibility - Should linkType be a fixed enum or allow custom values (e.g., 'preview', 'history')?

2. Query parameters - Should schemas support optional query string parameters (e.g., ?culture=en-US&segment=mobile)?

3. Default schemas - Should CMS ship with schemas for core entities (document, media, member, etc.)?

4. Management API exposure - Should schemas be queryable via the Management API for external tools?

Related

• Workspace routing patterns in @umbraco-cms/backoffice/router
• UmbPathPattern class for URL construction
• Entity context patterns

---

Type: Feature Request
Area: Backoffice / Extension System
Complexity: Medium