docs: add artifact metadata descriptions (#3815)

* docs: initial draft of artifact metadata descriptions, a few minor edits

* docs: add review feedback and clarification from eric

docs/modules/ROOT/pages/getting-started/assembly-installing-registry-openshift.adoc

@@ -14,7 +14,7 @@ ifdef::apicurio-registry[]
 * {registry-overview}
 endif::[]
 ifdef::rh-service-registry[]
-* Read the introduction in the link:{LinkServiceRegistryUser}[{NameServiceRegistryUser}]
+* Read the introduction in the link:{LinkServiceRegistryUser}[{NameServiceRegistryUser}].
 endif::[]
 
 ifdef::apicurio-registry[]

docs/modules/ROOT/partials/getting-started/con-registry-demo.adoc

@@ -11,7 +11,7 @@ These applications demonstrate use cases such as the following examples:
 * Apache Avro Kafka SerDes
 * Apache Avro Maven plug-in
 * Apache Camel Quarkus and Kafka
-* Cloud Events 
+* CloudEvents 
 * Confluent Kafka SerDes
 * Custom ID strategy
 * Event-driven architecture with Debezium

docs/modules/ROOT/partials/getting-started/con-registry-serdes-constants.adoc

@@ -5,13 +5,14 @@
 = {registry} serializer/deserializer configuration in client applications
 
 [role="_abstract"]
-You can configure specific client serializer/deserializer services and schema lookup strategies directly in a client application using the example constants shown in this section. Alternatively, you can configure the corresponding {registry} application properties in a file or an instance. 
+You can configure specific client serializer/deserializer (SerDes) services and schema lookup strategies directly 
+in a client application using the example constants shown in this section. Alternatively, you can configure the corresponding {registry} application properties in a file or an instance. 
 
 The following sections show examples of commonly used SerDes constants and configuration options.
 
 
 [discrete]
-== Configuration for SerDe services
+== Configuration for SerDes services
 
 [source,java,subs="+quotes,attributes"]
 ----
@@ -22,7 +23,7 @@ public class SerdeConfig {
    public static final String ENABLE_CONFLUENT_ID_HANDLER = "apicurio.registry.as-confluent"; <3>
 ----
 . The required URL of {registry}.
-. Extends ID handling to support other ID formats and make them compatible with {registry} SerDe services.
+. Extends ID handling to support other ID formats and make them compatible with {registry} SerDes services.
 For example, changing the default ID format from `Long` to `Integer` supports the Confluent ID format.
 . Simplifies the handling of Confluent IDs. If set to `true`, an `Integer` is used for the global ID lookup.
 The setting should not be used with the `ID_HANDLER` option.
@@ -34,7 +35,7 @@ The setting should not be used with the `ID_HANDLER` option.
 
 
 [discrete]
-== Configuration for SerDe lookup strategies
+== Configuration for SerDes lookup strategies
 
 [source,java,subs="+quotes,attributes"]
 ----
@@ -44,7 +45,7 @@ public class SerdeConfig {
    public static final String SCHEMA_RESOLVER = "apicurio.registry.schema-resolver"; <2>
 ...      
 ----
-<1> Java class that implements the artifact resolver strategy and maps between the Kafka SerDe and artifact ID.  Defaults to the topic ID strategy. This is only used by the serializer class.
+<1> Java class that implements the artifact resolver strategy and maps between the Kafka SerDes and artifact ID.  Defaults to the topic ID strategy. This is only used by the serializer class.
 <2> Java class that implements the schema resolver. Defaults to `DefaultSchemaResolver`. This is used by the serializer and deserializer classes.
 
 [role="_additional-resources"]

docs/modules/ROOT/partials/getting-started/proc-configuring-registry-security.adoc

@@ -152,13 +152,13 @@ TIP: For an example of setting environment variables on OpenShift, see xref:conf
 
 [role="_additional-resources"]
 .Additional resources
-* For details on configuring non-default user role names, see xref:registry-security-settings_{context}[]
-* For an open source example application and Keycloak realm, see https://github.com/Apicurio/apicurio-registry/tree/2.0.x/distro/docker-compose[Docker Compose-based example of using Keycloak with Apicurio Registry]
+* For details on configuring non-default user role names, see xref:registry-security-settings_{context}[].
+* For an open source example application and Keycloak realm, see https://github.com/Apicurio/apicurio-registry/tree/{registry-version}.x/distro/docker-compose[Docker Compose example of Apicurio Registry with Keycloak].
 * For details on how to use {keycloak} in a production environment, see
 ifdef::apicurio-registry[]
-the link:https://www.keycloak.org/documentation[Keycloak documentation]
+the link:https://www.keycloak.org/documentation[Keycloak documentation].
 endif::[]
 ifdef::rh-service-registry[]
-see link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/{keycloak-version}/[{keycloak} documentation]
+the link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/{keycloak-version}/[{keycloak} documentation].
 endif::[]
-* For details on custom security configuration, the see https://quarkus.io/guides/security-openid-connect-web-authentication[Quarkus Open ID Connect documentation] 
+

docs/modules/ROOT/partials/getting-started/proc-setting-up-kafka-streams-storage.adoc

@@ -109,10 +109,9 @@ WARNING: You must configure the Kafka topic used by {registry} (named `kafkasql-
 .Additional resources
 
 ifdef::apicurio-registry[]
-For more details on installing Strimzi and on creating Kafka clusters and topics, see https://strimzi.io/docs/overview/latest/
+* For more details on installing Strimzi and on creating Kafka clusters and topics, see https://strimzi.io/docs/overview/latest/
 endif::[]
 
 ifdef::rh-service-registry[]
-//* For more details, including how to configure Transport Layer Security (TLS) and Salted Challenge Response Authentication Mechanism (SCRAM), see the link:https://github.com/redhat-integration/apicurio-registry-install-examples[example custom resource definitions] provided for registry installation.
-* For more details on creating Kafka clusters and topics using {kafka-streams}, see link:https://access.redhat.com/documentation/en-us/red_hat_amq_streams/{amq-version}/html/deploying_and_upgrading_amq_streams_on_openshift/index[Deploying and Upgrading AMQ Streams on OpenShift].
+* For more details on creating Kafka clusters and topics using {kafka-streams}, see link:{LinkDeployStreamsOpenShift}[{NameDeployStreamsOpenShift}].
 endif::[]

docs/modules/ROOT/partials/getting-started/ref-registry-artifact-metadata.adoc

@@ -4,59 +4,85 @@
 = {registry} artifact metadata
 
 [role="_abstract"]
-When an artifact is added to {registry}, a set of metadata properties is stored along with the artifact content. This metadata consists of a set of generated read-only properties, along with some properties that you can set.
+When an artifact is added to {registry}, a set of metadata properties is created and stored along with the artifact content. This metadata consists of system-generated or user-generated properties that are read-only, and editable properties that you can update after the artifact is created.
 
-.{registry} read-only metadata
-[%header,cols=2*]
+.{registry} system-generated metadata
+[.table-expandable,width="100%",cols="1,1,2",options="header"]
 |===
 |Property
 |Type
+|Description
 |`contentId`
-| integer
+|integer
+|Unique identifier of artifact content in {registry}. The same content ID can be shared by multiple artifact versions when artifact versions have identical content. For example, a content ID of `4` can be used by multiple artifact versions with the same content. 
 |`createdBy`
-| string
+|string
+|The name of the user who created the artifact.
 |`createdOn`
-| date
+|date
+|The date and time when the artifact was created, for example, `2023-10-11T14:15:28Z`.
 |`globalId`
-| integer
-|`groupId`
-| string
-|`id`
-| string
+|integer
+|Globally unique identifier of an artifact version in {registry}. For example, a global ID of `1` is assigned to the first artifact version created in {registry}.
 |`modifiedBy`
-| string
+|string
+|The name of the user who modified the artifact.
 |`modifiedOn`
-| date
-|`references`
-| array of ArtifactReference
+|date
+|The date and time at which the artifact was modified, for example, `2023-10-11T14:15:28Z`.
 |`type`
-| ArtifactType
+|ArtifactType
+|The supported artifact type, for example, `AVRO`, `OPENAPI`, or `PROTOBUF`. 
+|===
+
+
+.{registry} user-provided or system-generated metadata
+[.table-expandable,width="100%",cols="1,1,2",options="header"]
+|===
+|Property
+|Type
+|Description
+|`groupId`
+|string
+|Unique identifier of an artifact group in {registry}, for example, `development` or `production`. When creating an artifact by using the {registry} web console, if you do not provide a group ID, this is set to `default`. You must provide a group ID when using the Apicurio Registry REST API, Java client, or Maven plug-in. 
+|`id`
+|string
+|Unique identifier of an artifact in {registry}. You can provide an artifact ID or use the UUID generated by {registry}, for example, `8d168cad-1865-4e6c-bb7e-04e8be005bea`. Different versions of an artifact use the same artifact ID, but have different global IDs. 
+|`references`
+|array of ArtifactReference
+|Optional set of artifact references contained in the artifact, which you can provide when creating the artifact. The following simple example shows a single artifact reference: `[{"groupId":"my-group","artifactId":"ItemId","version":"1","name":"com.example.common.ItemId"}]`.
 |`version`
-| integer
+|integer
+|The latest version of the artifact. You can use the generated version, for example, `3`, or provide a version by using the {registry} REST API or Maven plug-in, for example, `2.1.6`. 
 |===
 
 
 .{registry} editable metadata
-[%header,cols=2*]
+[.table-expandable,width="100%",cols="1,1,2",options="header"]
 |===
 |Property
 |Type
+|Description
 |`description`
-| string
+|string
+|Optional meaningful description of the artifact, for example, `This is a simple OpenAPI for testing`. You can provide a description, or it can be automatically discovered from the `info` section of OpenAPI and AsyncAPI artifacts, if already provided.
 |`labels`
-| array of string
+|array of string
+|Optional comma-separated list of labels used to filter and search for the artifact, for example, `test,protobuf`. Provided by the user. 
 |`name`
-| string
+|string
+|Optional human-readable name of the artifact, for example, `My first Avro schema`. You can provide a description, or it can be  automatically discovered from the `info` section of OpenAPI and AsyncAPI artifacts, if the `title` field has a value.
 |`properties`
 | map
+|Optional list of user-defined name-value pairs associated with the artifact. The name and value must be strings, for example, `my-key` and `my-value`.
 |`state`
-| ArtifactState
+|ArtifactState
+|The latest state of the artifact: `ENABLED`, `DISABLED`, or `DEPRECATED`. Defaults to `ENABLED`. 
 |===
 
 .Updating artifact metadata
-* You can use the {registry} REST API to update the set of editable properties using the metadata endpoints. 
-
-* You can edit the `state` property only by using the state transition API. For example, you can mark an artifact as `deprecated` or `disabled`.  
+* You can use the {registry} REST API or web console to update the set of editable metadata properties.
+* You can update the `state` property only by using the {registry} REST API.
 
 [role="_additional-resources"]
 .Additional resources

docs/modules/ROOT/partials/getting-started/ref-registry-security-configuration.adoc

@@ -5,7 +5,7 @@
 = {registry} authentication and authorization configuration options
 
 [role="_abstract"]
-{registry} provides authentication options for OpenID Connect with {keycloak} or HTTP basic authentication.  
+{registry} provides authentication options for OpenID Connect with {keycloak} and HTTP basic authentication.  
 
 {registry} provides authorization options for role-based and content-based approaches: 
 

docs/modules/ROOT/partials/shared/attributes-links.adoc

@@ -148,13 +148,13 @@
 
 
 // Service Registry titles
-:ServiceRegistryURLVersion: 2023.q2
+:ServiceRegistryURLVersion: 2023.q3
 :RegistryProductURL: service_registry 
 
 ifdef::RHAF[]
 :productpkg: red_hat_build_of_apicurio_registry 
 :RegistryProductURL: apicurio_registry
-:ServiceRegistryURLVersion: 2.3
+:ServiceRegistryURLVersion: 2.4
 endif::[]
 
 :LinkServiceRegistryInstall: https://access.redhat.com/documentation/en-us/{productpkg}/{ServiceRegistryURLVersion}/html-single/installing_and_deploying_{RegistryProductURL}_on_openshift/index
@@ -182,8 +182,8 @@ endif::[]
 :LinkStreamsOpenShift: https://access.redhat.com/documentation/en-us/red_hat_amq_streams/{AMQStreamsURLVersion}/html-single/using_amq_streams_on_openshift/index
 :NameStreamsOpenShift: Using {StreamsName} on OpenShift
 
-:LinkDeployStreamsOpenShift: https://access.redhat.com/documentation/en-us/red_hat_amq_streams/{AMQStreamsURLVersion}/html-single/deploying_and_upgrading_amq_streams_on_openshift/index
-:NameDeployStreamsOpenShift: Deploying and Upgrading {StreamsName} on OpenShift
+:LinkDeployStreamsOpenShift: https://access.redhat.com/documentation/en-us/red_hat_amq_streams/{AMQStreamsURLVersion}/html-single/deploying_and_managing_amq_streams_on_openshift/index
+:NameDeployStreamsOpenShift: Deploying and Managing {StreamsName} on OpenShift
 
 :LinkStreamsRhel: https://access.redhat.com/documentation/en-us/red_hat_amq_streams/{AMQStreamsURLVersion}/html-single/using_amq_streams_on_rhel/index
 :NameStreamsRhel: Using {StreamsName} on RHEL