From b31d41e7626944b1eef4de55161ec12d712f12ee Mon Sep 17 00:00:00 2001 From: Paul Wright Date: Thu, 14 Nov 2024 12:00:54 +0000 Subject: [PATCH] json schema referencing --- .../partials/getting-started/address.json | 16 +++ .../ROOT/partials/getting-started/person.json | 19 +++ .../proc-registry-serdes-referencing.adoc | 127 ++++++++++++++++++ 3 files changed, 162 insertions(+) create mode 100644 docs/modules/ROOT/partials/getting-started/address.json create mode 100644 docs/modules/ROOT/partials/getting-started/person.json create mode 100644 docs/modules/ROOT/partials/getting-started/proc-registry-serdes-referencing.adoc diff --git a/docs/modules/ROOT/partials/getting-started/address.json b/docs/modules/ROOT/partials/getting-started/address.json new file mode 100644 index 0000000000..548b831eed --- /dev/null +++ b/docs/modules/ROOT/partials/getting-started/address.json @@ -0,0 +1,16 @@ +{ + "$id": "https://example.com/address.json", + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Address", + "type": "object", + "properties": { + "street": { + "type": "string", + "description": "The street name." + }, + "city": { + "type": "string", + "description": "The city name." + } + } +} diff --git a/docs/modules/ROOT/partials/getting-started/person.json b/docs/modules/ROOT/partials/getting-started/person.json new file mode 100644 index 0000000000..491e95affc --- /dev/null +++ b/docs/modules/ROOT/partials/getting-started/person.json @@ -0,0 +1,19 @@ +{ + "$id": "https://example.com/person.json", + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Person", + "type": "object", + "properties": { + "firstName": { + "type": "string", + "description": "first name." + }, + "lastName": { + "type": "string", + "description": "last name." + }, + "address": { + "$ref": "address.json" + } + } +} diff --git a/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-referencing.adoc b/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-referencing.adoc new file mode 100644 index 0000000000..ac507a4e1b --- /dev/null +++ b/docs/modules/ROOT/partials/getting-started/proc-registry-serdes-referencing.adoc @@ -0,0 +1,127 @@ +// Module included in the following assemblies: +// assembly-using-kafka-client-serdes +:my-reg-url: +[id='dereferencing-json-schema_{context}'] += Dereferencing a JSON Schema in {registry} + +[role="_abstract"] +Working with JSON Schemas that include references can be challenging, especially when managing schema hierarchies and optimizing HTTP requests. {registry} introduces a dereferencing feature that allows you to fetch a fully inlined schema, simplifying schema management and reducing the number of HTTP requests needed. + + +.Prerequisites + +* A complex JSON schema + +.Procedure + +. Populate the {registry} with your complex schema. ++ +-- +Consider the following schema hierarchy: + +.address.json +[source,json,subs="+quotes,attributes"] +---- +include::address.json[] +---- + +.person.json +[source,json,subs="+quotes,attributes"] +---- +include::person.json[] +---- + +The `person` schema references the `address` schema. + + +.. Register `address.json`: ++ +[source,shell,subs="+quotes,attributes"] +---- +curl -X POST 'http://localhost:8080/apis/registry/v2/groups/default/artifacts' \ + -H 'Content-Type: application/json' \ + -H 'X-Registry-ArtifactId: address' \ + --data-binary @address.json +---- + +.. Register `person.json` including the reference to `address.json`: ++ +[source,shell,subs="+quotes,attributes"] +---- +curl -X POST 'http://localhost:8080/apis/registry/v2/groups/default/artifacts' \ + -H 'Content-Type: application/create.extended+json' \ + -H 'X-Registry-ArtifactId: person' \ + --data '{ + "content": "{\"$id\":\"https:\/\/example.com\/person.json\",\"$schema\":\"http:\/\/json-schema.org\/draft-07\/schema#\",\"title\":\"Person\",\"type\":\"object\",\"properties\":{\"firstName\":{\"type\":\"string\",\"description\":\"first name\"},\"lastName\":{\"type\":\"string\",\"description\":\"last name\"},\"address\":{\"$ref\":\"address.json\"}}}", + "references": [ + { + "name": "address.json", + "groupId": "default", + "artifactId": "address", + "version": "1" + } + ] + }' + + +---- +NOTE: You must escape the content of the `person.json` and add the references when posting this artifact. + +-- +. View the artifact in the console. ++ +-- +.. Navigate to the `person` schema. For example `/explore/default/person`. +.. Click *Versions* and click the version `1` of the `person` schema. +.. Click *References* to view the schemas referenced in the `person` schema. +You can now see the references: +* *Reference Name* is `address.json` +* *ID* is `address` +* *Version* is `1`. + +{registry} resolves any reference to `address.json` in the `person` schema to version 1 of the schema with ID `address`. + +NOTE: You can also navigate to a version of the `address` schema and see that the `person` schema reference `address` by clicking *View artifacts that reference this artifact*. +-- + +. Retrieve the dereferenced schema ++ +-- +[source,shell,subs="+quotes,attributes"] +---- +$ curl --location 'http://localhost:8080/apis/registry/v2/groups/default/artifacts/person?dereference=true' +{ + "$schema" : "http://json-schema.org/draft-07/schema#", + "title" : "Person", + "type" : "object", + "properties" : { + "firstName" : { + "description" : "first name", + "type" : "string" + }, + "lastName" : { + "description" : "last name", + "type" : "string" + }, + "address" : { + "title" : "Address", + "type" : "object", + "properties" : { + "city" : { + "description" : "The city name.", + "type" : "string" + }, + "street" : { + "description" : "The street name.", + "type" : "string" + } + } + } + }, + "$id" : "https://example.com/person.json" + +---- + +You can also retrieve the dereferenced artifact using GlobalID or specifying a specific version + +-- \ No newline at end of file