Common to All Asset Kinds

Asset Descriptor Example

In the T-matic platform, defining a Code Component asset requires specific parameters and structure. Here's a representation:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: ecommerce-website
  description: The ultimate destination for shopping.
  labels:
    example.com/custom: custom_label_value
  annotations:
    example.com/service-discovery: ecommerce-web
    circleci.com/project-slug: github/example-org/artist-website
  tags:
    - java
  links:
    - url: https://admin.example-org.com
      title: Admin Dashboard
      icon: dashboard
      type: admin-dashboard
spec:
  type: website
  lifecycle: production
  owner: ecommerce-team
  system: public-websites

API Response Format

When the software catalog API returns this entity, it is formatted in JSON as follows:

{
  "apiVersion": "backstage.io/v1alpha1",
  "kind": "Component",
  "metadata": {
    "annotations": {
      "backstage.io/managed-by-location": "file:/tmp/catalog-info.yaml",
      "example.com/service-discovery": "artistweb",
      "circleci.com/project-slug": "github/example-org/artist-website"
    },
    "description": "The ultimate destination for renowned artists.",
    "etag": "ZjU2MWRkZWUtMmMxZS00YTZiLWFmMWMtOTE1NGNiZDdlYzNk",
    "labels": {
      "example.com/custom": "custom_label_value"
    },
    "links": [
      {
        "url": "https://admin.example-org.com",
        "title": "Admin Dashboard",
        "icon": "dashboard",
        "type": "admin-dashboard"
      }
    ],
    "tags": ["java"],
    "name": "artist-web",
    "uid": "2152f463-549d-4d8d-a94d-ce2b7676c6e2"
  },
  "spec": {
    "lifecycle": "production",
    "owner": "artist-relations-team",
    "type": "website",
    "system": "public-websites"
  }
}

Root Fields Overview

The primary fields, namely apiVersion, kind, metadata, and spec, encapsulate the essence of the entity. Additionally, specific metadata fields, including name, labels, and annotations, are crucial and possess specific purposes and configurations.

Descriptor Format Substitutions

The descriptor format within T-matic supports dynamic substitutions like $text, $json, and $yaml.

• $text: Interprets the file's content as plain text, embedding it as a string.

• $json: Reads the file content as JSON, integrating the parsed structure.

• $yaml: Analyzes the file content as YAML and embeds the parsed structure.

For instance, to integrate an API entity definition from an external server and include it as a string in spec.definition, one might use:

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: petstore
  description: The prime API for Petstore
spec:
  type: openapi
  lifecycle: production
  owner: [e-mail]
  definition:
    $text: https://petstore.swagger.io/v2/swagger.json

T-matic Envelope Explanation

Every entity in T-matic uses a foundational structure called the envelope.

• apiVersion and kind [required]:

  • kind represents the entity's primary type. T-matic concentrates on the Component kind, especially in the initial stages.

  • apiVersion signifies the specification format version for that entity. The combination of apiVersion and kind helps parsers understand the data's interpretation.

• metadata [required]:

  • Metadata about the entity that isn't directly a part of the entity specification.

• spec [varies]:

  • Holds the actual data that describes the entity. The precise structure is determined by the apiVersion and kind.

T-matic Asset Metadata Explanation

name [required]

Refers to the name of the entity designed for human recognition and for digital systems, such as in T-matic platform URLs or from other Envelope files.

Each type of entity must have a unique name within a certain namespace (if given) at any time. This requirement for uniqueness is not case-sensitive. Once an entity is removed from the directory, its name can be reassigned.

Entities must conform to a specific naming pattern. Non-conformities won't be registered in the catalog. The default conventions are:

• Between 1 and 63 characters in length.

• Must consist of sequences of [a-z0-9A-Z] possibly separated by [-_.] Example: Tmatic-analytics-module, SystemDumpV2_cloud_storage

namespace [optional]

Indicates the entity's assigned namespace. It presently sets the boundaries for name uniqueness. Its definition might expand in the future.

It's recommended to forgo specifying a namespace unless it's essential, implying the entity falls under the "default" namespace.

Namespaces adhere to the [a-zA-Z0-9] pattern with optional dashes, capped at 63 characters. These are typically displayed in lowercase. Example: platform-modules, transaction

uid [output]

Each entity is endowed with a distinct global ID upon its initial database entry. This is an output, generated by the database system.

Keep in mind that these uid values might not remain consistent. For a stable reference, always use the name.

title [optional]

Provides a user-friendly display, often replacing the name in user interfaces if available.

This comes in handy when the name seems too technical. This title might not have as strict format rules as the name, but it should remain concise. Always avoid confusion between title and name.

description [optional]

A concise, human-readable summary of the entity for display in the T-matic platform. Comprehensive explanations and documents should be placed elsewhere.

labels [optional]

Labels are key/value pairs attached to the entity, similar to Kubernetes object labels. They serve various purposes, including classifying the current entity or referencing other entities.

annotations [optional]

An arbitrary object carrying non-identifying metadata for the entity. They often point to external systems or other references.

tags [optional]

A list of single-value strings to categorize entities differently from labels, which are key-value pairs.

links [optional]

External hyperlinks connected to the entity. These links might point to resources outside of the T-matic platform.

Each link contains:

• url: A standard URI format, e.g., https://example.com/some/page

• title: A user-friendly display name for the link.

• icon: Represents a visual UI icon.

• type: Categorizes links into distinct groups.

NOTE: Icons are usually mapped from an icon library, with the integrator providing the necessary icon components. The T-matic platform might offer basic icons by default.

The type field's semantics are open-ended. The user has the liberty to define and apply them as needed. They might help validate entity links or design UI components tailored for specific link types.

T-matic Asset Relations Explanation

In the T-matic platform, the relations field is a predefined, read-only list that details the relationships between the present entity and other associated entities. These are further explained in the recognized relations section. Relations typically operate in both directions, ensuring a set of relation types, each defining one orientation of the connection.

Here's an example of how a relation, as part of an individual entity extracted from the API, might appear in the T-matic platform:

{
  // ...
  "relations": [
    {
      "type": "ownedBy",
      "targetRef": "group:default/dev.infra"
    }
  ],
  "spec": {
    "owner": "dev.infra",
    // ...
  }
}

The structure of a relation includes:

Field	Type	Description
targetRef	String	A comprehensive entity reference pointing to the other end of the relation.
type	String	Denotes the type of relationship FROM a source entity TO the target entity.
metadata	Object	Preserved for prospective enhancements.

It's important to note that entity descriptor YAML files within the T-matic platform shouldn't incorporate this field. Instead, catalog processors evaluate the entity descriptor data along with its context to infer the relations. These relationships are then appended to the entity when extracted from the catalog.

Where these relations are generated, they should be viewed as the definitive source for that data segment. Referring to the previous example, it's advisable for a plugin in the T-matic platform to utilize the relation rather than spec.owner to determine the owner of the entity. This is because the ownership might not be sourced from the YAML directly—it could, for instance, be extracted from a nearby CODEOWNERS file. Moreover, spec.owner uses a condensed format that might carry specific semantics, such as defaulting to Group when not explicitly stated.

T-matic Asset Status Explanation

In the T-matic platform, the status root object provides a read-only collection of statuses related to the current state or health of the entity. Further details can be found in the recognized statuses section.

At present, the only established field is the items array. Each item within this array possesses a unique structure detailing certain aspects of the entity's state from a specific system's perspective. Multiple systems might contribute to this array under their individual type keys.

The primary application of this field within the T-matic platform is to allow ingestion processes of the catalog to relay information regarding errors and warnings back to the user.

An example of how a status field might appear for a single entity retrieved from the API in the T-matic platform is as follows:

{
  // ...
  "status": {
    "items": [
      {
        "type": "t-matic.io/catalog-processing",
        "level": "error",
        "message": "NotFoundError: File not found",
        "error": {
          "name": "NotFoundError",
          "message": "File not found",
          "stack": "..."
        }
      }
    ]
  },
  "spec": {
    // ...
  }
}

The individual fields of a status item include:

Field	Type	Description
type	String	Represents the status type as a unique key for each source. Each type might recur multiple times in the array.
level	String	Indicates the severity or level of the status item, which can be 'info', 'warning, or 'error'.
message	String	Provides a succinct message explaining the status, meant for end-users.
error	Object	An optional serialized error object linked with the status.

While the type is a flexible string, for clarity, it's suggested that types not exclusively private within an organization be prefixed to avert potential overlaps. For instance, statuses emitted by T-matic core processes might be prefixed with t-matic.io/, similar to the example provided.

It's imperative to note that entity descriptor YAML files in the T-matic platform shouldn't incorporate a status root key. Instead, catalog processors assess the entity descriptor data alongside its environment and determine status entries. These entries are subsequently appended to the entity when retrieved from the catalog.