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)
• Actions on its records, and an optional "Create …" button
• Connection to backend services (protobuf service mapping)
• Entity availability (active, disabled)

PhaseEntityConfig Interface

Property	Type	Description	Required
id	string	Unique identifier within the phase, used in URL routing	✅ Yes
name	string	Lowercase canonical display name (plural); title-cased at render time in nav	✅ Yes
service	string	Name of the protobuf service this entity maps to	✅ Yes
state	PhaseEntityState	Controls entity availability	✅ Yes
revisioned	boolean	Render the detail view from a Revision snapshot instead of the live record (see Revisioned Entities)	No
views	ViewConfig[]	View configurations: a list view and a detail view	✅ Yes
actions	ActionConfigSchema[]	Actions rendered in list-view rows and the detail header (see Action Configuration Reference)	No
createAction	CreateActionConfig	A "Create …" button in the list table's action bar	No

Entity States

The state property controls individual entity behavior within a phase:

State	Description	Use When
active	Entity is fully functional and can be interacted with	Entity is implemented with views configured
disabled	Entity is not available and cannot be interacted with	Entity 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
• ViewConfig is ListViewConfig | DetailViewConfig; there's no form view. Forms are React components opened from actions (see Form Reference)
• The list view must be views[0]: the phase page builds the entity table from views[0].tableConfig
• The detail page uses the first view with type: 'detail' (see Detail View Configuration Reference)

revisioned

• Set it only for entities whose records carry a status.latestRevision pointer. The built-in pipelines entity sets it

actions and createAction

• actions render in every list-view row (overflow menu) and in the detail header
• On the list view, entity actions replace any actions in the list view's tableConfig
• createAction opens a component that owns its own submit flow
• See Action Configuration Reference

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 (see Table Configuration Reference)
• Detail views: config/entities/*/detail.ts - Metadata header + content pages (see Detail View Configuration Reference)

Built-in Entities

These entity configs ship in config/entities/ and are wired into phases in config/phases/:

id	name	service	Phases	Notes
pipelines	pipelines	pipeline	train, retrain, deploy (data: disabled)	revisioned: true; actions: Run, Run trigger, Delete
runs	runs	pipelineRun	train, retrain, deploy (data: disabled)	Action: Retry
triggers	triggers	triggerRun	train, retrain, deploy	Actions: Kill, Rerun
models	trained models	model	train	No actions
targets	targets	inferenceServer	deploy	Inference servers; createAction: Create target
deployments	deployments	deployment	deploy	Actions: Update deployment, Retire, Delete; createAction: Create deployment

Phases also list placeholder entities with state: 'disabled' and views: []: datasources (data), and evaluations and notebooks (train).

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

Built-in entities: javascript/packages/core/config/entities/ and javascript/packages/core/config/phases/

Related Documentation

• Phase Configuration Reference - Configure phases that contain entities
• Cell Types Reference - Configure columns and fields in views
• Detail View Configuration Reference - Configure the detail view
• Action Configuration Reference - Configure actions and createAction
• Configuration API - overview of configuration system