Skip to main content

Entity Configuration Reference

Entities define data models and their properties within a phase. Each entity represents a type of object in your ML platform (pipelines, runs, models, datasets, etc.) and specifies how that object is displayed and interacted with in the UI.

Entities define:

  • URL routing within a phase (/<phase>/runs, /<phase>/pipelines)
  • Available views for the entity (list view, detail view, forms)
  • Connection to backend services (protobuf service mapping)
  • Entity availability (active, disabled)

PhaseEntityConfig Interface​

PropertyTypeDescriptionRequired
idstringUnique identifier within the phase, used in URL routing✅ Yes
namestringLowercase canonical display name (plural); title-cased at render time in nav✅ Yes
servicestringName of the protobuf service this entity maps to✅ Yes
statePhaseEntityStateControls entity availability✅ Yes
viewsViewConfig[]Array of view configurations (list, detail, form)✅ Yes

Entity States​

The state property controls individual entity behavior within a phase:

StateDescriptionUse When
activeEntity is fully functional and can be interacted withEntity is implemented with views configured
disabledEntity is not available and cannot be interacted withEntity is planned but views not yet implemented

Example​

// From: config/entities/run/run.ts
export const RUN_ENTITY_CONFIG: PhaseEntityConfig = {
  id: 'runs',
  name: 'runs',
  service: 'pipelineRun',
  state: 'active',
  views: [RUN_LIST_CONFIG, RUN_DETAIL_CONFIG],
};

See also: config/entities/ for other entity examples

Property Details​

id​

  • Must be unique within the phase
  • Used in URL routing: /${phase}/${id}
  • Convention: plural, lowercase, hyphenated (e.g., runs, pipelines, feature-groups)

name​

  • The lowercase canonical display name for the entity. Store it lowercase; casing is applied at render time, not in config
  • Recommended: plural, descriptive
  • Examples: "runs", "pipelines", "trained models"
  • Can be intentionally not pluralized for special cases (e.g., "feature consistency")

Nav chrome — breadcrumbs, left-nav, phase tabs, page H1s — renders the name through formatEntityName(name, 'nav'), which title-cases each space-separated word, so 'trained models' displays as Trained Models. Everywhere else the lowercase value is itself the correct display form, which is why it reads naturally mid-sentence ("no runs found"). Pre-casing the config value is invisible in nav — formatEntityName leaves existing capitals alone, so it's idempotent there — which is exactly why the mistake is easy to miss: it looks right in the tabs and breaks the sentence case everywhere else.

note

This applies to entity name only. Phase name in config/phases/ stays Title Case ('Train & Evaluate', 'Prepare & Analyze Data') — phases are not passed through formatEntityName.

service​

  • Maps to the root protobuf field name of the backend service
  • Must match exactly for RPC queries to work correctly
  • Examples:
    • 'pipeline' → PipelineService, query: ListPipeline
    • 'pipelineRun' → PipelineRunService, query: ListPipelineRun
    • 'triggerRun' → TriggerRunService, query: ListTriggerRun

views​

  • Array of view configurations defining how the entity is presented

View Configuration​

Views define how entities are presented. See Cell Types Reference for column/field configuration.

  • List views: config/entities/*/list.ts - Table columns with cells
  • Detail views: config/entities/*/detail.ts - Metadata header + content pages

Common Patterns​

Organize entity configs by file:

config/entities/run/
├── run.ts      # Main entity config
├── list.ts     # List view config
├── detail.ts   # Detail view config
└── shared.ts   # Shared configs

Share cell configs across views:

// shared.ts - define once
export const SHARED_RUN_CELL_CONFIG: Cell[] = [...];

// Reuse in list.ts and detail.ts
import { SHARED_RUN_CELL_CONFIG } from './shared';

Service Mapping​

The service property maps to your protobuf service definition:

// Example protobuf service
service PipelineRunService {
  rpc ListPipelineRun(ListPipelineRunRequest) returns (ListPipelineRunResponse);
  rpc GetPipelineRun(GetPipelineRunRequest) returns (PipelineRun);
}
// Entity config
{
  id: 'runs',
  name: 'runs',
  service: 'pipelineRun', // ← Must match root field name
  // ...
}

The configuration system uses this mapping to:

  • Construct RPC query names (ListPipelineRun)
  • Access the correct service endpoints
  • Handle data fetching for views

Source Files​

Type definitions: javascript/packages/core/types/common/studio-types.ts - PhaseEntityConfig interface, PhaseEntityState type

View configurations: javascript/packages/core/components/views/types.ts - ListViewConfig, DetailViewConfig interfaces