Records

Records are the foundation of Phaset. Each Record represents a single piece of software—a service, API, component, library, or tool. Everything in Phaset revolves around Records: metrics, standards, reviews, health scores.

If Phaset is your software catalog, Records are the catalog entries.

Everything else in Phaset builds on Records:

• Catalog organizes and displays Records
• Baselines define standards that Records should meet
• Standards measure Record compliance with Baselines
• Metrics track Record performance over time
• Reviews assess Record quality across architecture, development, and operations

Without Records, there’s nothing to measure, track, or improve. Records are where it all begins.

Why Records Matter

They document what exists. Every organization has software they’ve forgotten about, built twice, or can’t explain. Records make your software landscape explicit and discoverable. A Record isn’t just a name—it’s ownership, dependencies, SLOs, health metrics, tech stack, lifecycle stage, and business criticality. Everything you need to understand a piece of software lives on its Record. Once software is documented as Records, you can measure it (metrics), enforce standards against it (baselines), review it (assessments), and track its health over time. Whether you have 10 services or 1,000, Records keep everything organized and navigable through the Catalog.

What’s in a Record?

Every Record is able to capture and present a wide set of relevant data, such as:

Identity & Context:

• Name, description, version
• Repository link
• Kind (service, API, component, etc.)
• Lifecycle stage (development, production, deprecated)

Organization:

• Domain (business area)
• System (technical grouping)
• Group (owning team)

Dependencies and Relationships:

• Upstream dependencies
• Downstream dependents (consumers)
• Related services

Quality and Operations:

• Standards compliance
• Metrics (DORA, engineering)
• Health score
• Service Level Objectives (SLOs)

Technical Details:

• Technology stack
• Deployment model
• Data sensitivity
• Business criticality

Managing Records

Records can be managed two ways:

Manual: Create and update Records directly in the Phaset UI. Good for getting started, managing external software, or small catalogs.

Automated: Store Record data in a phaset.manifest.json file in your repository. Updates happen automatically via CI/CD integration. Good for keeping documentation in sync with code and scaling across many services.

Most teams use both: automation for services they own, manual entry for third-party dependencies.

Automation via Manifest Files

The manifest file (phaset.manifest.json) lives in your repository and contains all Record metadata as JSON. When you push changes, your CI/CD pipeline updates the Record in Phaset automatically. See the integration guide for setup details.

How to Create Records

You have lots of options on how to create a Record, fitting pretty much any conceivable use case.

To create the actual contents you can:

• Make them from scratch in the web application (see “Creating Records in the Web Application” below)
• Type them manually as JSON, following the expected format
• Kickstart a manifest by using the Phaset’s Claude MCP server in a code repository
• Convert existing Backstage files with the online converter or Phaset’s programmatic converter tool

To add them to Phaset you can:

• Again, create them from scratch in the web application. When you save your edits, they are stored and made available through Phaset
• Import a manifest JSON (i.e. Record data) into the Create Record modal in the web application
• Upload them via the API or integrations

Creating Records in the Web Application

This is the suggested method for many cases.

If you’ve never done it before, get started by:

1. Create your first Record manually through the UI
2. Fill in basic information (name, description, repo link)
3. Add organizational context (Domain, System, Group)
4. Connect dependencies if applicable
5. Set up automation via manifest files once comfortable

Start simple: A Record with just name, description, and owner is infinitely better than no Record at all. You can always add details later.

Starting From a Manifest File

If you have manifest files ready at hand, you can import that data during Record creation in the web application.

This allows you to prepare data separately and then simply import it easily when you are are ready to start managing the data.

Programmatic

You can also create and update Records programmatically, useful for bulk operations or custom workflows.

You can read more about this in the Integration Deep Dive