From baf90b6b38294e247d8e50044061e5a40a395d49 Mon Sep 17 00:00:00 2001 From: Stephen McCarthy <29098561+smccarthy-ie@users.noreply.github.com> Date: Wed, 11 Nov 2020 20:38:41 +0000 Subject: [PATCH] clean up registry user docs and restructure (#1004) --- docs/local-test-playbook.yml | 6 +- .../assets/attachments/registry-rest-api.htm | 2 +- docs/modules/ROOT/nav.adoc | 7 +- .../assembly-configuring-the-registry.adoc | 2 +- ... assembly-installing-registry-docker.adoc} | 0 ...ssembly-installing-registry-openshift.adoc | 25 ++++ ...nstalling-registry-storage-openshift.adoc} | 25 +--- .../assembly-intro-to-registry-rules.adoc | 1 - .../assembly-intro-to-the-registry.adoc | 2 - ...embly-managing-registry-artifacts-api.adoc | 9 +- ...bly-managing-registry-artifacts-maven.adoc | 7 +- ...sembly-managing-registry-artifacts-ui.adoc | 2 + .../assembly-registry-reference.adoc | 10 +- .../assembly-using-kafka-client-serdes.adoc | 4 +- .../assembly-using-the-registry-client.adoc | 4 +- docs/modules/ROOT/pages/index.adoc | 21 ++- .../con-kafka-connect-converters.adoc | 2 +- .../con-registry-artifact-metadata.adoc | 67 --------- .../con-registry-artifacts.adoc | 4 +- .../getting-started/con-registry-client.adoc | 22 +-- .../getting-started/con-registry-demo.adoc | 17 ++- .../getting-started/con-registry-distros.adoc | 4 +- .../con-registry-overview.adoc | 2 +- .../con-registry-rest-api.adoc | 2 +- .../getting-started/con-registry-rules.adoc | 41 +++--- .../getting-started/con-registry-serde.adoc | 9 +- .../con-registry-serdes-concepts.adoc | 20 +-- .../con-registry-serdes-strategy.adoc | 34 ++--- .../con-registry-serdes-types.adoc | 137 ++++++++---------- .../getting-started/con-registry-storage.adoc | 7 +- .../con-registry-web-console.adoc | 9 +- .../proc-configuring-registry-ui.adoc | 41 +++--- ...managing-artifacts-using-maven-plugin.adoc | 49 +++---- .../proc-writing-registry-client.adoc | 30 ++-- .../ref-registry-artifact-metadata.adoc | 58 ++++++++ .../getting-started/ref-registry-client.adoc | 34 +++-- .../ref-registry-rule-maturity-matrix.adoc | 13 +- 37 files changed, 360 insertions(+), 369 deletions(-) rename docs/modules/ROOT/pages/getting-started/{assembly-installing-the-registry-docker.adoc => assembly-installing-registry-docker.adoc} (100%) create mode 100644 docs/modules/ROOT/pages/getting-started/assembly-installing-registry-openshift.adoc rename docs/modules/ROOT/pages/getting-started/{assembly-installing-the-registry-openshift.adoc => assembly-installing-registry-storage-openshift.adoc} (64%) delete mode 100644 docs/modules/ROOT/partials/getting-started/con-registry-artifact-metadata.adoc create mode 100644 docs/modules/ROOT/partials/getting-started/ref-registry-artifact-metadata.adoc diff --git a/docs/local-test-playbook.yml b/docs/local-test-playbook.yml index 78430ef69b..00a872b36d 100644 --- a/docs/local-test-playbook.yml +++ b/docs/local-test-playbook.yml @@ -27,9 +27,9 @@ asciidoc: mod-loc: partial$ registry-overview: link:assembly-intro-to-the-registry.html[Introduction to Apicurio Registry] registry-rules: link:assembly-intro-to-registry-rules.html[Introduction to Apicurio Registry rules] - registry-artifact-types: link:assembly-registry-reference.html[Apicurio Registry reference] - registry-rule-types: link:assembly-registry-reference.html[Apicurio Registry reference] - registry-rule-maturity-matrix: link:assembly-registry-reference.html[Apicurio Registry reference] + registry-reference: link:assembly-registry-reference.html[Apicurio Registry artifact reference] managing-registry-artifacts-ui: link:assembly-managing-registry-artifacts-ui.html[Managing Apicurio Registry content using the web console] + managing-registry-artifacts-api: link:assembly-managing-registry-artifacts-api.html[Managing Apicurio Registry content using the REST API] installing-the-registry-docker: link:assembly-installing-the-registry-docker.html[Installing Apicurio Registry using Docker] installing-the-registry-openshift: link:assembly-installing-the-registry-openshift.html[Installing Apicurio Registry on OpenShift] + kafka-client-serdes: link:assembly-using-kafka-client-serdes.html[Validating schemas using Kafka client serializers/deserializers] diff --git a/docs/modules/ROOT/assets/attachments/registry-rest-api.htm b/docs/modules/ROOT/assets/attachments/registry-rest-api.htm index b2a41acc77..08414ab3b7 100644 --- a/docs/modules/ROOT/assets/attachments/registry-rest-api.htm +++ b/docs/modules/ROOT/assets/attachments/registry-rest-api.htm @@ -16,7 +16,7 @@ - + diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 575808a7eb..e4fe36299a 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,13 +1,14 @@ * xref:getting-started/assembly-intro-to-the-registry.adoc[] * xref:getting-started/assembly-intro-to-registry-rules.adoc[] ifdef:getting-started/:apicurio-registry[] -* xref:getting-started/assembly-installing-the-registry-docker.adoc[] +* xref:getting-started/assembly-installing-registry-docker.adoc[] endif:getting-started/:[] -* xref:getting-started/assembly-installing-the-registry-openshift.adoc[] +* xref:getting-started/assembly-installing-registry-openshift.adoc[] +* xref:getting-started/assembly-installing-registry-storage-openshift.adoc[] * xref:getting-started/assembly-configuring-the-registry.adoc[] * xref:getting-started/assembly-managing-registry-artifacts-ui.adoc[] * xref:getting-started/assembly-managing-registry-artifacts-api.adoc[] * xref:getting-started/assembly-managing-registry-artifacts-maven.adoc[] -* xref:getting-started/assembly-using-kafka-client-serdes.adoc[] * xref:getting-started/assembly-using-the-registry-client.adoc[] +* xref:getting-started/assembly-using-kafka-client-serdes.adoc[] * xref:getting-started/assembly-registry-reference.adoc[] diff --git a/docs/modules/ROOT/pages/getting-started/assembly-configuring-the-registry.adoc b/docs/modules/ROOT/pages/getting-started/assembly-configuring-the-registry.adoc index 73a504f8ee..524b8cd34b 100644 --- a/docs/modules/ROOT/pages/getting-started/assembly-configuring-the-registry.adoc +++ b/docs/modules/ROOT/pages/getting-started/assembly-configuring-the-registry.adoc @@ -2,7 +2,7 @@ include::{mod-loc}shared/all-attributes.adoc[] [id="configuring-the-registry"] -= Configuring {registry} on OpenShift += Managing {registry} deployment on OpenShift This chapter explains how to configure optional settings for {registry} health checks on OpenShift: diff --git a/docs/modules/ROOT/pages/getting-started/assembly-installing-the-registry-docker.adoc b/docs/modules/ROOT/pages/getting-started/assembly-installing-registry-docker.adoc similarity index 100% rename from docs/modules/ROOT/pages/getting-started/assembly-installing-the-registry-docker.adoc rename to docs/modules/ROOT/pages/getting-started/assembly-installing-registry-docker.adoc diff --git a/docs/modules/ROOT/pages/getting-started/assembly-installing-registry-openshift.adoc b/docs/modules/ROOT/pages/getting-started/assembly-installing-registry-openshift.adoc new file mode 100644 index 0000000000..a6b901af1f --- /dev/null +++ b/docs/modules/ROOT/pages/getting-started/assembly-installing-registry-openshift.adoc @@ -0,0 +1,25 @@ +// Metadata created by nebel + +include::{mod-loc}shared/all-attributes.adoc[] + +[id="installing-registry-ocp"] += Installing {registry} on OpenShift + +This chapter explains how to install {registry}: + +* xref:installing-registry-operatorhub[] +//* xref:installing-registry-kafka-streams-template-storage[] + +.Prerequisites +* {registry-overview} + +NOTE: You can install more than one instance of {registry} depending on your environment. The number of instances depends on the number and type of artifacts stored in {registry}, and on your chosen storage option, for example, Kafka Streams, database, Infinispan cluster configuration. + +ifdef::apicurio-registry[] +.Additional resources +* For details on building from source, see https://github.com/Apicurio/apicurio-registry. +endif::[] + +//INCLUDES +//include::{mod-loc}getting-started/proc_installing-registry-kafka-streams-template-storage.adoc[leveloffset=+1] +include::{mod-loc}getting-started/proc-installing-registry-operatorhub.adoc[leveloffset=+1] diff --git a/docs/modules/ROOT/pages/getting-started/assembly-installing-the-registry-openshift.adoc b/docs/modules/ROOT/pages/getting-started/assembly-installing-registry-storage-openshift.adoc similarity index 64% rename from docs/modules/ROOT/pages/getting-started/assembly-installing-the-registry-openshift.adoc rename to docs/modules/ROOT/pages/getting-started/assembly-installing-registry-storage-openshift.adoc index 318961b163..e774fca8f1 100644 --- a/docs/modules/ROOT/pages/getting-started/assembly-installing-the-registry-openshift.adoc +++ b/docs/modules/ROOT/pages/getting-started/assembly-installing-registry-storage-openshift.adoc @@ -1,19 +1,10 @@ // Metadata created by nebel - include::{mod-loc}shared/all-attributes.adoc[] -[id="installing-the-registry"] -= Installing {registry} on OpenShift - -This chapter explains how to first install {registry} and then how to set up your chosen registry storage option: {kafka-streams}, embedded Infinispan, or PostgreSQL database. - -.Prerequisites -* {registry-overview} +[id="installing-registry-storage"] += Installing {registry} storage on OpenShift -.{registry} installation -* xref:installing-registry-operatorhub[] -//* xref:installing-registry-kafka-streams-template-storage[] -* xref:configuring-registry-ui[] +This chapter explains how to install and configure your chosen registry storage option: {kafka-streams}, embedded Infinispan, or PostgreSQL database. .{kafka-streams} storage * xref:installing-kafka-streams-operatorhub[] @@ -44,17 +35,11 @@ These features provide early access to upcoming product features, enabling custo ==== endif::[] -NOTE: You can install more than one instance of {registry} depending on your environment. The number of instances depends on your storage option, for example, your Kafka, Infinispan, or database cluster configuration, and on the number and type of artifacts stored in {registry}. - -ifdef::apicurio-registry[] -.Additional resources -* For details on building from source, see https://github.com/Apicurio/apicurio-registry. -endif::[] +.Prerequisites +* {installing-the-registry-openshift} //INCLUDES //include::{mod-loc}getting-started/proc_installing-registry-kafka-streams-template-storage.adoc[leveloffset=+1] -include::{mod-loc}getting-started/proc-installing-registry-operatorhub.adoc[leveloffset=+1] -include::{mod-loc}getting-started/proc-configuring-registry-ui.adoc[leveloffset=+1] include::{mod-loc}getting-started/proc-installing-kafka-streams-operatorhub.adoc[leveloffset=+1] include::{mod-loc}getting-started/proc-setting-up-kafka-streams-storage.adoc[leveloffset=+1] include::{mod-loc}getting-started/proc-setting-up-infinispan-storage.adoc[leveloffset=+1] diff --git a/docs/modules/ROOT/pages/getting-started/assembly-intro-to-registry-rules.adoc b/docs/modules/ROOT/pages/getting-started/assembly-intro-to-registry-rules.adoc index 9f3ca239d1..09f505ad5f 100644 --- a/docs/modules/ROOT/pages/getting-started/assembly-intro-to-registry-rules.adoc +++ b/docs/modules/ROOT/pages/getting-started/assembly-intro-to-registry-rules.adoc @@ -12,6 +12,5 @@ This chapter introduces the optional rules used to govern registry content and p * xref:registry-rules-apply[] * xref:registry-rules-work[] - //INCLUDES include::{mod-loc}getting-started/con-registry-rules.adoc[leveloffset=+1] diff --git a/docs/modules/ROOT/pages/getting-started/assembly-intro-to-the-registry.adoc b/docs/modules/ROOT/pages/getting-started/assembly-intro-to-the-registry.adoc index bc73274984..2b0a65a0e7 100644 --- a/docs/modules/ROOT/pages/getting-started/assembly-intro-to-the-registry.adoc +++ b/docs/modules/ROOT/pages/getting-started/assembly-intro-to-the-registry.adoc @@ -11,7 +11,6 @@ This chapter introduces {registry} concepts and features and provides details on * xref:registry-overview[] * xref:registry-artifacts[] * xref:registry-web-console[] -* xref:registry-rest-api[] * xref:registry-storage[] * xref:client-serde[] * xref:kafka-connect[] @@ -22,7 +21,6 @@ This chapter introduces {registry} concepts and features and provides details on include::{mod-loc}getting-started/con-registry-overview.adoc[leveloffset=+1] include::{mod-loc}getting-started/con-registry-artifacts.adoc[leveloffset=+1] include::{mod-loc}getting-started/con-registry-web-console.adoc[leveloffset=+1] -include::{mod-loc}getting-started/con-registry-rest-api.adoc[leveloffset=+1] include::{mod-loc}getting-started/con-registry-storage.adoc[leveloffset=+1] include::{mod-loc}getting-started/con-registry-serde.adoc[leveloffset=+1] include::{mod-loc}getting-started/con-kafka-connect-converters.adoc[leveloffset=+1] diff --git a/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-api.adoc b/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-api.adoc index bc26b6b59d..cba301c3bb 100644 --- a/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-api.adoc +++ b/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-api.adoc @@ -6,11 +6,14 @@ include::{mod-loc}shared/all-attributes.adoc[] = Managing {registry} content using the REST API //If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring. -This chapter explains how to manage artifacts stored in the registry using the Registry REST API. This includes using Registry REST API commands, a Maven plug-in, or a Java client application: +This chapter describes the Registry REST API and shows how to use it manage artifacts stored in the registry: +* xref:registry-rest-api[] * xref:managing-artifacts-using-rest-api[] -* xref:managing-artifacts-using-client-code[] + +.Additional resources +* link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation] //INCLUDES +include::{mod-loc}getting-started/con-registry-rest-api.adoc[leveloffset=+1] include::{mod-loc}getting-started/proc-managing-artifacts-using-rest-api.adoc[leveloffset=+1] -include::{mod-loc}getting-started/proc-managing-artifacts-using-client-code.adoc[leveloffset=+1] diff --git a/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-maven.adoc b/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-maven.adoc index 7a7425f40c..b63a8461ec 100644 --- a/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-maven.adoc +++ b/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-maven.adoc @@ -5,9 +5,14 @@ include::{mod-loc}shared/all-attributes.adoc[] [id="managing-registry-artifacts-maven"] = Managing {registry} content using the Maven plug-in -This chapter explains how to manage artifacts stored in the registry using the {registry} Maven plug-in. +This chapter explains how to manage artifacts stored in the registry using the {registry} Maven plug-in: * xref:managing-artifacts-using-maven-plugin[] +.Prerequisites +* See {registry-overview} +* {registry} must be installed and running in your environment +* Maven must be installed and configured in your environment + //INCLUDES include::{mod-loc}getting-started/proc-managing-artifacts-using-maven-plugin.adoc[leveloffset=+1] diff --git a/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-ui.adoc b/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-ui.adoc index 31363e19a4..33b6ca111a 100644 --- a/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-ui.adoc +++ b/docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-ui.adoc @@ -8,11 +8,13 @@ include::{mod-loc}shared/all-attributes.adoc[] This chapter explains how to manage artifacts stored in the registry using the {registry} web console. This includes uploading and browsing registry content, and configuring optional rules: +* xref:configuring-registry-ui[] * xref:adding-artifacts-using-console[] * xref:browsing-artifacts-using-console[] * xref:configuring-rules-using-console[] //INCLUDES +include::{mod-loc}getting-started/proc-configuring-registry-ui.adoc[leveloffset=+1] include::{mod-loc}getting-started/proc-adding-artifacts-using-console.adoc[leveloffset=+1] include::{mod-loc}getting-started/proc-browsing-artifacts-using-console.adoc[leveloffset=+1] include::{mod-loc}getting-started/proc-configuring-rules-using-console.adoc[leveloffset=+1] diff --git a/docs/modules/ROOT/pages/getting-started/assembly-registry-reference.adoc b/docs/modules/ROOT/pages/getting-started/assembly-registry-reference.adoc index 4be9374d30..8319eda9f2 100644 --- a/docs/modules/ROOT/pages/getting-started/assembly-registry-reference.adoc +++ b/docs/modules/ROOT/pages/getting-started/assembly-registry-reference.adoc @@ -3,20 +3,24 @@ include::{mod-loc}shared/all-attributes.adoc[] [id="artifact-and-rule-types"] -= {registry} reference += {registry} artifact reference //If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring. -This chapter lists the supported artifact types, states and content rule types that are stored in {registry}. +This chapter provides details on the supported artifact types, states, metadata, and content rules that are stored in {registry}. + * xref:registry-artifact-types[] * xref:registry-artifact-states[] +* xref:registry-artifact-metadata[] * xref:registry-rule-types[] * xref:registry-rule-maturity-matrix[] + .Additional resources -* For more detailed information on artifact types, states, and rule types, see the link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation] +* For more detailed information, see the link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation] //INCLUDES include::{mod-loc}getting-started/ref-registry-artifact-types.adoc[leveloffset=+1] include::{mod-loc}getting-started/ref-registry-artifact-states.adoc[leveloffset=+1] +include::{mod-loc}getting-started/ref-registry-artifact-metadata.adoc[leveloffset=+1] include::{mod-loc}getting-started/ref-registry-rule-types.adoc[leveloffset=+1] include::{mod-loc}getting-started/ref-registry-rule-maturity-matrix.adoc[leveloffset=+1] diff --git a/docs/modules/ROOT/pages/getting-started/assembly-using-kafka-client-serdes.adoc b/docs/modules/ROOT/pages/getting-started/assembly-using-kafka-client-serdes.adoc index f4ee40170f..361721ae07 100644 --- a/docs/modules/ROOT/pages/getting-started/assembly-using-kafka-client-serdes.adoc +++ b/docs/modules/ROOT/pages/getting-started/assembly-using-kafka-client-serdes.adoc @@ -3,12 +3,12 @@ include::{mod-loc}shared/all-attributes.adoc[] [id="using-kafka-client-serdes"] -= Using the Kafka client serializers/deserializers += Validating schemas using Kafka client serializers/deserializers //If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring. {registry} provides Kafka client serializers/deserializers for producer and consumer applications. Kafka producer applications use serializers to encode messages that conform to a specific event schema. Kafka consumer applications use deserializers to validate that the messages have been serialized using the correct schema, based on a specific schema ID. This ensures consistent schema use and helps to prevent data errors at runtime. -This chapter provides instructions on how to use the Kafka client serializer and deserializer for Apache Avro in your Kafka producer and consumer client applications: +This chapter provides instructions on how to use the Kafka client serializers and deserializers for Apache Avro, JSON Schema, and Google Protobuf in your Kafka producer and consumer client applications: * xref:registry-serdes-concepts-serde-{context}[] * xref:registry-serdes-types-serde-{context}[] diff --git a/docs/modules/ROOT/pages/getting-started/assembly-using-the-registry-client.adoc b/docs/modules/ROOT/pages/getting-started/assembly-using-the-registry-client.adoc index eff4cc9c82..69af293c4d 100644 --- a/docs/modules/ROOT/pages/getting-started/assembly-using-the-registry-client.adoc +++ b/docs/modules/ROOT/pages/getting-started/assembly-using-the-registry-client.adoc @@ -2,13 +2,13 @@ include::{mod-loc}shared/all-attributes.adoc[] [id="using-the-registry-client"] -= Using the {registry} Java client += Managing {registry} content using the Java client This chapter explains how to use the {registry} Java client: * xref:registry-client-intro[] * xref:writing-registry-client[] -* xref:registry-client-types[] +* xref:registry-client-config[] //INCLUDES include::{mod-loc}getting-started/con-registry-client.adoc[leveloffset=+1] diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index a84e93bf7a..95c6d63e7d 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,6 +1,21 @@ include::partial$shared/attributes.adoc[] -= Welcome += {registry} documentation -Welcome to the {registry} version {registry-version} documentation. -Navigate using the left hand menu. \ No newline at end of file +Welcome to the {registry} version {registry-version} documentation. Navigate using the left menu. + +{registry} stores and retrieves API designs and event schemas, and gives you control of their evolution. + + +== About this documentation +This introduces {registry}, explains how to install with your chosen storage option, and how to manage event schemas and API designs using the {registry} web console, REST API, Maven plug-in, or Java client. + +This also explains how to enforce schemas using Kafka client serializers and deserializers in your consumer and producer applications. It also describes {registry} content types and rule types, and OpenShift environment variables for health checks. + +== Getting help with {registry} + +See the link:https://github.com/Apicurio/apicurio-registry[{registry}] and https://github.com/Apicurio/apicurio-registry-operator[{registry} Operator] projects on GitHub. +Any contributions, suggestions, and issue reports are welcome. + +ifdef::apicurio-registry[] +link:https://github.com/Apicurio/apicurio-registry/issues/new[Create an issue] on GitHub if you find any problems. diff --git a/docs/modules/ROOT/partials/getting-started/con-kafka-connect-converters.adoc b/docs/modules/ROOT/partials/getting-started/con-kafka-connect-converters.adoc index 9f8ec22bb6..3b64dcc06f 100644 --- a/docs/modules/ROOT/partials/getting-started/con-kafka-connect-converters.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-kafka-connect-converters.adoc @@ -2,7 +2,7 @@ [id="kafka-connect"] -= Kafka Connect converters += Stream data to external sytems with Kafka Connect converters You can use {registry} with Apache Kafka Connect to stream data between Kafka and external systems. Using Kafka Connect, you can define connectors for different systems to move large volumes of data into and out of Kafka-based systems. .{registry} and Kafka Connect architecture diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-artifact-metadata.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-artifact-metadata.adoc deleted file mode 100644 index cd4a9596d3..0000000000 --- a/docs/modules/ROOT/partials/getting-started/con-registry-artifact-metadata.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Metadata created by nebel - -[id="registry-artifact-metadata"] -= {registry} artifact metadata - -Whenever an item is added to {registry}, a set of metadata properties is stored along with the item content. This -metadata consists of a set of generated, read-only properties along with some properties that can be set by the user. - -.{registry} metadata properties -[%header,cols=3*] -|=== -|Property -|Type -|Editable -|`id` -a| string -a| false -|`type` -a| ArtifactType -a| false -|`state` -a| ArtifactState -a| true -|`version` -a| integer -a| false -|`createdBy` -a| string -a| false -|`createdOn` -a| date -a| false -|`modifiedBy` -a| string -a| false -|`modifiedOn` -a| date -a| false -|`name` -a| string -a| true -|`description` -a| string -a| true -|`labels` -a| array of string -a| true -|`properties` -a| map -a| true -|=== - -== Updating artifact metadata - -The set of editable properties can be updated via the REST API, using the metadata endpoint(s). Please see the -`/artifacts/{artifactId}/meta` section of the REST API reference for details. - -== Updating artifact state - -It is important to note that the `state` property is editable only by using the state transition API, which allows -users to, for example, mark an artifact as `deprecated` or `disabled`. Please see the `/artifacts/{artifactId}/meta` -section of the REST API reference for details. - -== Custom key-value properties - -{registry} allows users to set arbitrary key-value properties on any artifact. The `properties` property above is -the mechanism that allows this. As a result, any custom metadata properties can be stored with an artifact. diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-artifacts.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-artifacts.adoc index b08d007fb0..b03d211588 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-artifacts.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-artifacts.adoc @@ -1,7 +1,7 @@ // Metadata created by nebel [id="registry-artifacts"] -= {registry} artifacts += Store schema and API artifacts in {registry} The items stored in {registry}, such as event schemas and API specifications, are known as registry _artifacts_. The following shows an example of an Apache Avro schema artifact in JSON format for a simple share price application: @@ -26,4 +26,4 @@ The items stored in {registry}, such as event schemas and API specifications, ar When a schema or API contract is added as an artifact in the registry, client applications can then use that schema or API contract to validate that client messages conform to the correct data structure at runtime. -{registry} supports a wide range of message payload formats for standard event schemas and API specifications. For example, supported formats include Apache Avro, Google protocol buffers, GraphQL, AsyncAPI, OpenAPI, and others. For more details, see {registry-artifact-types}. +{registry} supports a wide range of message payload formats for standard event schemas and API specifications. For example, supported formats include Apache Avro, Google protocol buffers, GraphQL, AsyncAPI, OpenAPI, and others. For more details, see {registry-reference}. diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-client.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-client.adoc index 538e7275e3..c17d3adad0 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-client.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-client.adoc @@ -1,24 +1,10 @@ // Metadata created by nebel [id="registry-client-intro"] -= {registry} Java client overview += {registry} Java client -You can manage artifacts stored in {registry} using a Java client application. You can create, read, update, or delete artifacts stored -in the registry using the {registry} Java client classes. +You can manage artifacts stored in {registry} using a Java client application. You can create, read, update, or delete artifacts stored in the registry using the {registry} Java client classes. -You can access the {registry} Java client by adding the proper dependency to your project, see xref:writing-registry-client[]. +You can access the {registry} Java client by adding the correct dependency to your project, see xref:writing-registry-client[]. -The {registry} client is autocloseable and is implemented using Retrofit and OkHttp as base libraries. This gives the user the ability to customize its -usage by, for example, adding custom headers or enabling TLS auth support. - -== Enabling TLS support in the client - -You can configure TLS authentication using the following properties: - -* apicurio.registry.request.ssl.truststore.location -* apicurio.registry.request.ssl.truststore.password -* apicurio.registry.request.ssl.truststore.type -* apicurio.registry.request.ssl.keystore.location -* apicurio.registry.request.ssl.keystore.password -* apicurio.registry.request.ssl.keystore.type -* apicurio.registry.request.ssl.key.password +The {registry} client is auto-closeable and is implemented using Retrofit and OkHttp as base libraries. This gives you the ability to customize its use, for example, by adding custom headers or enabling Transport Layer Security (TLS) authentication. For more details, see xref:registry-client-config[]. diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-demo.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-demo.adoc index ad29a33176..355d9e17b6 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-demo.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-demo.adoc @@ -1,11 +1,20 @@ // Metadata created by nebel [id="registry-demo"] -= Registry demonstration examples -{registry} provides an open source demonstration example of Apache Avro serialization/deserialization with storage in Apache Kafka Streams. This example shows how the serializer/deserializer obtains the Avro schema from the registry at runtime and uses it to serialize and deserialize Kafka messages. For more details, see link:https://github.com/Apicurio/apicurio-registry-demo[]. += {registry} demonstration examples +{registry} provides an open source demonstration of Apache Avro serialization/deserialization with storage in Apache Kafka Streams. This example shows how the serializer/deserializer obtains the Avro schema from the registry at runtime and uses it to serialize and deserialize Kafka messages. For more details, see link:https://github.com/Apicurio/apicurio-registry-demo[]. -This demonstration also provides simple examples of both -link:https://github.com/Apicurio/apicurio-registry-demo/tree/master/src/main/java/io/apicurio/registry/demo/simple[Avro and JSON Schema serialization/deserialization with storage in Apache Kafka]. +{registry} also provides the following example applications: + +* Simple Avro example +* Simple JSON Schema example +* Confluent Serdes integration +* Avro bean example +* Custom ID strategy example +* Simple Avro Maven example +* REST client example + +For more details, see link:https://github.com/Apicurio/apicurio-registry-examples[] ifdef::rh-service-registry[] For another open source demonstration example with detailed instructions on Avro serialization/deserialization with storage in Apache Kafka, see the Red Hat Developer article on link:https://developers.redhat.com/blog/2019/12/16/getting-started-with-red-hat-integration-service-registry/[Getting Started with Red Hat Integration Service Registry]. diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-distros.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-distros.adoc index 11230ac5c1..c2dbfac78c 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-distros.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-distros.adoc @@ -1,9 +1,7 @@ // Metadata created by nebel [id="registry-distros"] -= Available distributions - -{registry} includes the following distributions: += {registry} available distributions ifdef::apicurio-registry[] diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-overview.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-overview.adoc index d2374e1643..cf92deafbb 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-overview.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-overview.adoc @@ -21,7 +21,7 @@ ifdef::rh-service-registry[] endif::[] [discrete] -== {registry} main features +== {registry} capabilities * Support for multiple payload formats for standard event schemas and API specifications diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-rest-api.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-rest-api.adoc index 52d88cab0e..138bf59ceb 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-rest-api.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-rest-api.adoc @@ -1,7 +1,7 @@ // Metadata created by nebel [id="registry-rest-api"] -= Registry REST API += Registry REST API overview Using the Registry REST API, client applications can manage the artifacts in {registry}. This API provides create, read, update, and delete operations for: Artifacts:: diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-rules.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-rules.adoc index e894867af3..3d641f0e75 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-rules.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-rules.adoc @@ -2,7 +2,7 @@ [id="registry-rules"] -= Rules for registry content += Govern registry content using rules To govern the evolution of registry content, you can configure optional rules for artifact content added to the registry. All configured global rules or artifact rules must pass before a new artifact version can be uploaded to the registry. Configured artifact rules override any configured global rules. The goal of these rules is to prevent invalid content from being added to the registry. For example, content can be invalid for the following reasons: @@ -32,31 +32,32 @@ Each rule has a name and optional configuration information. The registry storag A rule is provided with the content of the current version of the artifact (if one exists) and the new version of the artifact being added. The rule implementation returns true or false depending on whether the artifact passes the rule. If not, the registry reports the reason why in an HTTP error response. Some rules might not use the previous version of the content. For example, compatibility rules use previous versions, but syntax or semantic validity rules do not. .Additional resources -For more details, see {registry-rule-types} and {registry-rule-maturity-matrix}. +For more details, see {registry-reference}. [id="registry-rules-config"] -= Configuring rules -You can configure rules individually for each artifact, as well as globally. {registry} applies the rules configured -for the specific artifact, but if no rules are configured at that level it applies the globally configured rules. If -no global rules are configured then no rules are applied. += Content rule configuration +You can configure rules individually for each artifact, as well as globally. {registry} applies the rules configured for the specific artifact. But if no rules are configured at that level, {registry} applies the globally configured rules. If no global rules are configured, no rules are applied. -== Configuring artifact rules -You can configure artifact rules using the REST API or the web console. See the relevant documentation sections -for more information. +[discrete] +== Configure artifact rules +You can configure artifact rules using the {registry} web console or REST API. For details, see the following: -== Configuring global rules +* {managing-registry-artifacts-ui} +* link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation] + +[discrete] +== Configure global rules You can configure global rules in several ways: * Use the `/rules` operations in the REST API -* Use the web console +* Use the {registry} web console * Set default global rules using {registry} application properties -.Default global rules -You can configure the {registry} at the application level to enable or disable global rules. This allows -configuring of these global rules at installation time without any need for post-install configuration. You -can use the following application property format: - -`registry.rules.global.` +.Configure default global rules +You can configure {registry} at the application level to enable or disable global rules. You can configure default global rules at installation time without post-install configuration using the following application property format: +---- +registry.rules.global. +---- The following rule names are currently supported: @@ -64,8 +65,9 @@ The following rule names are currently supported: * `validity` The value of the application property must be a valid configuration option that is specific to the rule being -configured. The following is a table of valid values for each rule: +configured. The following table shows the valid values for each rule: +.{registry} content rules [%header,cols=2*] |=== |Rule @@ -93,5 +95,4 @@ a| `NONE` |=== NOTE: You can configure these application properties as Java system properties or include them in the Quarkus -`application.properties` file. See more information about configuring {registry} elsewhere in this -documentation and also in https://quarkus.io/guides/config#overriding-properties-at-runtime[Quarkus documentation]. +`application.properties` file. For more details, see the https://quarkus.io/guides/config#overriding-properties-at-runtime[Quarkus documentation]. diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-serde.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-serde.adoc index d5d187e62b..d4e89e2156 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-serde.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-serde.adoc @@ -2,7 +2,7 @@ [id="client-serde"] -= Kafka client serializers/deserializers += Validate schemas with Kafka client serializers/deserializers Kafka producer applications can use serializers to encode messages that conform to a specific event schema. Kafka consumer applications can then use deserializers to validate that messages have been serialized using the correct schema, based on a specific schema ID. .{registry} and Kafka client serializer/deserializer architecture @@ -16,10 +16,5 @@ image::images/getting-started/registry-serdes-architecture.png[Registry Serdes a The {registry} Maven repository and source code distributions include the Kafka serializer/deserializer implementations for these message types, which Kafka client developers can use to integrate with the registry. These implementations include custom `io.apicurio.registry.utils.serde` Java classes for each supported message type, which client applications can use to pull schemas from the registry at runtime for validation. -ifdef::rh-service-registry[] - .Additional resources -* For instructions on how to use the {registry} Kafka client serializer/deserializer for Apache Avro in AMQ Streams producer and consumer applications, see -link:https://access.redhat.com/documentation/en-us/red_hat_amq/{amq-version}/html/using_amq_streams_on_openshift/service-registry-str[Using AMQ Streams on Openshift]. - -endif::[] +* {kafka-client-serdes} diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-serdes-concepts.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-serdes-concepts.adoc index 8d3f010541..0a0ae09bbc 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-serdes-concepts.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-serdes-concepts.adoc @@ -15,9 +15,7 @@ Schemas can evolve, so you can define rules in {registry}, for example, to ensur * Protobuf * JSON Schema -These schema technologies can be used by client applications through Kafka client serializer/deserializer (SerDe) -services provided by {registry}. The maturity and usage of the SerDe classes provided by {registry} may vary. See -the type-specific sections below for more details about each. +These schema technologies can be used by client applications through Kafka client serializer/deserializer (SerDe) services provided by {registry}. The maturity and usage of the SerDe classes provided by {registry} may vary. See the type-specific sections below for more details about each. = Producer schema configuration @@ -30,12 +28,10 @@ To enable a producer to use {registry} for serialization: ** URL of {registry} ** {registry} serializer to use with the messages -** _Strategy_ to map the Kafka message to an artifact ID in {registry} -** _Strategy_ to look up (or register) the schema used for serialization in {registry} +** Strategy to map the Kafka message to an artifact ID in {registry} +** Strategy to look up or register the schema used for serialization in {registry} -After registering your schema, when you start Kafka and {registry}, you can access the schema to format messages -sent to the Kafka broker topic by the producer. Alternatively (depending on configuration), the producer can -automatically register the schema on first use. +After registering your schema, when you start Kafka and {registry}, you can access the schema to format messages sent to the Kafka broker topic by the producer. Alternatively (depending on configuration), the producer can automatically register the schema on first use. If a schema already exists, you can create a new version using the REST API based on compatibility rules defined in {registry}. Versions are used for compatibility checking as a schema evolves. An artifact ID and schema version represents a unique tuple that identifies a schema. @@ -50,15 +46,11 @@ To enable a consumer to use {registry} for deserialization: ** {registry} deserializer to use with the messages ** Input data stream for deserialization -The schema is then retrieved by the deserializer using a global ID written into the message being consumed. The schema -global ID can be located in the message headers or in the message payload itself, depending on the configuration of -the producer application. +The schema is then retrieved by the deserializer using a global ID written into the message being consumed. The schema global ID can be located in the message headers or in the message payload itself, depending on the configuration of the producer application. -When locating the global ID in the message payload, the format of the data begins with a magic byte (as a signal to -consumers) followed by the global ID and then the message data as normal. +When locating the global ID in the message payload, the format of the data begins with a magic byte (as a signal to consumers) followed by the global ID and then the message data as normal. For example: - [source,shell,subs="+quotes,attributes"] ---- # ... diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-serdes-strategy.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-serdes-strategy.adoc index 0bf39f3f52..c938836e86 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-serdes-strategy.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-serdes-strategy.adoc @@ -11,30 +11,24 @@ For a given topic and message, you can use implementations of the following Java * `ArtifactIdStrategy` to return an artifact ID * `GlobalIdStrategy` to return a global ID -.Artifact ID strategy - -The artifact ID strategy provides a way to map the Kafka topic and message information to the ID of an artifact in -{registry}. The common convention for the mapping is to combine the Kafka topic name with either `key` or `value` -(depending on whether the serializer is being used for the Kafka message key or value). However, alternative -conventions can be used for the mapping, either by using an alternative strategy provided by {registry} or by -creating a custom Java class that implements `io.apicurio.registry.utils.serde.strategy.ArtifactIdStrategy`. - -.Global ID strategy - -The global ID strategy is responsible for locating and identifying the specific *version* of the schema registered -under the artifact ID provided by the artifact ID strategy. Every version of every artifact has a single globally -unique identifier that can be used to retrieve the content of that artifact. As described in a previous section, -that global ID is what gets included in every Kafka message so that a deserializer can properly fetch the schema -from {registry}. The global ID strategy can either lookup an existing artifact version, or it can register one if -not found, depending on which strategy is used. Additionally, you can provide your own strategy by creating a -custom Java class that implements `io.apicurio.registry.utils.serde.strategy.GlobalIdStrategy`. +[discrete] +== Artifact ID strategy -The classes for each strategy are organized in the `io.apicurio.registry.utils.serde.strategy` package. +The artifact ID strategy provides a way to map the Kafka topic and message information to the ID of an artifact in {registry}. The common convention for the mapping is to combine the Kafka topic name with either `key` or `value`, depending on whether the serializer is being used for the Kafka message key or value). -The default artifact ID strategy is `TopicIdStrategy`, which looks for {registry} artifacts with the same name as the Kafka topic receiving messages. +However, you can use alternative conventions for the mapping, either by using an alternative strategy provided by {registry} or by creating a custom Java class that implements `io.apicurio.registry.utils.serde.strategy.ArtifactIdStrategy`. -.Example +[discrete] +== Global ID strategy + +The global ID strategy locates and identifies the specific version of the schema registered under the artifact ID provided by the artifact ID strategy. Every version of every artifact has a single globally unique identifier that can be used to retrieve the content of that artifact. That global ID is what gets included in every Kafka message so that a deserializer can properly fetch the schema from {registry}. +The global ID strategy can either lookup an existing artifact version, or it can register one if not found, depending on which strategy is used. Additionally, you can provide your own strategy by creating a +custom Java class that implements `io.apicurio.registry.utils.serde.strategy.GlobalIdStrategy`. + +The classes for each strategy are organized in the `io.apicurio.registry.utils.serde.strategy` package. The default artifact ID strategy is `TopicIdStrategy`, which looks for {registry} artifacts with the same name as the Kafka topic receiving messages. + +.Example [source,java,subs="+quotes,attributes"] ---- public String artifactId(String topic, boolean isKey, T schema) { diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-serdes-types.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-serdes-types.adoc index a8fbb61487..ca49069878 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-serdes-types.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-serdes-types.adoc @@ -4,25 +4,20 @@ [id='registry-serdes-types-serde-{context}'] = Configuring different SerDe types -When using a schema technology in your Kafka applications, you must choose which specific schema type to use. Common -options include: +When using a schema technology in your Kafka applications, you must choose which specific schema type to use. Common options include: * Apache Avro * JSON Schema * Google Protobuf -Which schema technology you choose is dependent on use case and preference. Of course Kafka allows you to implement -your own custom serializer and deserializer classes, so you are always free to write your own classes, including -leveraging {registry} functionality by utilizing the REST Client (see the "Using the {registry} Java client" section). +Which schema technology you choose is dependent on use case and preference. Of course you can use Kafka to implement custom serializer and deserializer classes, so you are always free to write your own classes, including leveraging {registry} functionality using the {registry} REST Java client. -For your convenience, {registry} provides out of the box SerDe classes for all three of the above schema technologies. -This section of the documentation explains how to configure Kafka applications to use each type. +For your convenience, {registry} provides out-of-the box SerDe classes for all three schema technologies. This section explains how to configure Kafka applications to use each type. -Using one of the serializer or deserializer classes provided by {registry} in your Kafka application is as simple -as setting the proper configuration properties. Here are some simple examples of configuring producer and -consumer Kafka applications. +Using one of the serializer or deserializer classes provided by {registry} in your Kafka application involves setting the correct configuration properties. Here are some simple examples of configuring producer and consumer Kafka applications. -.Configuring a producer +[discrete] +== Configuring a producer [source,java,subs="+quotes,attributes"] ---- @@ -55,7 +50,8 @@ public Producer createKafkaProducer(String kafkaBootstrapServers, } ---- -.Configuring a consumer +[discrete] +== Configuring a consumer [source,java,subs="+quotes,attributes"] ---- @@ -87,11 +83,10 @@ public Consumer createKafkaConsumer(String kafkaBootstrapServers, } ---- - == Using Avro SerDe with {registry} -{registry} provides serializer and deserializer classes for Apache Avro out of the box, to make using Avro as -easy as possible. These classes are: +{registry} provides serializer and deserializer classes for Apache Avro to make using Avro as +easy as possible. These classes are: * `io.apicurio.registry.utils.serde.AvroKafkaSerializer` * `io.apicurio.registry.utils.serde.AvroKafkaDeserializer` @@ -101,65 +96,53 @@ easy as possible. These classes are: You can configure the Avro serializer class in the following ways: * {registry} location as a URL -* Artifact ID strategy (see the "Strategies to lookup a schema" section) -* Global ID strategy (see the "Strategies to lookup a schema" section) +* Artifact ID strategy +* Global ID strategy * Global ID location * Global ID handler * Avro datum provider * Avro encoding -==== *Global ID location* - -The serializer is responsible for passing the unique global ID of the schema as part of the Kafka message so that -consumers can use the right schema for deserialization. The location of that global ID can be in the payload of -the message or in the message headers. The default approach is to pass the global ID in the message payload. If -you want the ID sent in the message headers instead, you can set the following configuration property: - -`props.putIfAbsent(AbstractKafkaSerDe.USE_HEADERS, "true")` - +.Global ID location +lizer is responsible for passing the unique global ID of the schema as part of the Kafka message so that consumers can use the right schema for deserialization. The location of that global ID can be in the payload of the message or in the message headers. The default approach is to pass the global ID in the message payload. If you want the ID sent in the message headers instead, you can set the following configuration property: +---- +props.putIfAbsent(AbstractKafkaSerDe.USE_HEADERS, "true") +---- The property name is `apicurio.registry.use.headers`. -==== *Global ID handler* - +.Global ID handler You can customize precisely how the global ID is encoded when passing it in the Kafka message body. Set the configuration property `apicurio.registry.id-handler` to be a class that implements the -`io.apicurio.registry.utils.serde.strategy.IdHandler` interface. {registry} provides two implementations of +`io.apicurio.registry.utils.serde.strategy.IdHandler` interface. {registry} provides two implementations of that interface: * `io.apicurio.registry.utils.serde.strategy.DefaultIdHandler` - stores the ID as an 8 byte long * `io.apicurio.registry.utils.serde.strategy.Legacy4ByteIdHandler` - stores the ID as an 4 byte int -{registry} represents the global ID of an artifact as a long, but for legacy reasons (or for compatibility with -other registries or serde classes) you may want to use 4 bytes when sending the ID. +{registry} represents the global ID of an artifact as a long, but for legacy reasons (or for compatibility with other registries or serde classes) you may want to use 4 bytes when sending the ID. -==== *Avro datum provider* +.Avro datum provider Avro provides different Datum writers and readers to write and read data. {registry} supports three different types: * Generic * Specific * Reflect -{registry}'s `AvroDatumProvider` is the abstraction on which type is then actually used, -where `DefaultAvroDatumProvider` is used by default. +The {registry} `AvroDatumProvider` is the abstraction on which type is then actually used, where `DefaultAvroDatumProvider` is used by default. There are two configuration options you can set: -* `apicurio.registry.avro-datum-provider` - provide a fully qualified Java classname of the `AvroDatumProvider` implementation, for example `io.apicurio.registry.utils.serde.avro.ReflectAvroDatumProvider` -* `apicurio.registry.use-specific-avro-reader` - true or false, to use Specific type when using `DefaultAvroDatumProvider` +* `apicurio.registry.avro-datum-provider` - provide a fully qualified Java class name of the `AvroDatumProvider` implementation, for example `io.apicurio.registry.utils.serde.avro.ReflectAvroDatumProvider` +* `apicurio.registry.use-specific-avro-reader` - true or false, to use specific type when using `DefaultAvroDatumProvider` -==== *Avro encoding* +.Avro encoding -When using Apache Avro to serializer data, it is common to use the Avro binary encoding format. This is so that -the data is encoded in as efficient a format as possible. However, Avro also supports encoding the data as JSON. -Encoding as JSON is useful because it is much easier to inspect the payload of each message, often for logging, -debugging, or other similar use cases. The {registry} Avro serializer can be configured to change the encoding -to JSON from the default (binary). +When using Apache Avro to serializer data, it is common to use the Avro binary encoding format. This is so that the data is encoded in as efficient a format as possible. However, Avro also supports encoding the data as JSON. Encoding as JSON is useful because it is much easier to inspect the payload of each message, often for logging, debugging, or other similar use cases. The {registry} Avro serializer can be configured to change the encoding to JSON from the default (binary). Set the Avro encoding to use by configuring the `apicurio.avro.encoding` property. The value must be either `JSON` or `BINARY`. - === Configuring the Avro deserializer You must configure the Avro deserializer class to match the configuration settings of the serializer. As a @@ -172,45 +155,46 @@ result, you can configure the Avro deserializer class in the following ways: See the serializer documentation for the above configuration options - the property names and values are the same. -NOTE: The following options are *not* needed when configuring the deserializer: +[NOTE] +==== +The following options are not needed when configuring the deserializer: * Artifact ID strategy * Global ID strategy * Global ID location +==== The reason these options are not necessary is that the deserializer class can figure this information out from -the message itself. In the case of the two strategies, they are not needed because the serializer is responsible -for sending the global ID of the schema as part of the message. And the location of that global ID is determined -(by the deserializer) by simply checking for the magic byte at the start of the message payload. If that byte is -found then the global ID is read from the message payload (using the configured handler). If the magic byte is -not found, then the global ID is read from the message headers. +the message itself. In the case of the two strategies, they are not needed because the serializer is responsible for sending the global ID of the schema as part of the message. + +The location of that global ID is determined by the deserializer by simply checking for the magic byte at the start of the message payload. If that byte is found, the global ID is read from the message payload using the configured handler. If the magic byte is not found, the global ID is read from the message headers. == Using JSON Schema SerDe with {registry} -{registry} provides serializer and deserializer classes for JSON Schema out of the box, to make using JSON Schema as -easy as possible. These classes are: +{registry} provides serializer and deserializer classes for JSON Schema to make using JSON Schema as easy as possible. These classes are: * `io.apicurio.registry.utils.serde.JsonSchemaKafkaSerializer` * `io.apicurio.registry.utils.serde.JsonSchemaKafkaDeserializer` Unlike Apache Avro, JSON Schema is not actually a serialization technology - it is instead a validation -technology. As a result, configuration options for JSON Schema are quite different. For example, there is no -*encoding* option, since data is always encoded as JSON. +technology. As a result, configuration options for JSON Schema are quite different. For example, there is no +encoding option, because data is always encoded as JSON. === Configuring the JSON Schema serializer You can configure the JSON Schema serializer class in the following ways: * {registry} location as a URL -* Artifact ID strategy (see the "Strategies to lookup a schema" section) -* Global ID strategy (see the "Strategies to lookup a schema" section) +* Artifact ID strategy +* Global ID strategy * Validation enabled/disabled As you can see, the only non-standard configuration property is whether JSON Schema validation is enabled or disabled. The validation feature is disabled by default but can be enabled by setting -`apicurio.registry.serdes.json-schema.validation-enabled` to `"true"`. For example: - -`props.putIfAbsent(JsonSchemaSerDeConstants.REGISTRY_JSON_SCHEMA_VALIDATION_ENABLED, "true")` +`apicurio.registry.serdes.json-schema.validation-enabled` to `"true"`. For example: +---- +props.putIfAbsent(JsonSchemaSerDeConstants.REGISTRY_JSON_SCHEMA_VALIDATION_ENABLED, "true")` +---- === Configuring the JSON Schema deserializer @@ -219,17 +203,14 @@ You can configure the JSON Schema deserializer class in the following ways: * {registry} location as a URL * Validation enabled/disabled -As you can see, the deserializer is very simple to configure. You need to provide the location of {registry} so -that the schema can be loaded. The only other configuration is whether or not to perform validation. These +The deserializer is simple to configure. You must provide the location of {registry} so that the schema can be loaded. The only other configuration is whether or not to perform validation. These configuration properties are the same as for the serializer. -NOTE: Deserializer validation will only work if the serializer passes the global ID in the Kafka message, which -will only happen when validation is enabled in the serializer. +NOTE: Deserializer validation only works if the serializer passes the global ID in the Kafka message, which will only happen when validation is enabled in the serializer. == Using Protobuf SerDe with {registry} -{registry} provides serializer and deserializer classes for Google Protobuf out of the box, to make using Protobuf as -easy as possible. These classes are: +{registry} provides serializer and deserializer classes for Google Protobuf out of the box, to make using Protobuf as easy as possible. These classes are: * `io.apicurio.registry.utils.serde.ProtobufKafkaSerializer` * `io.apicurio.registry.utils.serde.ProtobufKafkaDeserializer` @@ -239,33 +220,33 @@ easy as possible. These classes are: You can configure the Protobuf serializer class in the following ways: * {registry} location as a URL -* Artifact ID strategy (see the "Strategies to lookup a schema" section) -* Global ID strategy (see the "Strategies to lookup a schema" section) +* Artifact ID strategy +* Global ID strategy * Global ID location * Global ID handler === Configuring the Protobuf deserializer -You must configure the Protobuf deserializer class to match the configuration settings of the serializer. As a -result, you can configure the Protobuf deserializer class in the following ways: +You must configure the Protobuf deserializer class to match the configuration settings of the serializer. As a result, you can configure the Protobuf deserializer class in the following ways: * {registry} location as a URL * Global ID handler -See the serializer documentation for the above configuration options - the property names and values are the same. +See the serializer documentation these configuration options - the property names and values are the same. -NOTE: The following options are *not* needed when configuring the deserializer: +[NOTE] +==== +The following options are not needed when configuring the deserializer: * Artifact ID strategy * Global ID strategy * Global ID location +==== The reason these options are not necessary is that the deserializer class can figure this information out from -the message itself. In the case of the two strategies, they are not needed because the serializer is responsible -for sending the global ID of the schema as part of the message. And the location of that global ID is determined -(by the deserializer) by simply checking for the magic byte at the start of the message payload. If that byte is -found then the global ID is read from the message payload (using the configured handler). If the magic byte is -not found, then the global ID is read from the message headers. - -NOTE: the Protobuf deserializer doesn't deserialize to your exact Protobuf Message implementation, -but rather to a `DynamicMessage` instance (as there is no appropriate API to do otherwise). +the message itself. In the case of the two strategies, they are not needed because the serializer is responsible for sending the global ID of the schema as part of the message. + +The location of that global ID is determined (by the deserializer) by simply checking for the magic byte at the start of the message payload. If that byte is found, the global ID is read from the message payload (using the configured handler). If the magic byte is not found, the global ID is read from the message headers. + +NOTE: The Protobuf deserializer does not deserialize to your exact Protobuf Message implementation, +but rather to a `DynamicMessage` instance (because there is no appropriate API to do otherwise). diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-storage.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-storage.adoc index d51e529319..202af8236b 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-storage.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-storage.adoc @@ -1,7 +1,7 @@ // Metadata created by nebel [id="registry-storage"] -= Storage options += {registry} storage options {registry} provides the following underlying storage implementations for registry artifacts: ifdef::apicurio-registry[] @@ -12,7 +12,7 @@ ifdef::apicurio-registry[] * Apache Kafka Streams * Embedded Infinispan cache -NOTE: The in-memory storage option is suitable for a development environment only. All data is lost when restarting this storage implementation. All other storage options are suitable for development and production environments. +NOTE: The in-memory storage option is suitable for a development environment only. All data is lost when restarting {registry} with this storage. The Kafka Streams storage option is recommended for production environments. endif::[] @@ -43,9 +43,6 @@ These features provide early access to upcoming product features, enabling custo endif::[] .Additional resources - -For details on how to install into your preferred storage option, see: - ifdef::apicurio-registry[] * {installing-the-registry-docker} endif::[] diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-web-console.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-web-console.adoc index a8a815bf61..2ec474592e 100644 --- a/docs/modules/ROOT/partials/getting-started/con-registry-web-console.adoc +++ b/docs/modules/ROOT/partials/getting-started/con-registry-web-console.adoc @@ -1,13 +1,16 @@ // Metadata created by nebel [id="registry-web-console"] -= {registry} web console += Manage content using {registry} web console You can use the {registry} web console to browse and search the artifacts stored in the registry, and to upload new artifacts and artifact versions. You can search for artifacts by label, name, and description. You can also view an artifact’s content, view all of its available versions, or download an artifact file locally. -You can also use the {registry} web console to configure optional rules for registry content, both globally and for each artifact. These optional rules for content validation and compatibility are applied when new artifacts or artifact versions are uploaded to the registry. For more details, see {registry-rule-types} and {registry-rule-maturity-matrix}. +You can also use the {registry} web console to configure optional rules for registry content, both globally and for each artifact. These optional rules for content validation and compatibility are applied when new artifacts or artifact versions are uploaded to the registry. For more details, see {registry-reference}. .{registry} web console image::images/getting-started/registry-web-console.png[{registry} web console] -The {registry} web console is available from the main endpoint of your {registry} deployment, for example, on `\http://MY-REGISTRY-URL/ui`. For more details, see {managing-registry-artifacts-ui}. +The {registry} web console is available from the main endpoint of your {registry} deployment, for example, on `\http://MY-REGISTRY-URL/ui`. + +.Additional resources + * {managing-registry-artifacts-ui} diff --git a/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-ui.adoc b/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-ui.adoc index dba292adf9..eec08c129a 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-ui.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-configuring-registry-ui.adoc @@ -1,36 +1,39 @@ [id="configuring-registry-ui"] -= Configuring {registry} web console += Configuring {registry} web console -You can configure the {registry} web console in a number of ways, either to customize its behavior or to properly -configure it for your deployment environment. +You can configure the {registry} web console specifically for your deployment environment or to customize its behavior. This section provides details on how to configure optional environment variables for the {registry} web console. -== Configuring {registry} web console for deployment environment +.Prerequisites +* You must have already installed {registry}. -When a user navigates their browser to the {registry} web console, some initial configuration settings are loaded. -Two important configuration properties are: +[discrete] +== Configuring the web console deployment environment -* URL of the back-end API -* URL of the front-end web console +When a user navigates their browser to the {registry} web console, some initial configuration settings are loaded. Two important configuration properties are: -Typically {registry} will automatically detect and generate these settings, but there are some deployment environments -where this automatic detection can fail. When this happens, you can configure the following environment variables to -explicitly set them: +* URL for backend {registry} REST API +* URL for frontend {registry} web console -* *_REGISTRY_UI_CONFIG_APIURL_* : set to override the URL to the back-end API (example https://registry.my-domain.com/api) -* *_REGISTRY_UI_CONFIG_UIURL_* : set to override the URL to the front-end web console (example https://registry.my-domain.com/ui) +Typically, {registry} automatically detects and generates these settings, but there are some deployment environments where this automatic detection can fail. If this happens, you can configure environment variables to explicitly set these URLs for your environment. -== Configuring {registry} console for read-only mode +.Procedure +Configure the following environment variables to override the default URLs: -An optional feature that can be enabled in {registry} is the ability to put the web console into "Read Only" -mode. This mode disables all of the features in the web console that would allow a user to make changes to -registered artifacts. This includes (but is not limited to): +* `REGISTRY_UI_CONFIG_APIURL`: Set the URL for the backend {registry} REST API. For example,`\https://registry.my-domain.com/api` +* `REGISTRY_UI_CONFIG_UIURL`: Set the URL for the frontend {registry} web console. For example, `\https://registry.my-domain.com/ui` + +[discrete] +== Configuring the console in read-only mode + +You can configure the {registry} web console in read-only mode as an optional feature. This mode disables all features in the {registry} web console that allow users to make changes to registered artifacts. For example, this includes the following: * Creating an artifact * Uploading a new version of an artifact * Updating an artifact's metadata * Deleting an artifact -To put the web console into read only mode, set the following environment variable: +.Procedure +Configure the following environment variable to set the {registry} web console in read-only mode: -* *_REGISTRY_UI_FEATURES_READONLY_* : set to `true` to enable "Read Only" mode (default `false`) +* `REGISTRY_UI_FEATURES_READONLY`: Set to `true` to enable read-only mode. Defaults to `false`. diff --git a/docs/modules/ROOT/partials/getting-started/proc-managing-artifacts-using-maven-plugin.adoc b/docs/modules/ROOT/partials/getting-started/proc-managing-artifacts-using-maven-plugin.adoc index c17da1ddee..c450d3780a 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-managing-artifacts-using-maven-plugin.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-managing-artifacts-using-maven-plugin.adoc @@ -4,22 +4,16 @@ [id="managing-artifacts-using-maven-plugin"] = Managing artifacts using the {registry} Maven plug-in -{registry} provides a Maven plug-in to enable you to upload or download registry artifacts as part of your development build. For example, this plug-in is useful for testing and validating that your schema updates are compatible with client applications. - -.Prerequisites - -* See {registry-overview} -* {registry} must be installed and running in your environment -* Maven must be installed and configured in your environment +You can use the {registry} Maven plug-in to upload or download registry artifacts as part of your development build. For example, this plug-in is useful for testing and validating that your schema updates are compatible with client applications. +[discrete] == Registering an artifact using the Maven plug-in -Probably the most common use case for the Maven plug-in is registering artifacts during a build. You can accomplish -this by using the `register` goal provided. Simply update your Maven `pom.xml` file to use the -`apicurio-registry-maven-plugin` to upload an artifact to {registry}. - -The following example shows registering an Apache Avro schema artifact: +Probably the most common use case for the Maven plug-in is registering artifacts during a build. You can accomplish this by using the `register` execution goal. +.Procedure +* Update your Maven `pom.xml` file to use the `apicurio-registry-maven-plugin` to register an artifact. The following example shows registering an Apache Avro schema: ++ [source,xml] ---- @@ -43,16 +37,17 @@ The following example shows registering an Apache Avro schema artifact: ---- -<1> Specify `register` as the execution goal to upload an artifact to the registry. +<1> Specify `register` as the execution goal to upload the schema artifact to the registry. <2> You must specify the {registry} URL with the `/api` endpoint. <3> You can upload multiple artifacts using the artifact ID and location. +[discrete] == Downloading an artifact using the Maven plug-in -You can also use the Maven plug-in to download artifacts from {registry}. This is often useful, for example, when -generating code from a registered schema. - -The following example shows downloading a single schema by its artifact ID. +You can also use the Maven plug-in to download artifacts from {registry}. This is often useful, for example, when generating code from a registered schema. +.Procedure +* Update your Maven `pom.xml` file to use the `apicurio-registry-maven-plugin` to download an artifact. The following example shows downloading a single schema by its artifact ID. ++ [source,xml] ---- @@ -80,17 +75,17 @@ The following example shows downloading a single schema by its artifact ID. <1> Specify `download` as the execution goal. <2> You must specify the {registry} URL with the `/api` endpoint. <3> You can download multiple artifacts to a specified directory using the artifact ID. -<4> The plug-in will automatically try to select an appropriate file extension, but you can override it using ``. - -== Testing an artifact -You may want to simply verify that an artifact can be registered without actually making any changes. This is most -often useful when rules have been configured in {registry}. Testing the artifact will result in a failure if the -artifact content violates any of the configured rules. +<4> The plug-in automatically tries to select an appropriate file extension, but you can override it using ``. -NOTE: Even if the artifact passes the test, no content will be added to {registry}. +[discrete] +== Testing an artifact using the Maven plug-in +You might want to verify that an artifact can be registered without actually making any changes. This is most often useful when rules are configured in {registry}. Testing the artifact results in a failure if the artifact content violates any of the configured rules. -The following example shows testing an Apache Avro schema artifact: +NOTE: Even if the artifact passes the test, no content is added to {registry}. +.Procedure +* Update your Maven `pom.xml` file to use the `apicurio-registry-maven-plugin` to test an artifact. The following example shows testing an Apache Avro schema: ++ [source,xml] ---- @@ -114,9 +109,9 @@ The following example shows testing an Apache Avro schema artifact: ---- -<1> Specify `test-update` as the execution goal to test an artifact. +<1> Specify `test-update` as the execution goal to test the schema artifact. <2> You must specify the {registry} URL with the `/api` endpoint. <3> You can test multiple artifacts using the artifact ID and location. .Additional resources - * For more details on the Maven plug-in, see https://github.com/Apicurio/apicurio-registry-demo. + * For more details on the {registry} Maven plug-in, see the link:https://github.com/Apicurio/apicurio-registry-demo[Registry demonstration example] diff --git a/docs/modules/ROOT/partials/getting-started/proc-writing-registry-client.adoc b/docs/modules/ROOT/partials/getting-started/proc-writing-registry-client.adoc index 4254a03c55..8f12b5f6c2 100644 --- a/docs/modules/ROOT/partials/getting-started/proc-writing-registry-client.adoc +++ b/docs/modules/ROOT/partials/getting-started/proc-writing-registry-client.adoc @@ -2,15 +2,17 @@ // ParentAssemblies: assemblies/getting-started/as_installing-the-registry.adoc [id="writing-registry-client"] -= Writing a {registry} client application += Writing {registry} client applications -This section explains how to manage artifacts stored in {registry} using a Java client application. +This section explains how to manage artifacts stored in {registry} using a Java client application. The {registry} Java client extends the `Autocloseable` interface. .Prerequisites * See {registry-overview} -* {registry} must be installed and running in your environment. -* Add the following dependency to your Maven project: +* {registry} must be installed and running in your environment +.Procedure +. Add the following dependency to your Maven project: ++ [source,xml,subs="+quotes,attributes"] ---- @@ -20,8 +22,7 @@ This section explains how to manage artifacts stored in {registry} using a Java ---- -.Procedure -. Create a registry client +. Create a registry client as follows: + [source,java,subs="+quotes,attributes"] ---- @@ -30,22 +31,19 @@ public class ClientExample { private static final RegistryRestClient client; public static void main(String[] args) throws Exception { - // Create a Service Registry client - String registryUrl = "http://localhost:8080/api/"; - RegistryRestClient client = RegistryRestClientFactory.create(registryUrl); <1> + // Create a registry client + String registryUrl = "https://registry.my-domain.com/api"; <1> + RegistryRestClient client = RegistryRestClientFactory.create(registryUrl); <2> } } ---- -<1> For more options on how to create a {registry} client, see {registry-client-types}. - -. Once created, all the operations from the {registry} REST API are available through the client. For details about the available -operations, see the REST API documentation. - +<1> You must specify the {registry} URL with the `/api` endpoint. +<2> For more options when creating a {registry} client, see the Java client configuration in the next section. -The {registry} Java client extends the interface Autocloseable. +. When the client is created, you can use all the operations from the {registry} REST API through the client. For more details, see the link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation]. .Additional resources -* For more examples on how to use or customize the {registry} client see https://github.com/Apicurio/apicurio-registry-examples/blob/master/rest-client +* For an example of how to use and customize the {registry} client, see the https://github.com/Apicurio/apicurio-registry-examples/blob/master/rest-client[Registry client demonstration example]. ifdef::rh-service-registry[] * For details on how to use the {registry} Kafka client serializer/deserializer for Apache Avro in AMQ Streams producer and consumer applications, see diff --git a/docs/modules/ROOT/partials/getting-started/ref-registry-artifact-metadata.adoc b/docs/modules/ROOT/partials/getting-started/ref-registry-artifact-metadata.adoc new file mode 100644 index 0000000000..037b7a302d --- /dev/null +++ b/docs/modules/ROOT/partials/getting-started/ref-registry-artifact-metadata.adoc @@ -0,0 +1,58 @@ +// Metadata created by nebel + +[id="registry-artifact-metadata"] += {registry} artifact metadata + +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. + +.{registry} metadata properties +[%header,cols=3*] +|=== +|Property +|Type +|Editable +|`id` +a| string +a| false +|`type` +a| ArtifactType +a| false +|`state` +a| ArtifactState +a| true +|`version` +a| integer +a| false +|`createdBy` +a| string +a| false +|`createdOn` +a| date +a| false +|`modifiedBy` +a| string +a| false +|`modifiedOn` +a| date +a| false +|`name` +a| string +a| true +|`description` +a| string +a| true +|`labels` +a| array of string +a| true +|`properties` +a| map +a| true +|=== + +.Updating artifact metadata +* You can use the {registry} REST API 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`. + +.Additional resources +For more details, see the `/artifacts/{artifactId}/meta` sections in the link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation]. diff --git a/docs/modules/ROOT/partials/getting-started/ref-registry-client.adoc b/docs/modules/ROOT/partials/getting-started/ref-registry-client.adoc index 4109ffc7f7..00be8323aa 100644 --- a/docs/modules/ROOT/partials/getting-started/ref-registry-client.adoc +++ b/docs/modules/ROOT/partials/getting-started/ref-registry-client.adoc @@ -1,27 +1,39 @@ // Metadata created by nebel // ParentAssemblies: assemblies/getting-started/assembly-using-the-registry-client.adoc -[id="registry-client-types"] -= {registry} Java client reference -The {registry} Java client includes the following configuration options, based on the client factory. +[id="registry-client-config"] += {registry} Java client configuration +The {registry} Java client includes the following configuration options, based on the client factory: -.{registry} Java client options -[%header,cols=3*] +.{registry} Java client configuration options +[%header,cols="1,2,1"] |=== |Option |Description |Arguments -|Plain Client +|Plain client |Basic REST client used to interact with a running registry. -|baseUrl +|`baseUrl` |Custom HTTP client |Registry client using an OkHttpClient provided by the user. -|baseUrl, okhttpClient -|Custom Configuration +|`baseUrl`, `okhttpClient` +|Custom configuration |Registry client that accepts a map containing custom configuration. This is useful, for example, to add custom headers to the calls. -|baseUrl, Map configs +|`baseUrl`, `Map configs` |=== +[discrete] +== Custom header configuration +To configure custom headers, you must add the `apicurio.registry.request.headers` prefix to the `configs` map key. For example, a key of `apicurio.registry.request.headers.Authorization` with a value of `Basic: xxxxx` results in a header of `Authorization` with value of `Basic: xxxxx`. -In order to configure custom headers, the prefix *apicurio.registry.request.headers* must be added to the configs map key, for example, a key *apicurio.registry.request.headers.Authorization* with value Basic: xxxxx would result in a header of *Authorization* with value Basic: xxxxx. +[discrete] +== TLS configuration +You can configure Transport Layer Security (TLS) authentication for the {registry} Java client using the following properties: +* `apicurio.registry.request.ssl.truststore.location` +* `apicurio.registry.request.ssl.truststore.password` +* `apicurio.registry.request.ssl.truststore.type` +* `apicurio.registry.request.ssl.keystore.location` +* `apicurio.registry.request.ssl.keystore.password` +* `apicurio.registry.request.ssl.keystore.type` +* `apicurio.registry.request.ssl.key.password` diff --git a/docs/modules/ROOT/partials/getting-started/ref-registry-rule-maturity-matrix.adoc b/docs/modules/ROOT/partials/getting-started/ref-registry-rule-maturity-matrix.adoc index bf40fe2055..6885335991 100644 --- a/docs/modules/ROOT/partials/getting-started/ref-registry-rule-maturity-matrix.adoc +++ b/docs/modules/ROOT/partials/getting-started/ref-registry-rule-maturity-matrix.adoc @@ -2,18 +2,17 @@ // ParentAssemblies: assemblies/getting-started/as_registry-reference.adoc [id="registry-rule-maturity-matrix"] -= {registry} content rule maturity matrix += {registry} content rule maturity -Not all rules are fully implemented for every artifact type supported by the registry. -The following table documents the current maturity level for each rule and each -artifact type. +Not all content rules are fully implemented for every artifact type supported by {registry}. +The following table shows the current maturity level for each rule and artifact type. .{registry} content rule maturity matrix [%header,cols=3*] |=== -|Artifact Type -|Validity Rule -|Compatibility Rule +|Artifact type +|Validity rule +|Compatibility rule |*Avro* a| Full a| Full