From 856dfa1793c4aee02cdd33ca08c52728cfdca09c Mon Sep 17 00:00:00 2001
From: Ben Parees <bparees@redhat.com>
Date: Wed, 6 Sep 2017 21:56:03 -0400
Subject: [PATCH] deprecate imagestream dockerImageRepository field

---
 .../v1.ImageStream.adoc                       | 12 +++++-----
 .../v1.ImageStreamImport.adoc                 | 12 +++++-----
 .../v1.ImageStreamTag.adoc                    | 10 ++++----
 api/docs/oapi/v1.ImageStream.adoc             | 12 +++++-----
 api/docs/oapi/v1.ImageStreamImport.adoc       | 12 +++++-----
 api/docs/oapi/v1.ImageStreamTag.adoc          | 10 ++++----
 ...shift_origin_pkg_image_apis_image_v1.proto | 23 +++++++++++++------
 api/swagger-spec/oapi-v1.json                 | 12 +++++-----
 api/swagger-spec/openshift-openapi-spec.json  | 12 +++++-----
 pkg/image/apis/image/types.go                 |  4 +++-
 pkg/image/apis/image/v1/generated.proto       | 23 +++++++++++++------
 pkg/image/apis/image/v1/swagger_doc.go        | 12 +++++-----
 pkg/image/apis/image/v1/types.go              | 23 +++++++++++++------
 pkg/openapi/zz_generated.openapi.go           | 12 +++++-----
 14 files changed, 109 insertions(+), 80 deletions(-)

diff --git a/api/docs/apis-image.openshift.io/v1.ImageStream.adoc b/api/docs/apis-image.openshift.io/v1.ImageStream.adoc
index 2fcd6dd5c578..5dca04d55752 100644
--- a/api/docs/apis-image.openshift.io/v1.ImageStream.adoc
+++ b/api/docs/apis-image.openshift.io/v1.ImageStream.adoc
@@ -89,13 +89,13 @@ Populated by the system. Read-only. Value must be treated as opaque by clients a
 
 Populated by the system. Read-only. More info: http://kubernetes.io/docs/user-guide/identifiers#uids">uid</span>:
 </div></details><details open><summary><span title="(v1.ImageStreamSpec) Spec describes the desired state of this stream">spec</span>:
-</summary><div style="margin-left:13px;">  <span title="(string) dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server">dockerImageRepository</span>:
+</summary><div style="margin-left:13px;">  <span title="(string) dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server Deprecated: This field is deprecated as of v3.7 and will be removed in a future release. Specify the source for the tags to be imported in each tag via the spec.tags.from reference instead.">dockerImageRepository</span>:
 </div><details><summary>  <span title="(v1.ImageLookupPolicy) lookupPolicy controls how other resources reference images within this namespace.">lookupPolicy</span>:
 </summary><div style="margin-left:13px;">    <span title="(boolean) local will change the docker short image references (like &#34;mysql&#34; or &#34;php:latest&#34;) on objects in this namespace to the image ID whenever they match this image stream, instead of reaching out to a remote registry. The name will be fully qualified to an image ID if found. The tag&#39;s referencePolicy is taken into account on the replaced value. Only works within the current namespace.">local</span>:
 </div></details><details><summary>  <span title="(array) tags map arbitrary string values to specific image locators">tags</span>:
-</summary><details><summary>  - <span title="(object) Annotations associated with images using this tag">annotations</span>:
+</summary><details><summary>  - <span title="(object) Optional; if specified, annotations that are applied to images retrieved via ImageStreamTags.">annotations</span>:
 </summary><div style="margin-left:13px;">  -   <span title="(string)">[string]</span>:
-</div></details><details><summary>    <span title="(v1.ObjectReference) From is a reference to an image stream tag or image stream this tag should track">from</span>:
+</div></details><details><summary>    <span title="(v1.ObjectReference) Optional; if specified, a reference to another image that this tag should point to. Valid values are ImageStreamTag, ImageStreamImage, and DockerImage.">from</span>:
 </summary><div style="margin-left:13px;">      <span title="(string) API version of the referent.">apiVersion</span>:
 </div><div style="margin-left:13px;">      <span title="(string) If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: &#34;spec.containers{name}&#34; (where &#34;name&#34; refers to the name of the container that triggered the event) or if no container name is specified &#34;spec.containers[2]&#34; (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object.">fieldPath</span>:
 </div><div style="margin-left:13px;">      <span title="(string) Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds">kind</span>:
@@ -103,13 +103,13 @@ Populated by the system. Read-only. More info: http://kubernetes.io/docs/user-gu
 </div><div style="margin-left:13px;">      <span title="(string) Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/">namespace</span>:
 </div><div style="margin-left:13px;">      <span title="(string) Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#concurrency-control-and-consistency">resourceVersion</span>:
 </div><div style="margin-left:13px;">      <span title="(string) UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids">uid</span>:
-</div></details><div style="margin-left:13px;">    <span title="(integer) Generation is the image stream generation that updated this tag - setting it to 0 is an indication that the generation must be updated. Legacy clients will send this as nil, which means the client doesn&#39;t know or care.">generation</span>:
-</div><details><summary>    <span title="(v1.TagImportPolicy) Import is information that controls how images may be imported by the server.">importPolicy</span>:
+</div></details><div style="margin-left:13px;">    <span title="(integer) Generation is a counter that tracks mutations to the spec tag (user intent). When a tag reference is changed the generation is set to match the current stream generation (which is incremented every time spec is changed). Other processes in the system like the image importer observe that the generation of spec tag is newer than the generation recorded in the status and use that as a trigger to import the newest remote tag. To trigger a new import, clients may set this value to zero which will reset the generation to the latest stream generation. Legacy clients will send this value as nil which will be merged with the current tag generation.">generation</span>:
+</div><details><summary>    <span title="(v1.TagImportPolicy) ImportPolicy is information that controls how images may be imported by the server.">importPolicy</span>:
 </summary><div style="margin-left:13px;">      <span title="(boolean) Insecure is true if the server may bypass certificate verification or connect directly over HTTP during image import.">insecure</span>:
 </div><div style="margin-left:13px;">      <span title="(boolean) Scheduled indicates to the server that this tag should be periodically checked to ensure it is up to date, and imported">scheduled</span>:
 </div></details><div style="margin-left:13px;">    <span title="(string) Name of the tag">name</span>:
 </div><div style="margin-left:13px;">    <span title="(boolean) Reference states if the tag will be imported. Default value is false, which means the tag will be imported.">reference</span>:
-</div><details><summary>    <span title="(v1.TagReferencePolicy) ReferencePolicy defines how other components should consume the image">referencePolicy</span>:
+</div><details><summary>    <span title="(v1.TagReferencePolicy) ReferencePolicy defines how other components should consume the image.">referencePolicy</span>:
 </summary><div style="margin-left:13px;">      <span title="(string) Type determines how the image pull spec should be transformed when the image stream tag is used in deployment config triggers or new builds. The default value is `Source`, indicating the original location of the image should be used (if imported). The user may also specify `Local`, indicating that the pull spec should point to the integrated Docker registry and leverage the registry&#39;s ability to proxy the pull to an upstream registry. `Local` allows the credentials used to pull this image to be managed from the image stream&#39;s namespace, so others on the platform can access a remote image but have no access to the remote secret. It also allows the image layers to be mirrored into the local registry which the images can still be pulled even if the upstream registry is unavailable.">type</span>:
 </div></details></details></details><details><summary><span title="(v1.ImageStreamStatus) Status describes the current state of this stream">status</span>:
 </summary><div style="margin-left:13px;">  <span title="(string) DockerImageRepository represents the effective location this stream may be accessed at. May be empty until the server determines where the repository is located">dockerImageRepository</span>:
diff --git a/api/docs/apis-image.openshift.io/v1.ImageStreamImport.adoc b/api/docs/apis-image.openshift.io/v1.ImageStreamImport.adoc
index 71802e09b6e7..c70bc8bbbc7c 100644
--- a/api/docs/apis-image.openshift.io/v1.ImageStreamImport.adoc
+++ b/api/docs/apis-image.openshift.io/v1.ImageStreamImport.adoc
@@ -398,13 +398,13 @@ Populated by the system. Read-only. Value must be treated as opaque by clients a
 
 Populated by the system. Read-only. More info: http://kubernetes.io/docs/user-guide/identifiers#uids">uid</span>:
 </div></details><details><summary>    <span title="(v1.ImageStreamSpec) Spec describes the desired state of this stream">spec</span>:
-</summary><div style="margin-left:13px;">      <span title="(string) dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server">dockerImageRepository</span>:
+</summary><div style="margin-left:13px;">      <span title="(string) dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server Deprecated: This field is deprecated as of v3.7 and will be removed in a future release. Specify the source for the tags to be imported in each tag via the spec.tags.from reference instead.">dockerImageRepository</span>:
 </div><details><summary>      <span title="(v1.ImageLookupPolicy) lookupPolicy controls how other resources reference images within this namespace.">lookupPolicy</span>:
 </summary><div style="margin-left:13px;">        <span title="(boolean) local will change the docker short image references (like &#34;mysql&#34; or &#34;php:latest&#34;) on objects in this namespace to the image ID whenever they match this image stream, instead of reaching out to a remote registry. The name will be fully qualified to an image ID if found. The tag&#39;s referencePolicy is taken into account on the replaced value. Only works within the current namespace.">local</span>:
 </div></details><details><summary>      <span title="(array) tags map arbitrary string values to specific image locators">tags</span>:
-</summary><details><summary>      - <span title="(object) Annotations associated with images using this tag">annotations</span>:
+</summary><details><summary>      - <span title="(object) Optional; if specified, annotations that are applied to images retrieved via ImageStreamTags.">annotations</span>:
 </summary><div style="margin-left:13px;">      -   <span title="(string)">[string]</span>:
-</div></details><details><summary>        <span title="(v1.ObjectReference) From is a reference to an image stream tag or image stream this tag should track">from</span>:
+</div></details><details><summary>        <span title="(v1.ObjectReference) Optional; if specified, a reference to another image that this tag should point to. Valid values are ImageStreamTag, ImageStreamImage, and DockerImage.">from</span>:
 </summary><div style="margin-left:13px;">          <span title="(string) API version of the referent.">apiVersion</span>:
 </div><div style="margin-left:13px;">          <span title="(string) If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: &#34;spec.containers{name}&#34; (where &#34;name&#34; refers to the name of the container that triggered the event) or if no container name is specified &#34;spec.containers[2]&#34; (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object.">fieldPath</span>:
 </div><div style="margin-left:13px;">          <span title="(string) Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds">kind</span>:
@@ -412,13 +412,13 @@ Populated by the system. Read-only. More info: http://kubernetes.io/docs/user-gu
 </div><div style="margin-left:13px;">          <span title="(string) Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/">namespace</span>:
 </div><div style="margin-left:13px;">          <span title="(string) Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#concurrency-control-and-consistency">resourceVersion</span>:
 </div><div style="margin-left:13px;">          <span title="(string) UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids">uid</span>:
-</div></details><div style="margin-left:13px;">        <span title="(integer) Generation is the image stream generation that updated this tag - setting it to 0 is an indication that the generation must be updated. Legacy clients will send this as nil, which means the client doesn&#39;t know or care.">generation</span>:
-</div><details><summary>        <span title="(v1.TagImportPolicy) Import is information that controls how images may be imported by the server.">importPolicy</span>:
+</div></details><div style="margin-left:13px;">        <span title="(integer) Generation is a counter that tracks mutations to the spec tag (user intent). When a tag reference is changed the generation is set to match the current stream generation (which is incremented every time spec is changed). Other processes in the system like the image importer observe that the generation of spec tag is newer than the generation recorded in the status and use that as a trigger to import the newest remote tag. To trigger a new import, clients may set this value to zero which will reset the generation to the latest stream generation. Legacy clients will send this value as nil which will be merged with the current tag generation.">generation</span>:
+</div><details><summary>        <span title="(v1.TagImportPolicy) ImportPolicy is information that controls how images may be imported by the server.">importPolicy</span>:
 </summary><div style="margin-left:13px;">          <span title="(boolean) Insecure is true if the server may bypass certificate verification or connect directly over HTTP during image import.">insecure</span>:
 </div><div style="margin-left:13px;">          <span title="(boolean) Scheduled indicates to the server that this tag should be periodically checked to ensure it is up to date, and imported">scheduled</span>:
 </div></details><div style="margin-left:13px;">        <span title="(string) Name of the tag">name</span>:
 </div><div style="margin-left:13px;">        <span title="(boolean) Reference states if the tag will be imported. Default value is false, which means the tag will be imported.">reference</span>:
-</div><details><summary>        <span title="(v1.TagReferencePolicy) ReferencePolicy defines how other components should consume the image">referencePolicy</span>:
+</div><details><summary>        <span title="(v1.TagReferencePolicy) ReferencePolicy defines how other components should consume the image.">referencePolicy</span>:
 </summary><div style="margin-left:13px;">          <span title="(string) Type determines how the image pull spec should be transformed when the image stream tag is used in deployment config triggers or new builds. The default value is `Source`, indicating the original location of the image should be used (if imported). The user may also specify `Local`, indicating that the pull spec should point to the integrated Docker registry and leverage the registry&#39;s ability to proxy the pull to an upstream registry. `Local` allows the credentials used to pull this image to be managed from the image stream&#39;s namespace, so others on the platform can access a remote image but have no access to the remote secret. It also allows the image layers to be mirrored into the local registry which the images can still be pulled even if the upstream registry is unavailable.">type</span>:
 </div></details></details></details><details><summary>    <span title="(v1.ImageStreamStatus) Status describes the current state of this stream">status</span>:
 </summary><div style="margin-left:13px;">      <span title="(string) DockerImageRepository represents the effective location this stream may be accessed at. May be empty until the server determines where the repository is located">dockerImageRepository</span>:
diff --git a/api/docs/apis-image.openshift.io/v1.ImageStreamTag.adoc b/api/docs/apis-image.openshift.io/v1.ImageStreamTag.adoc
index 66dcee124523..978bee310632 100644
--- a/api/docs/apis-image.openshift.io/v1.ImageStreamTag.adoc
+++ b/api/docs/apis-image.openshift.io/v1.ImageStreamTag.adoc
@@ -274,9 +274,9 @@ Populated by the system. Read-only. Value must be treated as opaque by clients a
 
 Populated by the system. Read-only. More info: http://kubernetes.io/docs/user-guide/identifiers#uids">uid</span>:
 </div></details><details><summary><span title="(v1.TagReference) tag is the spec tag associated with this image stream tag, and it may be null if only pushes have occurred to this image stream.">tag</span>:
-</summary><details><summary>  <span title="(object) Annotations associated with images using this tag">annotations</span>:
+</summary><details><summary>  <span title="(object) Optional; if specified, annotations that are applied to images retrieved via ImageStreamTags.">annotations</span>:
 </summary><div style="margin-left:13px;">    <span title="(string)">[string]</span>:
-</div></details><details><summary>  <span title="(v1.ObjectReference) From is a reference to an image stream tag or image stream this tag should track">from</span>:
+</div></details><details><summary>  <span title="(v1.ObjectReference) Optional; if specified, a reference to another image that this tag should point to. Valid values are ImageStreamTag, ImageStreamImage, and DockerImage.">from</span>:
 </summary><div style="margin-left:13px;">    <span title="(string) API version of the referent.">apiVersion</span>:
 </div><div style="margin-left:13px;">    <span title="(string) If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: &#34;spec.containers{name}&#34; (where &#34;name&#34; refers to the name of the container that triggered the event) or if no container name is specified &#34;spec.containers[2]&#34; (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object.">fieldPath</span>:
 </div><div style="margin-left:13px;">    <span title="(string) Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds">kind</span>:
@@ -284,13 +284,13 @@ Populated by the system. Read-only. More info: http://kubernetes.io/docs/user-gu
 </div><div style="margin-left:13px;">    <span title="(string) Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/">namespace</span>:
 </div><div style="margin-left:13px;">    <span title="(string) Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#concurrency-control-and-consistency">resourceVersion</span>:
 </div><div style="margin-left:13px;">    <span title="(string) UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids">uid</span>:
-</div></details><div style="margin-left:13px;">  <span title="(integer) Generation is the image stream generation that updated this tag - setting it to 0 is an indication that the generation must be updated. Legacy clients will send this as nil, which means the client doesn&#39;t know or care.">generation</span>:
-</div><details><summary>  <span title="(v1.TagImportPolicy) Import is information that controls how images may be imported by the server.">importPolicy</span>:
+</div></details><div style="margin-left:13px;">  <span title="(integer) Generation is a counter that tracks mutations to the spec tag (user intent). When a tag reference is changed the generation is set to match the current stream generation (which is incremented every time spec is changed). Other processes in the system like the image importer observe that the generation of spec tag is newer than the generation recorded in the status and use that as a trigger to import the newest remote tag. To trigger a new import, clients may set this value to zero which will reset the generation to the latest stream generation. Legacy clients will send this value as nil which will be merged with the current tag generation.">generation</span>:
+</div><details><summary>  <span title="(v1.TagImportPolicy) ImportPolicy is information that controls how images may be imported by the server.">importPolicy</span>:
 </summary><div style="margin-left:13px;">    <span title="(boolean) Insecure is true if the server may bypass certificate verification or connect directly over HTTP during image import.">insecure</span>:
 </div><div style="margin-left:13px;">    <span title="(boolean) Scheduled indicates to the server that this tag should be periodically checked to ensure it is up to date, and imported">scheduled</span>:
 </div></details><div style="margin-left:13px;">  <span title="(string) Name of the tag">name</span>:
 </div><div style="margin-left:13px;">  <span title="(boolean) Reference states if the tag will be imported. Default value is false, which means the tag will be imported.">reference</span>:
-</div><details><summary>  <span title="(v1.TagReferencePolicy) ReferencePolicy defines how other components should consume the image">referencePolicy</span>:
+</div><details><summary>  <span title="(v1.TagReferencePolicy) ReferencePolicy defines how other components should consume the image.">referencePolicy</span>:
 </summary><div style="margin-left:13px;">    <span title="(string) Type determines how the image pull spec should be transformed when the image stream tag is used in deployment config triggers or new builds. The default value is `Source`, indicating the original location of the image should be used (if imported). The user may also specify `Local`, indicating that the pull spec should point to the integrated Docker registry and leverage the registry&#39;s ability to proxy the pull to an upstream registry. `Local` allows the credentials used to pull this image to be managed from the image stream&#39;s namespace, so others on the platform can access a remote image but have no access to the remote secret. It also allows the image layers to be mirrored into the local registry which the images can still be pulled even if the upstream registry is unavailable.">type</span>:
 </div></details></details>
 </pre>
diff --git a/api/docs/oapi/v1.ImageStream.adoc b/api/docs/oapi/v1.ImageStream.adoc
index 5d2efbf315d1..fd043e7667ae 100644
--- a/api/docs/oapi/v1.ImageStream.adoc
+++ b/api/docs/oapi/v1.ImageStream.adoc
@@ -89,13 +89,13 @@ Populated by the system. Read-only. Value must be treated as opaque by clients a
 
 Populated by the system. Read-only. More info: http://kubernetes.io/docs/user-guide/identifiers#uids">uid</span>:
 </div></details><details open><summary><span title="(v1.ImageStreamSpec) Spec describes the desired state of this stream">spec</span>:
-</summary><div style="margin-left:13px;">  <span title="(string) dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server">dockerImageRepository</span>:
+</summary><div style="margin-left:13px;">  <span title="(string) dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server Deprecated: This field is deprecated as of v3.7 and will be removed in a future release. Specify the source for the tags to be imported in each tag via the spec.tags.from reference instead.">dockerImageRepository</span>:
 </div><details><summary>  <span title="(v1.ImageLookupPolicy) lookupPolicy controls how other resources reference images within this namespace.">lookupPolicy</span>:
 </summary><div style="margin-left:13px;">    <span title="(boolean) local will change the docker short image references (like &#34;mysql&#34; or &#34;php:latest&#34;) on objects in this namespace to the image ID whenever they match this image stream, instead of reaching out to a remote registry. The name will be fully qualified to an image ID if found. The tag&#39;s referencePolicy is taken into account on the replaced value. Only works within the current namespace.">local</span>:
 </div></details><details><summary>  <span title="(array) tags map arbitrary string values to specific image locators">tags</span>:
-</summary><details><summary>  - <span title="(object) Annotations associated with images using this tag">annotations</span>:
+</summary><details><summary>  - <span title="(object) Optional; if specified, annotations that are applied to images retrieved via ImageStreamTags.">annotations</span>:
 </summary><div style="margin-left:13px;">  -   <span title="(string)">[string]</span>:
-</div></details><details><summary>    <span title="(v1.ObjectReference) From is a reference to an image stream tag or image stream this tag should track">from</span>:
+</div></details><details><summary>    <span title="(v1.ObjectReference) Optional; if specified, a reference to another image that this tag should point to. Valid values are ImageStreamTag, ImageStreamImage, and DockerImage.">from</span>:
 </summary><div style="margin-left:13px;">      <span title="(string) API version of the referent.">apiVersion</span>:
 </div><div style="margin-left:13px;">      <span title="(string) If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: &#34;spec.containers{name}&#34; (where &#34;name&#34; refers to the name of the container that triggered the event) or if no container name is specified &#34;spec.containers[2]&#34; (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object.">fieldPath</span>:
 </div><div style="margin-left:13px;">      <span title="(string) Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds">kind</span>:
@@ -103,13 +103,13 @@ Populated by the system. Read-only. More info: http://kubernetes.io/docs/user-gu
 </div><div style="margin-left:13px;">      <span title="(string) Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/">namespace</span>:
 </div><div style="margin-left:13px;">      <span title="(string) Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#concurrency-control-and-consistency">resourceVersion</span>:
 </div><div style="margin-left:13px;">      <span title="(string) UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids">uid</span>:
-</div></details><div style="margin-left:13px;">    <span title="(integer) Generation is the image stream generation that updated this tag - setting it to 0 is an indication that the generation must be updated. Legacy clients will send this as nil, which means the client doesn&#39;t know or care.">generation</span>:
-</div><details><summary>    <span title="(v1.TagImportPolicy) Import is information that controls how images may be imported by the server.">importPolicy</span>:
+</div></details><div style="margin-left:13px;">    <span title="(integer) Generation is a counter that tracks mutations to the spec tag (user intent). When a tag reference is changed the generation is set to match the current stream generation (which is incremented every time spec is changed). Other processes in the system like the image importer observe that the generation of spec tag is newer than the generation recorded in the status and use that as a trigger to import the newest remote tag. To trigger a new import, clients may set this value to zero which will reset the generation to the latest stream generation. Legacy clients will send this value as nil which will be merged with the current tag generation.">generation</span>:
+</div><details><summary>    <span title="(v1.TagImportPolicy) ImportPolicy is information that controls how images may be imported by the server.">importPolicy</span>:
 </summary><div style="margin-left:13px;">      <span title="(boolean) Insecure is true if the server may bypass certificate verification or connect directly over HTTP during image import.">insecure</span>:
 </div><div style="margin-left:13px;">      <span title="(boolean) Scheduled indicates to the server that this tag should be periodically checked to ensure it is up to date, and imported">scheduled</span>:
 </div></details><div style="margin-left:13px;">    <span title="(string) Name of the tag">name</span>:
 </div><div style="margin-left:13px;">    <span title="(boolean) Reference states if the tag will be imported. Default value is false, which means the tag will be imported.">reference</span>:
-</div><details><summary>    <span title="(v1.TagReferencePolicy) ReferencePolicy defines how other components should consume the image">referencePolicy</span>:
+</div><details><summary>    <span title="(v1.TagReferencePolicy) ReferencePolicy defines how other components should consume the image.">referencePolicy</span>:
 </summary><div style="margin-left:13px;">      <span title="(string) Type determines how the image pull spec should be transformed when the image stream tag is used in deployment config triggers or new builds. The default value is `Source`, indicating the original location of the image should be used (if imported). The user may also specify `Local`, indicating that the pull spec should point to the integrated Docker registry and leverage the registry&#39;s ability to proxy the pull to an upstream registry. `Local` allows the credentials used to pull this image to be managed from the image stream&#39;s namespace, so others on the platform can access a remote image but have no access to the remote secret. It also allows the image layers to be mirrored into the local registry which the images can still be pulled even if the upstream registry is unavailable.">type</span>:
 </div></details></details></details><details><summary><span title="(v1.ImageStreamStatus) Status describes the current state of this stream">status</span>:
 </summary><div style="margin-left:13px;">  <span title="(string) DockerImageRepository represents the effective location this stream may be accessed at. May be empty until the server determines where the repository is located">dockerImageRepository</span>:
diff --git a/api/docs/oapi/v1.ImageStreamImport.adoc b/api/docs/oapi/v1.ImageStreamImport.adoc
index a7c9dd0f44e8..977f0419cc52 100644
--- a/api/docs/oapi/v1.ImageStreamImport.adoc
+++ b/api/docs/oapi/v1.ImageStreamImport.adoc
@@ -398,13 +398,13 @@ Populated by the system. Read-only. Value must be treated as opaque by clients a
 
 Populated by the system. Read-only. More info: http://kubernetes.io/docs/user-guide/identifiers#uids">uid</span>:
 </div></details><details><summary>    <span title="(v1.ImageStreamSpec) Spec describes the desired state of this stream">spec</span>:
-</summary><div style="margin-left:13px;">      <span title="(string) dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server">dockerImageRepository</span>:
+</summary><div style="margin-left:13px;">      <span title="(string) dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server Deprecated: This field is deprecated as of v3.7 and will be removed in a future release. Specify the source for the tags to be imported in each tag via the spec.tags.from reference instead.">dockerImageRepository</span>:
 </div><details><summary>      <span title="(v1.ImageLookupPolicy) lookupPolicy controls how other resources reference images within this namespace.">lookupPolicy</span>:
 </summary><div style="margin-left:13px;">        <span title="(boolean) local will change the docker short image references (like &#34;mysql&#34; or &#34;php:latest&#34;) on objects in this namespace to the image ID whenever they match this image stream, instead of reaching out to a remote registry. The name will be fully qualified to an image ID if found. The tag&#39;s referencePolicy is taken into account on the replaced value. Only works within the current namespace.">local</span>:
 </div></details><details><summary>      <span title="(array) tags map arbitrary string values to specific image locators">tags</span>:
-</summary><details><summary>      - <span title="(object) Annotations associated with images using this tag">annotations</span>:
+</summary><details><summary>      - <span title="(object) Optional; if specified, annotations that are applied to images retrieved via ImageStreamTags.">annotations</span>:
 </summary><div style="margin-left:13px;">      -   <span title="(string)">[string]</span>:
-</div></details><details><summary>        <span title="(v1.ObjectReference) From is a reference to an image stream tag or image stream this tag should track">from</span>:
+</div></details><details><summary>        <span title="(v1.ObjectReference) Optional; if specified, a reference to another image that this tag should point to. Valid values are ImageStreamTag, ImageStreamImage, and DockerImage.">from</span>:
 </summary><div style="margin-left:13px;">          <span title="(string) API version of the referent.">apiVersion</span>:
 </div><div style="margin-left:13px;">          <span title="(string) If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: &#34;spec.containers{name}&#34; (where &#34;name&#34; refers to the name of the container that triggered the event) or if no container name is specified &#34;spec.containers[2]&#34; (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object.">fieldPath</span>:
 </div><div style="margin-left:13px;">          <span title="(string) Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds">kind</span>:
@@ -412,13 +412,13 @@ Populated by the system. Read-only. More info: http://kubernetes.io/docs/user-gu
 </div><div style="margin-left:13px;">          <span title="(string) Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/">namespace</span>:
 </div><div style="margin-left:13px;">          <span title="(string) Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#concurrency-control-and-consistency">resourceVersion</span>:
 </div><div style="margin-left:13px;">          <span title="(string) UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids">uid</span>:
-</div></details><div style="margin-left:13px;">        <span title="(integer) Generation is the image stream generation that updated this tag - setting it to 0 is an indication that the generation must be updated. Legacy clients will send this as nil, which means the client doesn&#39;t know or care.">generation</span>:
-</div><details><summary>        <span title="(v1.TagImportPolicy) Import is information that controls how images may be imported by the server.">importPolicy</span>:
+</div></details><div style="margin-left:13px;">        <span title="(integer) Generation is a counter that tracks mutations to the spec tag (user intent). When a tag reference is changed the generation is set to match the current stream generation (which is incremented every time spec is changed). Other processes in the system like the image importer observe that the generation of spec tag is newer than the generation recorded in the status and use that as a trigger to import the newest remote tag. To trigger a new import, clients may set this value to zero which will reset the generation to the latest stream generation. Legacy clients will send this value as nil which will be merged with the current tag generation.">generation</span>:
+</div><details><summary>        <span title="(v1.TagImportPolicy) ImportPolicy is information that controls how images may be imported by the server.">importPolicy</span>:
 </summary><div style="margin-left:13px;">          <span title="(boolean) Insecure is true if the server may bypass certificate verification or connect directly over HTTP during image import.">insecure</span>:
 </div><div style="margin-left:13px;">          <span title="(boolean) Scheduled indicates to the server that this tag should be periodically checked to ensure it is up to date, and imported">scheduled</span>:
 </div></details><div style="margin-left:13px;">        <span title="(string) Name of the tag">name</span>:
 </div><div style="margin-left:13px;">        <span title="(boolean) Reference states if the tag will be imported. Default value is false, which means the tag will be imported.">reference</span>:
-</div><details><summary>        <span title="(v1.TagReferencePolicy) ReferencePolicy defines how other components should consume the image">referencePolicy</span>:
+</div><details><summary>        <span title="(v1.TagReferencePolicy) ReferencePolicy defines how other components should consume the image.">referencePolicy</span>:
 </summary><div style="margin-left:13px;">          <span title="(string) Type determines how the image pull spec should be transformed when the image stream tag is used in deployment config triggers or new builds. The default value is `Source`, indicating the original location of the image should be used (if imported). The user may also specify `Local`, indicating that the pull spec should point to the integrated Docker registry and leverage the registry&#39;s ability to proxy the pull to an upstream registry. `Local` allows the credentials used to pull this image to be managed from the image stream&#39;s namespace, so others on the platform can access a remote image but have no access to the remote secret. It also allows the image layers to be mirrored into the local registry which the images can still be pulled even if the upstream registry is unavailable.">type</span>:
 </div></details></details></details><details><summary>    <span title="(v1.ImageStreamStatus) Status describes the current state of this stream">status</span>:
 </summary><div style="margin-left:13px;">      <span title="(string) DockerImageRepository represents the effective location this stream may be accessed at. May be empty until the server determines where the repository is located">dockerImageRepository</span>:
diff --git a/api/docs/oapi/v1.ImageStreamTag.adoc b/api/docs/oapi/v1.ImageStreamTag.adoc
index d5c4c0f431fe..d1283ebf78c7 100644
--- a/api/docs/oapi/v1.ImageStreamTag.adoc
+++ b/api/docs/oapi/v1.ImageStreamTag.adoc
@@ -274,9 +274,9 @@ Populated by the system. Read-only. Value must be treated as opaque by clients a
 
 Populated by the system. Read-only. More info: http://kubernetes.io/docs/user-guide/identifiers#uids">uid</span>:
 </div></details><details><summary><span title="(v1.TagReference) tag is the spec tag associated with this image stream tag, and it may be null if only pushes have occurred to this image stream.">tag</span>:
-</summary><details><summary>  <span title="(object) Annotations associated with images using this tag">annotations</span>:
+</summary><details><summary>  <span title="(object) Optional; if specified, annotations that are applied to images retrieved via ImageStreamTags.">annotations</span>:
 </summary><div style="margin-left:13px;">    <span title="(string)">[string]</span>:
-</div></details><details><summary>  <span title="(v1.ObjectReference) From is a reference to an image stream tag or image stream this tag should track">from</span>:
+</div></details><details><summary>  <span title="(v1.ObjectReference) Optional; if specified, a reference to another image that this tag should point to. Valid values are ImageStreamTag, ImageStreamImage, and DockerImage.">from</span>:
 </summary><div style="margin-left:13px;">    <span title="(string) API version of the referent.">apiVersion</span>:
 </div><div style="margin-left:13px;">    <span title="(string) If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: &#34;spec.containers{name}&#34; (where &#34;name&#34; refers to the name of the container that triggered the event) or if no container name is specified &#34;spec.containers[2]&#34; (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object.">fieldPath</span>:
 </div><div style="margin-left:13px;">    <span title="(string) Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds">kind</span>:
@@ -284,13 +284,13 @@ Populated by the system. Read-only. More info: http://kubernetes.io/docs/user-gu
 </div><div style="margin-left:13px;">    <span title="(string) Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/">namespace</span>:
 </div><div style="margin-left:13px;">    <span title="(string) Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#concurrency-control-and-consistency">resourceVersion</span>:
 </div><div style="margin-left:13px;">    <span title="(string) UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids">uid</span>:
-</div></details><div style="margin-left:13px;">  <span title="(integer) Generation is the image stream generation that updated this tag - setting it to 0 is an indication that the generation must be updated. Legacy clients will send this as nil, which means the client doesn&#39;t know or care.">generation</span>:
-</div><details><summary>  <span title="(v1.TagImportPolicy) Import is information that controls how images may be imported by the server.">importPolicy</span>:
+</div></details><div style="margin-left:13px;">  <span title="(integer) Generation is a counter that tracks mutations to the spec tag (user intent). When a tag reference is changed the generation is set to match the current stream generation (which is incremented every time spec is changed). Other processes in the system like the image importer observe that the generation of spec tag is newer than the generation recorded in the status and use that as a trigger to import the newest remote tag. To trigger a new import, clients may set this value to zero which will reset the generation to the latest stream generation. Legacy clients will send this value as nil which will be merged with the current tag generation.">generation</span>:
+</div><details><summary>  <span title="(v1.TagImportPolicy) ImportPolicy is information that controls how images may be imported by the server.">importPolicy</span>:
 </summary><div style="margin-left:13px;">    <span title="(boolean) Insecure is true if the server may bypass certificate verification or connect directly over HTTP during image import.">insecure</span>:
 </div><div style="margin-left:13px;">    <span title="(boolean) Scheduled indicates to the server that this tag should be periodically checked to ensure it is up to date, and imported">scheduled</span>:
 </div></details><div style="margin-left:13px;">  <span title="(string) Name of the tag">name</span>:
 </div><div style="margin-left:13px;">  <span title="(boolean) Reference states if the tag will be imported. Default value is false, which means the tag will be imported.">reference</span>:
-</div><details><summary>  <span title="(v1.TagReferencePolicy) ReferencePolicy defines how other components should consume the image">referencePolicy</span>:
+</div><details><summary>  <span title="(v1.TagReferencePolicy) ReferencePolicy defines how other components should consume the image.">referencePolicy</span>:
 </summary><div style="margin-left:13px;">    <span title="(string) Type determines how the image pull spec should be transformed when the image stream tag is used in deployment config triggers or new builds. The default value is `Source`, indicating the original location of the image should be used (if imported). The user may also specify `Local`, indicating that the pull spec should point to the integrated Docker registry and leverage the registry&#39;s ability to proxy the pull to an upstream registry. `Local` allows the credentials used to pull this image to be managed from the image stream&#39;s namespace, so others on the platform can access a remote image but have no access to the remote secret. It also allows the image layers to be mirrored into the local registry which the images can still be pulled even if the upstream registry is unavailable.">type</span>:
 </div></details></details>
 </pre>
diff --git a/api/protobuf-spec/github_com_openshift_origin_pkg_image_apis_image_v1.proto b/api/protobuf-spec/github_com_openshift_origin_pkg_image_apis_image_v1.proto
index bca0e2c04eef..34c91b297553 100644
--- a/api/protobuf-spec/github_com_openshift_origin_pkg_image_apis_image_v1.proto
+++ b/api/protobuf-spec/github_com_openshift_origin_pkg_image_apis_image_v1.proto
@@ -265,6 +265,8 @@ message ImageStreamSpec {
   optional ImageLookupPolicy lookupPolicy = 3;
 
   // dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server
+  // Deprecated: This field is deprecated as of v3.7 and will be removed in a future release.
+  // Specify the source for the tags to be imported in each tag via the spec.tags.from reference instead.
   optional string dockerImageRepository = 1;
 
   // tags map arbitrary string values to specific image locators
@@ -458,23 +460,30 @@ message TagReference {
   // Name of the tag
   optional string name = 1;
 
-  // Annotations associated with images using this tag
+  // Optional; if specified, annotations that are applied to images retrieved via ImageStreamTags.
   map<string, string> annotations = 2;
 
-  // From is a reference to an image stream tag or image stream this tag should track
+  // Optional; if specified, a reference to another image that this tag should point to. Valid values
+  // are ImageStreamTag, ImageStreamImage, and DockerImage.
   optional k8s.io.kubernetes.pkg.api.v1.ObjectReference from = 3;
 
-  // Reference states if the tag will be imported. Default value is false, which means the tag will be imported.
+  // Reference states if the tag will be imported. Default value is false, which means the tag will
+  // be imported.
   optional bool reference = 4;
 
-  // Generation is the image stream generation that updated this tag - setting it to 0 is an indication that the generation must be updated.
-  // Legacy clients will send this as nil, which means the client doesn't know or care.
+  // Generation is a counter that tracks mutations to the spec tag (user intent). When a tag reference
+  // is changed the generation is set to match the current stream generation (which is incremented every
+  // time spec is changed). Other processes in the system like the image importer observe that the
+  // generation of spec tag is newer than the generation recorded in the status and use that as a trigger
+  // to import the newest remote tag. To trigger a new import, clients may set this value to zero which
+  // will reset the generation to the latest stream generation. Legacy clients will send this value as
+  // nil which will be merged with the current tag generation.
   optional int64 generation = 5;
 
-  // Import is information that controls how images may be imported by the server.
+  // ImportPolicy is information that controls how images may be imported by the server.
   optional TagImportPolicy importPolicy = 6;
 
-  // ReferencePolicy defines how other components should consume the image
+  // ReferencePolicy defines how other components should consume the image.
   optional TagReferencePolicy referencePolicy = 7;
 }
 
diff --git a/api/swagger-spec/oapi-v1.json b/api/swagger-spec/oapi-v1.json
index 2523db9fe154..9b192c3c346e 100644
--- a/api/swagger-spec/oapi-v1.json
+++ b/api/swagger-spec/oapi-v1.json
@@ -26292,7 +26292,7 @@
      },
      "dockerImageRepository": {
       "type": "string",
-      "description": "dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server"
+      "description": "dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server Deprecated: This field is deprecated as of v3.7 and will be removed in a future release. Specify the source for the tags to be imported in each tag via the spec.tags.from reference instead."
      },
      "tags": {
       "type": "array",
@@ -26331,11 +26331,11 @@
      },
      "annotations": {
       "type": "object",
-      "description": "Annotations associated with images using this tag"
+      "description": "Optional; if specified, annotations that are applied to images retrieved via ImageStreamTags."
      },
      "from": {
       "$ref": "v1.ObjectReference",
-      "description": "From is a reference to an image stream tag or image stream this tag should track"
+      "description": "Optional; if specified, a reference to another image that this tag should point to. Valid values are ImageStreamTag, ImageStreamImage, and DockerImage."
      },
      "reference": {
       "type": "boolean",
@@ -26344,15 +26344,15 @@
      "generation": {
       "type": "integer",
       "format": "int64",
-      "description": "Generation is the image stream generation that updated this tag - setting it to 0 is an indication that the generation must be updated. Legacy clients will send this as nil, which means the client doesn't know or care."
+      "description": "Generation is a counter that tracks mutations to the spec tag (user intent). When a tag reference is changed the generation is set to match the current stream generation (which is incremented every time spec is changed). Other processes in the system like the image importer observe that the generation of spec tag is newer than the generation recorded in the status and use that as a trigger to import the newest remote tag. To trigger a new import, clients may set this value to zero which will reset the generation to the latest stream generation. Legacy clients will send this value as nil which will be merged with the current tag generation."
      },
      "importPolicy": {
       "$ref": "v1.TagImportPolicy",
-      "description": "Import is information that controls how images may be imported by the server."
+      "description": "ImportPolicy is information that controls how images may be imported by the server."
      },
      "referencePolicy": {
       "$ref": "v1.TagReferencePolicy",
-      "description": "ReferencePolicy defines how other components should consume the image"
+      "description": "ReferencePolicy defines how other components should consume the image."
      }
     }
    },
diff --git a/api/swagger-spec/openshift-openapi-spec.json b/api/swagger-spec/openshift-openapi-spec.json
index 7a950723a4e3..54c26908a056 100644
--- a/api/swagger-spec/openshift-openapi-spec.json
+++ b/api/swagger-spec/openshift-openapi-spec.json
@@ -90332,7 +90332,7 @@
     "description": "ImageStreamSpec represents options for ImageStreams.",
     "properties": {
      "dockerImageRepository": {
-      "description": "dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server",
+      "description": "dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server Deprecated: This field is deprecated as of v3.7 and will be removed in a future release. Specify the source for the tags to be imported in each tag via the spec.tags.from reference instead.",
       "type": "string"
      },
      "lookupPolicy": {
@@ -90694,23 +90694,23 @@
     ],
     "properties": {
      "annotations": {
-      "description": "Annotations associated with images using this tag",
+      "description": "Optional; if specified, annotations that are applied to images retrieved via ImageStreamTags.",
       "type": "object",
       "additionalProperties": {
        "type": "string"
       }
      },
      "from": {
-      "description": "From is a reference to an image stream tag or image stream this tag should track",
+      "description": "Optional; if specified, a reference to another image that this tag should point to. Valid values are ImageStreamTag, ImageStreamImage, and DockerImage.",
       "$ref": "#/definitions/io.k8s.kubernetes.pkg.api.v1.ObjectReference"
      },
      "generation": {
-      "description": "Generation is the image stream generation that updated this tag - setting it to 0 is an indication that the generation must be updated. Legacy clients will send this as nil, which means the client doesn't know or care.",
+      "description": "Generation is a counter that tracks mutations to the spec tag (user intent). When a tag reference is changed the generation is set to match the current stream generation (which is incremented every time spec is changed). Other processes in the system like the image importer observe that the generation of spec tag is newer than the generation recorded in the status and use that as a trigger to import the newest remote tag. To trigger a new import, clients may set this value to zero which will reset the generation to the latest stream generation. Legacy clients will send this value as nil which will be merged with the current tag generation.",
       "type": "integer",
       "format": "int64"
      },
      "importPolicy": {
-      "description": "Import is information that controls how images may be imported by the server.",
+      "description": "ImportPolicy is information that controls how images may be imported by the server.",
       "$ref": "#/definitions/com.github.openshift.origin.pkg.image.apis.image.v1.TagImportPolicy"
      },
      "name": {
@@ -90722,7 +90722,7 @@
       "type": "boolean"
      },
      "referencePolicy": {
-      "description": "ReferencePolicy defines how other components should consume the image",
+      "description": "ReferencePolicy defines how other components should consume the image.",
       "$ref": "#/definitions/com.github.openshift.origin.pkg.image.apis.image.v1.TagReferencePolicy"
      }
     }
diff --git a/pkg/image/apis/image/types.go b/pkg/image/apis/image/types.go
index 2aae668f3ff9..5eca798be486 100644
--- a/pkg/image/apis/image/types.go
+++ b/pkg/image/apis/image/types.go
@@ -217,6 +217,8 @@ type ImageStreamSpec struct {
 	// lookupPolicy controls how other resources reference images within this namespace.
 	LookupPolicy ImageLookupPolicy
 	// Optional, if specified this stream is backed by a Docker repository on this server
+	// Deprecated: This field is deprecated as of v3.7 and will be removed in a future release.
+	// Specify the source for the tags to be imported in each tag via the spec.tags.from reference instead.
 	DockerImageRepository string
 	// Tags map arbitrary string values to specific image locators
 	Tags map[string]TagReference
@@ -256,7 +258,7 @@ type TagReference struct {
 	Generation *int64
 	// ImportPolicy is information that controls how images may be imported by the server.
 	ImportPolicy TagImportPolicy
-	// ReferencePolicy defines how other components should consume the image
+	// ReferencePolicy defines how other components should consume the image.
 	ReferencePolicy TagReferencePolicy
 }
 
diff --git a/pkg/image/apis/image/v1/generated.proto b/pkg/image/apis/image/v1/generated.proto
index bca0e2c04eef..34c91b297553 100644
--- a/pkg/image/apis/image/v1/generated.proto
+++ b/pkg/image/apis/image/v1/generated.proto
@@ -265,6 +265,8 @@ message ImageStreamSpec {
   optional ImageLookupPolicy lookupPolicy = 3;
 
   // dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server
+  // Deprecated: This field is deprecated as of v3.7 and will be removed in a future release.
+  // Specify the source for the tags to be imported in each tag via the spec.tags.from reference instead.
   optional string dockerImageRepository = 1;
 
   // tags map arbitrary string values to specific image locators
@@ -458,23 +460,30 @@ message TagReference {
   // Name of the tag
   optional string name = 1;
 
-  // Annotations associated with images using this tag
+  // Optional; if specified, annotations that are applied to images retrieved via ImageStreamTags.
   map<string, string> annotations = 2;
 
-  // From is a reference to an image stream tag or image stream this tag should track
+  // Optional; if specified, a reference to another image that this tag should point to. Valid values
+  // are ImageStreamTag, ImageStreamImage, and DockerImage.
   optional k8s.io.kubernetes.pkg.api.v1.ObjectReference from = 3;
 
-  // Reference states if the tag will be imported. Default value is false, which means the tag will be imported.
+  // Reference states if the tag will be imported. Default value is false, which means the tag will
+  // be imported.
   optional bool reference = 4;
 
-  // Generation is the image stream generation that updated this tag - setting it to 0 is an indication that the generation must be updated.
-  // Legacy clients will send this as nil, which means the client doesn't know or care.
+  // Generation is a counter that tracks mutations to the spec tag (user intent). When a tag reference
+  // is changed the generation is set to match the current stream generation (which is incremented every
+  // time spec is changed). Other processes in the system like the image importer observe that the
+  // generation of spec tag is newer than the generation recorded in the status and use that as a trigger
+  // to import the newest remote tag. To trigger a new import, clients may set this value to zero which
+  // will reset the generation to the latest stream generation. Legacy clients will send this value as
+  // nil which will be merged with the current tag generation.
   optional int64 generation = 5;
 
-  // Import is information that controls how images may be imported by the server.
+  // ImportPolicy is information that controls how images may be imported by the server.
   optional TagImportPolicy importPolicy = 6;
 
-  // ReferencePolicy defines how other components should consume the image
+  // ReferencePolicy defines how other components should consume the image.
   optional TagReferencePolicy referencePolicy = 7;
 }
 
diff --git a/pkg/image/apis/image/v1/swagger_doc.go b/pkg/image/apis/image/v1/swagger_doc.go
index 241909a8202b..4fb443c967f8 100644
--- a/pkg/image/apis/image/v1/swagger_doc.go
+++ b/pkg/image/apis/image/v1/swagger_doc.go
@@ -185,7 +185,7 @@ func (ImageStreamMapping) SwaggerDoc() map[string]string {
 var map_ImageStreamSpec = map[string]string{
 	"":                      "ImageStreamSpec represents options for ImageStreams.",
 	"lookupPolicy":          "lookupPolicy controls how other resources reference images within this namespace.",
-	"dockerImageRepository": "dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server",
+	"dockerImageRepository": "dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server Deprecated: This field is deprecated as of v3.7 and will be removed in a future release. Specify the source for the tags to be imported in each tag via the spec.tags.from reference instead.",
 	"tags":                  "tags map arbitrary string values to specific image locators",
 }
 
@@ -342,12 +342,12 @@ func (TagImportPolicy) SwaggerDoc() map[string]string {
 var map_TagReference = map[string]string{
 	"":                "TagReference specifies optional annotations for images using this tag and an optional reference to an ImageStreamTag, ImageStreamImage, or DockerImage this tag should track.",
 	"name":            "Name of the tag",
-	"annotations":     "Annotations associated with images using this tag",
-	"from":            "From is a reference to an image stream tag or image stream this tag should track",
+	"annotations":     "Optional; if specified, annotations that are applied to images retrieved via ImageStreamTags.",
+	"from":            "Optional; if specified, a reference to another image that this tag should point to. Valid values are ImageStreamTag, ImageStreamImage, and DockerImage.",
 	"reference":       "Reference states if the tag will be imported. Default value is false, which means the tag will be imported.",
-	"generation":      "Generation is the image stream generation that updated this tag - setting it to 0 is an indication that the generation must be updated. Legacy clients will send this as nil, which means the client doesn't know or care.",
-	"importPolicy":    "Import is information that controls how images may be imported by the server.",
-	"referencePolicy": "ReferencePolicy defines how other components should consume the image",
+	"generation":      "Generation is a counter that tracks mutations to the spec tag (user intent). When a tag reference is changed the generation is set to match the current stream generation (which is incremented every time spec is changed). Other processes in the system like the image importer observe that the generation of spec tag is newer than the generation recorded in the status and use that as a trigger to import the newest remote tag. To trigger a new import, clients may set this value to zero which will reset the generation to the latest stream generation. Legacy clients will send this value as nil which will be merged with the current tag generation.",
+	"importPolicy":    "ImportPolicy is information that controls how images may be imported by the server.",
+	"referencePolicy": "ReferencePolicy defines how other components should consume the image.",
 }
 
 func (TagReference) SwaggerDoc() map[string]string {
diff --git a/pkg/image/apis/image/v1/types.go b/pkg/image/apis/image/v1/types.go
index 52c337649f37..f6f0c3ad8f91 100644
--- a/pkg/image/apis/image/v1/types.go
+++ b/pkg/image/apis/image/v1/types.go
@@ -173,6 +173,8 @@ type ImageStreamSpec struct {
 	// lookupPolicy controls how other resources reference images within this namespace.
 	LookupPolicy ImageLookupPolicy `json:"lookupPolicy,omitempty" protobuf:"bytes,3,opt,name=lookupPolicy"`
 	// dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server
+	// Deprecated: This field is deprecated as of v3.7 and will be removed in a future release.
+	// Specify the source for the tags to be imported in each tag via the spec.tags.from reference instead.
 	DockerImageRepository string `json:"dockerImageRepository,omitempty" protobuf:"bytes,1,opt,name=dockerImageRepository"`
 	// tags map arbitrary string values to specific image locators
 	Tags []TagReference `json:"tags,omitempty" protobuf:"bytes,2,rep,name=tags"`
@@ -193,18 +195,25 @@ type ImageLookupPolicy struct {
 type TagReference struct {
 	// Name of the tag
 	Name string `json:"name" protobuf:"bytes,1,opt,name=name"`
-	// Annotations associated with images using this tag
+	// Optional; if specified, annotations that are applied to images retrieved via ImageStreamTags.
 	Annotations map[string]string `json:"annotations" protobuf:"bytes,2,rep,name=annotations"`
-	// From is a reference to an image stream tag or image stream this tag should track
+	// Optional; if specified, a reference to another image that this tag should point to. Valid values
+	// are ImageStreamTag, ImageStreamImage, and DockerImage.
 	From *kapi.ObjectReference `json:"from,omitempty" protobuf:"bytes,3,opt,name=from"`
-	// Reference states if the tag will be imported. Default value is false, which means the tag will be imported.
+	// Reference states if the tag will be imported. Default value is false, which means the tag will
+	// be imported.
 	Reference bool `json:"reference,omitempty" protobuf:"varint,4,opt,name=reference"`
-	// Generation is the image stream generation that updated this tag - setting it to 0 is an indication that the generation must be updated.
-	// Legacy clients will send this as nil, which means the client doesn't know or care.
+	// Generation is a counter that tracks mutations to the spec tag (user intent). When a tag reference
+	// is changed the generation is set to match the current stream generation (which is incremented every
+	// time spec is changed). Other processes in the system like the image importer observe that the
+	// generation of spec tag is newer than the generation recorded in the status and use that as a trigger
+	// to import the newest remote tag. To trigger a new import, clients may set this value to zero which
+	// will reset the generation to the latest stream generation. Legacy clients will send this value as
+	// nil which will be merged with the current tag generation.
 	Generation *int64 `json:"generation" protobuf:"varint,5,opt,name=generation"`
-	// Import is information that controls how images may be imported by the server.
+	// ImportPolicy is information that controls how images may be imported by the server.
 	ImportPolicy TagImportPolicy `json:"importPolicy,omitempty" protobuf:"bytes,6,opt,name=importPolicy"`
-	// ReferencePolicy defines how other components should consume the image
+	// ReferencePolicy defines how other components should consume the image.
 	ReferencePolicy TagReferencePolicy `json:"referencePolicy,omitempty" protobuf:"bytes,7,opt,name=referencePolicy"`
 }
 
diff --git a/pkg/openapi/zz_generated.openapi.go b/pkg/openapi/zz_generated.openapi.go
index ffeed8bd12c6..691148b7c0ce 100644
--- a/pkg/openapi/zz_generated.openapi.go
+++ b/pkg/openapi/zz_generated.openapi.go
@@ -6149,7 +6149,7 @@ func GetOpenAPIDefinitions(ref openapi.ReferenceCallback) map[string]openapi.Ope
 						},
 						"dockerImageRepository": {
 							SchemaProps: spec.SchemaProps{
-								Description: "dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server",
+								Description: "dockerImageRepository is optional, if specified this stream is backed by a Docker repository on this server Deprecated: This field is deprecated as of v3.7 and will be removed in a future release. Specify the source for the tags to be imported in each tag via the spec.tags.from reference instead.",
 								Type:        []string{"string"},
 								Format:      "",
 							},
@@ -6715,7 +6715,7 @@ func GetOpenAPIDefinitions(ref openapi.ReferenceCallback) map[string]openapi.Ope
 						},
 						"annotations": {
 							SchemaProps: spec.SchemaProps{
-								Description: "Annotations associated with images using this tag",
+								Description: "Optional; if specified, annotations that are applied to images retrieved via ImageStreamTags.",
 								Type:        []string{"object"},
 								AdditionalProperties: &spec.SchemaOrBool{
 									Schema: &spec.Schema{
@@ -6729,7 +6729,7 @@ func GetOpenAPIDefinitions(ref openapi.ReferenceCallback) map[string]openapi.Ope
 						},
 						"from": {
 							SchemaProps: spec.SchemaProps{
-								Description: "From is a reference to an image stream tag or image stream this tag should track",
+								Description: "Optional; if specified, a reference to another image that this tag should point to. Valid values are ImageStreamTag, ImageStreamImage, and DockerImage.",
 								Ref:         ref("k8s.io/kubernetes/pkg/api/v1.ObjectReference"),
 							},
 						},
@@ -6742,20 +6742,20 @@ func GetOpenAPIDefinitions(ref openapi.ReferenceCallback) map[string]openapi.Ope
 						},
 						"generation": {
 							SchemaProps: spec.SchemaProps{
-								Description: "Generation is the image stream generation that updated this tag - setting it to 0 is an indication that the generation must be updated. Legacy clients will send this as nil, which means the client doesn't know or care.",
+								Description: "Generation is a counter that tracks mutations to the spec tag (user intent). When a tag reference is changed the generation is set to match the current stream generation (which is incremented every time spec is changed). Other processes in the system like the image importer observe that the generation of spec tag is newer than the generation recorded in the status and use that as a trigger to import the newest remote tag. To trigger a new import, clients may set this value to zero which will reset the generation to the latest stream generation. Legacy clients will send this value as nil which will be merged with the current tag generation.",
 								Type:        []string{"integer"},
 								Format:      "int64",
 							},
 						},
 						"importPolicy": {
 							SchemaProps: spec.SchemaProps{
-								Description: "Import is information that controls how images may be imported by the server.",
+								Description: "ImportPolicy is information that controls how images may be imported by the server.",
 								Ref:         ref("github.com/openshift/origin/pkg/image/apis/image/v1.TagImportPolicy"),
 							},
 						},
 						"referencePolicy": {
 							SchemaProps: spec.SchemaProps{
-								Description: "ReferencePolicy defines how other components should consume the image",
+								Description: "ReferencePolicy defines how other components should consume the image.",
 								Ref:         ref("github.com/openshift/origin/pkg/image/apis/image/v1.TagReferencePolicy"),
 							},
 						},