Add the status field to the Entity envelope

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

docs/features/software-catalog/descriptor-format.md

@@ -23,6 +23,7 @@ we recommend that you name them `catalog-info.yaml`.
 - [Common to All Kinds: The Envelope](#common-to-all-kinds-the-envelope)
 - [Common to All Kinds: The Metadata](#common-to-all-kinds-the-metadata)
 - [Common to All Kinds: Relations](#common-to-all-kinds-relations)
+- [Common to All Kinds: Status](#common-to-all-kinds-status)
 - [Kind: Component](#kind-component)
 - [Kind: Template](#kind-template)
 - [Kind: API](#kind-api)
@@ -396,6 +397,54 @@ with it (such as the default kind being `Group` if not specified).
 See the [well-known relations section](well-known-relations.md) for a list of
 well-known / common relations and their semantics.
 
+## Common to All Kinds: Status
+
+The `status` root field is a read-only set of statuses, pertaining to the
+current state or health of the entity, described in the
+[well-known statuses section](well-known-statuses.md). Each status field
+contains a specific blob of data that describes some aspect of the state of the
+entity, as seen from the point of view of some specific system. Different
+systems may contribute to this status object, under their own respective keys.
+
+The current main use case for this field is for the ingestion processes of the
+catalog itself to convey information about failures and warnings back to the
+user.
+
+A status field as part of a single entity that's read out of the API may look as
+follows.
+
+```js
+{
+  // ...
+  "status": {
+    "backstage.io/processing-status": {
+      "errors": []
+    }
+  },
+  "spec": {
+    // ...
+  }
+}
+```
+
+The keys of the `status` object are arbitrary strings. We recommend that any
+statuses, that are not strictly private within the organization, be namespaced
+to avoid collisions. Statuses emitted by Backstage core processes will for
+example be prefixed with `backstage.io/` as in the example above.
+
+The values of the `status` object are currently left unrestricted, except that
+they must be objects. We reserve the right to extend this model in the future,
+such that some fields of those value objects gain standardized meaning. We may
+for example want to add a standard concept of "severity" or "level" to these.
+
+Entity descriptor YAML files are not supposed to contain this field. Instead,
+catalog processors analyze the entity descriptor data and its surroundings, and
+deduce status entries that are then attached onto the entity as read from the
+catalog.
+
+See the [well-known statuses section](well-known-statuses.md) for a list of
+well-known / common relations and their semantics.
+
 ## Kind: Component
 
 Describes the following entity kind:

docs/features/software-catalog/extending-the-model.md

@@ -1,6 +1,7 @@
 ---
 id: extending-the-model
 title: Extending the model
+# prettier-ignore
 description: Documentation on extending the catalog model
 ---
 
@@ -301,9 +302,9 @@ Example intents:
 > "We have this concept of service maintainership, separate from ownership, that
 > we would like to make relations to individual users for."
 
-> We feel that we want to explicitly model the team-to-global-department mapping
-> as a relation, because it is core to our org setup and we frequently query for
-> it.
+> "We feel that we want to explicitly model the team-to-global-department
+> mapping as a relation, because it is core to our org setup and we frequently
+> query for it."
 
 Any processor can emit relations for entities as they are being processed, and
 new processors can be added when building the backend catalog using the
@@ -349,3 +350,21 @@ If you want to extend the use of an established relation type in a way that has
 an effect outside of your organization, reach out to the Backstage maintainers
 or a support partner to discuss risk/impact. It may even be that one end of the
 relation could be considered for addition to the core.
+
+## Adding a New Status field
+
+Example intents:
+
+> "We would like to convey entity statuses through the catalog in a generic way,
+> as an integration layer. Our monitoring and alerting system has a plugin with
+> Backstage, and it would be useful if the entity's status field contained the
+> current alert state close to the actual entity data for anyone to consume.
+
+While we are considering a mechanism for contributing generic statuses to
+entities, no such mechanism has yet been built. If you are interested in that
+topic, [this issue](https://github.com/backstage/backstage/issues/2292) contains
+more context.
+
+But in general, errors emitted (and exceptions thrown) by any processor
+including custom ones, end up in the [well known key](well-known-statuses.md)
+for ingestion status.

docs/features/software-catalog/well-known-statuses.md

@@ -0,0 +1,51 @@
+---
+id: well-known-statuses
+title: Well-known Status fields of Catalog Entities
+sidebar_label: Well-known Statuses
+# prettier-ignore
+description: Lists a number of well known entity statuses, that have defined semantics. They can be attached to catalog entities and consumed by plugins as needed.
+---
+
+This section lists a number of well known
+[entity status fields](descriptor-format.md#common-to-all-kinds-status), that
+have defined semantics. They can be attached to catalog entities and consumed by
+plugins as needed.
+
+If you are looking to extend the set of statuses, see
+[Extending the model](extending-the-model.md).
+
+## Common Fields
+
+The values of statuses are currently left unrestricted, except that they must be
+objects. They therefore currently formally have no common fields.
+
+We reserve the right to extend this model in the future, such that some fields
+of those value objects gain standardized meaning. We may for example want to add
+a standard concept of "severity" or "level" to these.
+
+## Statuses
+
+This is a (non-exhaustive) list of statuses that are known to be in active use.
+
+### `backstage.io/processing-status`
+
+Contains the current status of the catalog's ingestion of this entity. Errors
+that may appear here include inability to read from the remote SCM provider,
+syntax errors in the YAML file, and similar.
+
+Note that the entity data itself may be of an older version, when errors are
+present. The ingestion system keeps the old, valid entity data untouched when
+possible, so the errors described in this state may not seem to align with the
+rest of the entity, because they pertain to a remote that could not be
+successfully ingested. This is normal.
+
+```yaml
+# Example:
+status:
+  backstage.io/processing-status:
+    errors: []
+```
+
+This status is in active development and its format will change unexpectedly. Do
+not consume it in your own code until such a time that this documentation has
+been updated.