From 9b9a56129874096bf274ceff348673da0d1ff747 Mon Sep 17 00:00:00 2001
From: James Turley <jamesturley@gocardless.com>
Date: Tue, 12 Jan 2021 14:54:39 +0000
Subject: [PATCH] Document subcomponentOf field

---
 docs/features/software-catalog/descriptor-format.md    |  9 +++++++++
 docs/features/software-catalog/well-known-relations.md | 10 ++++++----
 2 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md
index 725f358b92..12d13069c3 100644
--- a/docs/features/software-catalog/descriptor-format.md
+++ b/docs/features/software-catalog/descriptor-format.md
@@ -454,6 +454,15 @@ belongs to, e.g. `artist-engagement-portal`. This field is optional.
 | --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
 | [`System`](#kind-system) (default)      | Same as this entity, typically `default`   | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) |
 
+### `spec.subcomponentOf` [optional]
+
+An [entity reference](#string-references) to another component of which the
+component is a part, e.g. `spotify-ios-app`. This field is optional.
+
+| [`kind`](#apiversion-and-kind-required)  | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type                            |
+| ---------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
+| [`Component`](#kind-component) (default) | Same as this entity, typically `default`   | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) |
+
 ### `spec.providesApis` [optional]
 
 An array of [entity references](#string-references) to the APIs that are
diff --git a/docs/features/software-catalog/well-known-relations.md b/docs/features/software-catalog/well-known-relations.md
index af2e7367f2..6fb7ae2fea 100644
--- a/docs/features/software-catalog/well-known-relations.md
+++ b/docs/features/software-catalog/well-known-relations.md
@@ -92,13 +92,15 @@ 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
+A relation with a [Domain](descriptor-format.md#kind-domain),
+[System](descriptor-format.md#kind-system) or
+[Component](descriptor-format.md#kind-component) 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.
+These relations express that a component belongs to a larger component; 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`.