diff --git a/docs/assets/software-catalog/software-model-core-entities.drawio.svg b/docs/assets/software-catalog/software-model-core-entities.drawio.svg
new file mode 100644
index 0000000000..2260e5502e
--- /dev/null
+++ b/docs/assets/software-catalog/software-model-core-entities.drawio.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/docs/assets/software-catalog/software-model-core-entities.png b/docs/assets/software-catalog/software-model-core-entities.png
deleted file mode 100644
index 60cb283802..0000000000
Binary files a/docs/assets/software-catalog/software-model-core-entities.png and /dev/null differ
diff --git a/docs/assets/software-catalog/software-model-entities.drawio.svg b/docs/assets/software-catalog/software-model-entities.drawio.svg
new file mode 100644
index 0000000000..7b8b88f224
--- /dev/null
+++ b/docs/assets/software-catalog/software-model-entities.drawio.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md
index 763acd2261..725f358b92 100644
--- a/docs/features/software-catalog/descriptor-format.md
+++ b/docs/features/software-catalog/descriptor-format.md
@@ -60,7 +60,7 @@ software catalog API.
},
"spec": {
"lifecycle": "production",
- "owner": "artist-relations@example.com",
+ "owner": "artist-relations-team",
"type": "website"
}
}
@@ -84,7 +84,7 @@ metadata:
spec:
type: website
lifecycle: production
- owner: artist-relations@example.com
+ owner: artist-relations-team
```
The root fields `apiVersion`, `kind`, `metadata`, and `spec` are part of the
@@ -381,7 +381,8 @@ metadata:
spec:
type: website
lifecycle: production
- owner: artist-relations@example.com
+ owner: artist-relations-team
+ system: artist-engagement-portal
providesApis:
- artist-api
```
@@ -427,8 +428,8 @@ The current set of well-known and common values for this field is:
### `spec.owner` [required]
-The owner of the component, e.g. `artist-relations@example.com`. This field is
-required.
+An [entity reference](#string-references) to the owner of the component, e.g.
+`artist-relations-team`. This field is required.
In Backstage, the owner of a component is the singular entity (commonly a team)
that bears ultimate responsibility for the component, and has the authority and
@@ -440,25 +441,36 @@ not to be used by automated processes to for example assign authorization in
runtime systems. There may be others that also develop or otherwise touch the
component, but there will always be one ultimate owner.
-Apart from being a string, the software catalog leaves the format of this field
-open to implementers to choose. Most commonly, it is set to the ID or email of a
-group of people in an organizational structure.
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
+| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
+| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default` | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) |
+
+### `spec.system` [optional]
+
+An [entity reference](#string-references) to the system that the component
+belongs to, e.g. `artist-engagement-portal`. This field is optional.
+
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
+| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
+| [`System`](#kind-system) (default) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) |
### `spec.providesApis` [optional]
-Links APIs that are provided by the component, e.g. `artist-api`. This field is
-optional.
+An array of [entity references](#string-references) to the APIs that are
+provided by the component, e.g. `artist-api`. This field is optional.
-The software catalog expects a list of one or more strings that references the
-names of other entities of the `kind` `API`.
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
+| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| [`API`](#kind-api) (default) | Same as this entity, typically `default` | [`providesApi`, and reverse `apiProvidedBy`](well-known-relations.md#providesapi-and-apiprovidedby) |
### `spec.consumesApis` [optional]
-Links APIs that are consumed by the component, e.g. `artist-api`. This field is
-optional.
+An array of [entity references](#string-references) to the APIs that are
+consumed by the component, e.g. `artist-api`. This field is optional.
-The software catalog expects a list of one or more strings that references the
-names of other entities of the `kind` `API`.
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
+| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| [`API`](#kind-api) (default) | Same as this entity, typically `default` | [`consumesApi`, and reverse `apiConsumedBy`](well-known-relations.md#consumesapi-and-apiconsumedby) |
## Kind: Template
@@ -597,7 +609,8 @@ metadata:
spec:
type: openapi
lifecycle: production
- owner: artist-relations@example.com
+ owner: artist-relations-team
+ system: artist-engagement-portal
definition: |
openapi: "3.0.0"
info:
@@ -663,8 +676,8 @@ The current set of well-known and common values for this field is:
### `spec.owner` [required]
-The owner of the API, e.g. `artist-relations@example.com`. This field is
-required.
+An [entity reference](#string-references) to the owner of the component, e.g.
+`artist-relations-team`. This field is required.
In Backstage, the owner of an API is the singular entity (commonly a team) that
bears ultimate responsibility for the API, and has the authority and capability
@@ -676,9 +689,18 @@ processes to for example assign authorization in runtime systems. There may be
others that also develop or otherwise touch the API, but there will always be
one ultimate owner.
-Apart from being a string, the software catalog leaves the format of this field
-open to implementers to choose. Most commonly, it is set to the ID or email of a
-group of people in an organizational structure.
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
+| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
+| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default` | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) |
+
+### `spec.system` [optional]
+
+An [entity reference](#string-references) to the system that the API belongs to,
+e.g. `artist-engagement-portal`. This field is optional.
+
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
+| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
+| [`System`](#kind-system) (default) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) |
### `spec.definition` [required]
@@ -751,11 +773,11 @@ parent; the catalog supports multi-root hierarchies. Groups may however not have
more than one parent.
This field is an
-[entity reference](https://backstage.io/docs/features/software-catalog/references),
-with the default kind `Group` and the default namespace equal to the same
-namespace as the user. Only `Group` entities may be referenced. Most commonly,
-this field points to a group in the same namespace, so in those cases it is
-sufficient to enter only the `metadata.name` field of that group.
+[entity reference](https://backstage.io/docs/features/software-catalog/references).
+
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
+| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------- |
+| [`Group`](#kind-group) (default) | Same as this entity, typically `default` | [`childOf`, and reverse `parentOf`](well-known-relations.md#parentof-and-childof) |
### `spec.children` [required]
@@ -765,11 +787,11 @@ no child groups. The items are not guaranteed to be ordered in any particular
way.
The entries of this array are
-[entity references](https://backstage.io/docs/features/software-catalog/references),
-with the default kind `Group` and the default namespace equal to the same
-namespace as the user. Only `Group` entities may be referenced. Most commonly,
-these entries point to groups in the same namespace, so in those cases it is
-sufficient to enter only the `metadata.name` field of those groups.
+[entity references](https://backstage.io/docs/features/software-catalog/references).
+
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
+| --------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- |
+| [`Group`](#kind-group) (default) | Same as this entity, typically `default` | [`hasMember`, and reverse `memberOf`](well-known-relations.md#memberof-and-hasmember) |
## Kind: User
@@ -825,23 +847,202 @@ user is not member of any groups. The items are not guaranteed to be ordered in
any particular way.
The entries of this array are
-[entity references](https://backstage.io/docs/features/software-catalog/references),
-with the default kind `Group` and the default namespace equal to the same
-namespace as the user. Only `Group` entities may be referenced. Most commonly,
-these entries point to groups in the same namespace, so in those cases it is
-sufficient to enter only the `metadata.name` field of those groups.
+[entity references](https://backstage.io/docs/features/software-catalog/references).
+
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
+| --------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- |
+| [`Group`](#kind-group) (default) | Same as this entity, typically `default` | [`memberOf`, and reverse `hasMember`](well-known-relations.md#memberof-and-hasmember) |
## Kind: Resource
-This kind is not yet defined, but is reserved [for future use](system-model.md).
+Describes the following entity kind:
+
+| Field | Value |
+| ------------ | ----------------------- |
+| `apiVersion` | `backstage.io/v1alpha1` |
+| `kind` | `Resource` |
+
+A resource describes the infrastructure a system needs to operate, like BigTable
+databases, Pub/Sub topics, S3 buckets or CDNs. Modelling them together with
+components and systems allows to visualize resource footprint, and create
+tooling around them.
+
+Descriptor files for this kind may look as follows.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Resource
+metadata:
+ name: artists-db
+ description: Stores artist details
+spec:
+ type: database
+ owner: artist-relations-team
+ system: artist-engagement-portal
+```
+
+In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
+shape, this kind has the following structure.
+
+### `apiVersion` and `kind` [required]
+
+Exactly equal to `backstage.io/v1alpha1` and `Resource`, respectively.
+
+### `spec.owner` [required]
+
+An [entity reference](#string-references) to the owner of the resource, e.g.
+`artist-relations-team`. This field is required.
+
+In Backstage, the owner of a resource is the singular entity (commonly a team)
+that bears ultimate responsibility for the resource, and has the authority and
+capability to develop and maintain it. They will be the point of contact if
+something goes wrong, or if features are to be requested. The main purpose of
+this field is for display purposes in Backstage, so that people looking at
+catalog items can get an understanding of to whom this resource belongs. It is
+not to be used by automated processes to for example assign authorization in
+runtime systems. There may be others that also manage or otherwise touch the
+resource, but there will always be one ultimate owner.
+
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
+| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
+| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default` | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) |
+
+### `spec.type` [required]
+
+The type of resource as a string, e.g. `database`. This field is required. There
+is currently no enforced set of values for this field, so it is left up to the
+adopting organization to choose a nomenclature that matches the resources used
+in their tech stack.
+
+Some common values for this field could be:
+
+- `database`
+- `s3-bucket`
+- `cluster`
+
+### `spec.system` [optional]
+
+An [entity reference](#string-references) to the system that the resource
+belongs to, e.g. `artist-engagement-portal`. This field is optional.
+
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
+| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
+| [`System`](#kind-system) (default) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) |
## Kind: System
-This kind is not yet defined, but is reserved [for future use](system-model.md).
+Describes the following entity kind:
+
+| Field | Value |
+| ------------ | ----------------------- |
+| `apiVersion` | `backstage.io/v1alpha1` |
+| `kind` | `System` |
+
+A system is a collection of resources and components. The system may expose or
+consume one or several APIs. It is viewed as abstraction level that provides
+potential consumers insights into exposed features without needing a too
+detailed view into the details of all components. This also gives the owning
+team the possibility to decide about published artifacts and APIs.
+
+Descriptor files for this kind may look as follows.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: System
+metadata:
+ name: artist-engagement-portal
+ description: Handy tools to keep artists in the loop
+spec:
+ owner: artist-relations-team
+ domain: artists
+ providesApis:
+ - artist-api
+```
+
+In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
+shape, this kind has the following structure.
+
+### `apiVersion` and `kind` [required]
+
+Exactly equal to `backstage.io/v1alpha1` and `System`, respectively.
+
+### `spec.owner` [required]
+
+An [entity reference](#string-references) to the owner of the system, e.g.
+`artist-relations-team`. This field is required.
+
+In Backstage, the owner of a system is the singular entity (commonly a team)
+that bears ultimate responsibility for the system, and has the authority and
+capability to develop and maintain it. They will be the point of contact if
+something goes wrong, or if features are to be requested. The main purpose of
+this field is for display purposes in Backstage, so that people looking at
+catalog items can get an understanding of to whom this system belongs. It is not
+to be used by automated processes to for example assign authorization in runtime
+systems. There may be others that also develop or otherwise touch the system,
+but there will always be one ultimate owner.
+
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
+| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
+| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default` | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) |
+
+### `spec.domain` [optional]
+
+An [entity reference](#string-references) to the domain that the system belongs
+to, e.g. `artists`. This field is optional.
+
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
+| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
+| [`Domain`](#kind-domain) (default) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) |
## Kind: Domain
-This kind is not yet defined, but is reserved [for future use](system-model.md).
+Describes the following entity kind:
+
+| Field | Value |
+| ------------ | ----------------------- |
+| `apiVersion` | `backstage.io/v1alpha1` |
+| `kind` | `Domain` |
+
+A Domain groups a collection of systems that share terminology, domain models,
+business purpose, or documentation, i.e. form a bounded context.
+
+Descriptor files for this kind may look as follows.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Domain
+metadata:
+ name: artists
+ description: Everything about artists
+spec:
+ owner: artist-relations-team
+```
+
+In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
+shape, this kind has the following structure.
+
+### `apiVersion` and `kind` [required]
+
+Exactly equal to `backstage.io/v1alpha1` and `Domain`, respectively.
+
+### `spec.owner` [required]
+
+An [entity reference](#string-references) to the owner of the domain, e.g.
+`artist-relations-team`. This field is required.
+
+In Backstage, the owner of a domain is the singular entity (commonly a team)
+that bears ultimate responsibility for the domain, and has the authority and
+capability to develop and maintain it. They will be the point of contact if
+something goes wrong, or if features are to be requested. The main purpose of
+this field is for display purposes in Backstage, so that people looking at
+catalog items can get an understanding of to whom this domain belongs. It is not
+to be used by automated processes to for example assign authorization in runtime
+systems. There may be others that also develop or otherwise touch the domain,
+but there will always be one ultimate owner.
+
+| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
+| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
+| [`Group`](#kind-group) (default), [`User`](#kind-user) | Same as this entity, typically `default` | [`ownerOf`, and reverse `ownedBy`](well-known-relations.md#ownedby-and-ownerof) |
## Kind: Location
diff --git a/docs/features/software-catalog/system-model.md b/docs/features/software-catalog/system-model.md
index d797e87499..f0ead20664 100644
--- a/docs/features/software-catalog/system-model.md
+++ b/docs/features/software-catalog/system-model.md
@@ -23,7 +23,7 @@ We model software in the Backstage catalogue using these three core entities
- **Resources** are physical or virtual infrastructure needed to operate a
component
-
+
### Component
@@ -73,6 +73,8 @@ these entities using the following (optional) concepts:
function
- **Domains** relate entities and systems to part of the business
+
+
### System
With increasing complexity in software, systems form an important abstraction
@@ -107,10 +109,6 @@ product or use-case, share the same entity types in their APIs, and integrate
well with each other. Other domains could be “Content Ingestion”, “Ads” or
“Search”.
-## Current status
-
-Backstage currently supports Components and APIs.
-
## Links
- [Original RFC](https://github.com/backstage/backstage/issues/390)
diff --git a/docs/features/software-catalog/well-known-relations.md b/docs/features/software-catalog/well-known-relations.md
index 54f7833d1b..af2e7367f2 100644
--- a/docs/features/software-catalog/well-known-relations.md
+++ b/docs/features/software-catalog/well-known-relations.md
@@ -48,11 +48,10 @@ where present.
### `providesApi` and `apiProvidedBy`
A relation with an [API](descriptor-format.md#kind-api) entity, typically from a
-[Component](descriptor-format.md#kind-component) or
-[System](descriptor-format.md#kind-system).
+[Component](descriptor-format.md#kind-component).
-These relations express that a component or system exposes an API - meaning that
-it hosts callable endpoints from which you can consume that API.
+These relations express that a component exposes an API - meaning that it hosts
+callable endpoints from which you can consume that API.
This relation is commonly generated based on `spec.providesApis` of the
component or system in question.
@@ -60,11 +59,10 @@ component or system in question.
### `consumesApi` and `apiConsumedBy`
A relation with an [API](descriptor-format.md#kind-api) entity, typically from a
-[Component](descriptor-format.md#kind-component) or
-[System](descriptor-format.md#kind-system).
+[Component](descriptor-format.md#kind-component).
-These relations express that a component or system consumes an API - meaning
-that it depends on endpoints of the API.
+These relations express that a component consumes an API - meaning that it
+depends on endpoints of the API.
This relation is commonly generated based on `spec.consumesApis` of the
component or system in question.
@@ -91,3 +89,16 @@ A membership relation, typically for [Users](descriptor-format.md#kind-user) in
[Groups](descriptor-format.md#kind-group).
This relation is commonly based on `spec.memberOf`.
+
+### `partOf` and `hasPart`
+
+A relation with a [Domain](descriptor-format.md#kind-domain) or
+[System](descriptor-format.md#kind-system) entity, typically from a
+[Component](descriptor-format.md#kind-component),
+[API](descriptor-format.md#kind-api), or
+[System](descriptor-format.md#kind-system).
+
+These relations express that a component, API or resource belongs to a system,
+or that a system is grouped under a domain.
+
+This relation is commonly based on `spec.system` or `spec.domain`.