> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/internal-developer-portal/3.0/use-idp/software-catalog/tutorials/entity-ref.md).

# Catalog Entity Reference

In IDP Catalog, Entities such as (Components, APIs, Groups, etc.) commonly have a need to refer other Catalog entities. For example, when we set an Owner of a Component by mentioning a Group or User. Or when we add a dependency between a Service and an API. This article describes how to write those entity references in your YAML descriptor files. The "Entity Refs" are also used anywhere else you want to uniquely mention an entity such as when using the [Catalog Ingestion API](/internal-developer-portal/use-idp/software-catalog/integrate-tools/catalog-ingestion-api.md).

Each entity in the catalog is uniquely identified by the triplet of its [kind](/internal-developer-portal/use-idp/software-catalog/content/catalog-yaml/catalog-yaml-2o.md#kind), [namespace](https://backstage.io/docs/features/software-catalog/descriptor-format#namespace-optional), and [name](/internal-developer-portal/use-idp/software-catalog/content/catalog-yaml/catalog-yaml-2o.md#name). But that is a lot to type out manually, and in a lot of circumstances, both the kind and the namespace are fixed, or possible to deduce, or could have sane default values. So in order to help the writer, the catalog has a few tricks up its sleeve.

Each reference can be expressed in one of two ways: as **a compact string**.

### String references <a href="#string-references" id="string-references"></a>

This is the most common alternative and is used in almost all circumstances.

The string is of the form `[<kind>:][<namespace>/]<name>`. That is, it is composed of between one and three parts in this specific order, without any additional encoding:

* Optionally, the kind, followed by a colon
* Optionally, the namespace, followed by a forward slash
* The name

Here are few examples:

* `component:order-service`
* `api:petstore`
* `group:my-team`
* `component:default/my-service`

**The name is always required**. Depending on the context, you may be able to leave out the kind and/or namespace. If you do, it is contextual what values will be used, and the relevant documentation should specify which rule applies where. **All strings are case insensitive**.

```yaml
# Example: <a href="#example" id="example"></a>
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: petstore
  namespace: external-systems
  description: Petstore
spec:
  type: service
  lifecycle: experimental
  owner: group:pet-managers
  providesApis:
    - petstore
    - internal/streetlights
    - hello-world
```

The field `spec.owner` is a reference. In this case, the string `group:pet-managers` was given by the user. That means that the kind is `Group`, the namespace is left out, and the name is `pet-managers`. In this context, the namespace was chosen to fall back to the value `default` by the code that parsed the reference, so the end result is that we expect to find another entity in the catalog that is of kind `Group`, namespace `default` (which, actually, also can be left out in its own YAML file because that is the default value there too), and name `pet-managers`.

The entries in `providesApis` are also references. In this case, none of them needs to specify a kind since we know from the context that that is the only kind that is supported here. The second entry specifies a namespace, but the other ones do not, and in this context, the default is to refer to the same namespace as the originating entity (`external-systems` here). So the three references essentially expand to `api:external-systems/petstore`, `api:internal/streetlights`, and `api:external-systems/hello-world`. We expect there to exist three API kind entities in the catalog matching those references.

Note that the remarks above in regard to shortening (leaving out kind and/or namespace) *only* apply for the entity input YAML data. In protocols, storage systems, or when referring to entities externally, the entity ref always consists of all three parts.