From d25d70c009341ba4837362f99089bf3ff993308a Mon Sep 17 00:00:00 2001 From: Ankit Kumar Date: Thu, 1 Feb 2024 18:50:37 +0530 Subject: [PATCH] Model & View update (#181) * catalog definition update * protobuf record name update to reflect java class naming --------- Co-authored-by: AJ --- src/.vuepress/sidebar/en.ts | 8 ++ .../config/bindings/binding-kafka.md | 14 +++ src/reference/config/models/model-avro.md | 91 +++++++++++++++ src/reference/config/models/model-integer.md | 22 ++++ src/reference/config/models/model-json.md | 83 ++++++++++++++ src/reference/config/models/model-protobuf.md | 104 ++++++++++++++++++ src/reference/config/models/model-string.md | 41 +++++++ src/reference/config/overview.md | 7 ++ 8 files changed, 370 insertions(+) create mode 100644 src/reference/config/models/model-avro.md create mode 100644 src/reference/config/models/model-integer.md create mode 100644 src/reference/config/models/model-json.md create mode 100644 src/reference/config/models/model-protobuf.md create mode 100644 src/reference/config/models/model-string.md diff --git a/src/.vuepress/sidebar/en.ts b/src/.vuepress/sidebar/en.ts index 3527101a..a64a4873 100644 --- a/src/.vuepress/sidebar/en.ts +++ b/src/.vuepress/sidebar/en.ts @@ -43,6 +43,12 @@ export const enSidebar = sidebar({ link: "catalogs/", children: "structure", }, + { + text: "Models", + prefix: "models/", + link: "models/", + children: "structure", + }, { text: "Telemetry", prefix: "telemetry/", @@ -261,6 +267,8 @@ export const enSidebar = sidebar({ "config/guards/", "config/vaults/", "config/telemetry/", + "config/catalogs/", + "config/models/", "troubleshooting/aws.md", ], }, diff --git a/src/reference/config/bindings/binding-kafka.md b/src/reference/config/bindings/binding-kafka.md index ed1d7c48..7c5a6ebb 100644 --- a/src/reference/config/bindings/binding-kafka.md +++ b/src/reference/config/bindings/binding-kafka.md @@ -69,6 +69,8 @@ Conditional routes based on `kafka` `topic` names are used to route these networ - [options.topics](#options-topics) - [topics\[\].name\*](#topics-name) - [topics\[\].defaultOffset](#topics-defaultoffset) + - [topics\[\].key](#topics-key) + - [topics\[\].value](#topics-value) - [options.servers](#options-servers) - [options.sasl](#options-sasl) - [sasl.name](#sasl-name) @@ -131,6 +133,18 @@ Topic name. Fetch offset to use for new consumers +#### topics[].key + +> `object` of a named [`model`](../models/) + +Enforce validation for key + +#### topics[].value + +> `object` of a named [`model`](../models/) + +Enforce validation for value + ### options.servers > `array` of `string` diff --git a/src/reference/config/models/model-avro.md b/src/reference/config/models/model-avro.md new file mode 100644 index 00000000..96aafe79 --- /dev/null +++ b/src/reference/config/models/model-avro.md @@ -0,0 +1,91 @@ +--- +shortTitle: avro +description: Zilla runtime avro model +category: + - Models +--- + +# avro model + +::: info Feature Coming Soon +This is currently on the [Zilla roadmap](https://github.com/orgs/aklivity/projects/4). Star and watch the [Zilla repo](https://github.com/aklivity/zilla/releases) for new releases! +::: + +Zilla runtime avro model + +```yaml {1} +model: avro +view: json +catalog: + items-catalog: + - strategy: topic + version: latest + - subject: items-snapshots + version: latest + - id: 1 +``` + +## Summary + +Defines a model to utilize schema from catalog to enforce validation, ensuring adherence to predefined data structures. + +## Configuration + +:::: note Properties + +- [view](#view) +- [catalog\*](#catalog) + - [catalog.strategy](#catalog-strategy) + - [catalog.subject](#catalog-subject) + - [catalog.version](#catalog-version) + - [catalog.id](#catalog-id) + +::: right +\* required +::: + +:::: + +### view + +> `enum` [ "json" ] + +Transforms the model from this data type to the Avro schema on produce and to this data type from the Avro schema on consume. + +### catalog\* + +> `object` + +To map defined catalog for schema retrieval based on catalog specific parameters. Any of the possible combination can be configured. + +> `id` +----- +> `strategy` +> `version` +----- +> `subject` +> `version` + +#### catalog.strategy + +> `enum` [ "topic" ] + +To determine the subject based on the specified strategy + +#### catalog.subject + +> `string` + +Unique identifier for schema categorization in the catalog. + +#### catalog.version + +> `string` | Default: `"latest"` + +Specific iteration or version of a registered schema in the defined catalog. + +#### catalog.id + +> `integer` + +Define specific schema id to refer from catalog. diff --git a/src/reference/config/models/model-integer.md b/src/reference/config/models/model-integer.md new file mode 100644 index 00000000..03f4e623 --- /dev/null +++ b/src/reference/config/models/model-integer.md @@ -0,0 +1,22 @@ +--- +shortTitle: integer +description: Zilla runtime integer model +category: + - Models +--- + +# integer Model + +::: info Feature Coming Soon +This is currently on the [Zilla roadmap](https://github.com/orgs/aklivity/projects/4). Star and watch the [Zilla repo](https://github.com/aklivity/zilla/releases) for new releases! +::: + +Zilla runtime integer model + +```yaml {1} +model: integer +``` + +## Summary + +Defines a model to enforce validation for integer data. diff --git a/src/reference/config/models/model-json.md b/src/reference/config/models/model-json.md new file mode 100644 index 00000000..55b582a4 --- /dev/null +++ b/src/reference/config/models/model-json.md @@ -0,0 +1,83 @@ +--- +shortTitle: json +description: Zilla runtime json model +category: + - Models +--- + +# json Model + +::: info Feature Coming Soon +This is currently on the [Zilla roadmap](https://github.com/orgs/aklivity/projects/4). Star and watch the [Zilla repo](https://github.com/aklivity/zilla/releases) for new releases! +::: + +Zilla runtime json model + +```yaml {1} +model: json +catalog: + items-catalog: + - strategy: topic + version: latest + - subject: items-snapshots + version: latest + - id: 1 +``` + +## Summary + +Defines a model to utilize schema from catalog to enforce validation, ensuring adherence to predefined data structures. + +## Configuration + +:::: note Properties + +- [catalog\*](#catalog) + - [catalog.strategy](#catalog-strategy) + - [catalog.subject](#catalog-subject) + - [catalog.version](#catalog-version) + - [catalog.id](#catalog-id) + +::: right +\* required +::: + +:::: + +### catalog\* + +> `object` + +To map defined catalog for schema retrieval based on catalog specific parameters. Any of the possible combination can be configured. + +> `id` +----- +> `strategy` +> `version` +----- +> `subject` +> `version` + +#### catalog.strategy + +> `enum` [ "topic" ] + +To determine the subject based on the specified strategy + +#### catalog.subject + +> `string` + +Unique identifier for schema categorization in the catalog. + +#### catalog.version + +> `string` | Default: `"latest"` + +Specific iteration or version of a registered schema in the defined catalog. + +#### catalog.id + +> `integer` + +Define specific schema id to refer from catalog. diff --git a/src/reference/config/models/model-protobuf.md b/src/reference/config/models/model-protobuf.md new file mode 100644 index 00000000..3b17788f --- /dev/null +++ b/src/reference/config/models/model-protobuf.md @@ -0,0 +1,104 @@ +--- +shortTitle: protobuf +description: Zilla runtime protobuf model +category: + - Models +--- + +# protobuf Model + +::: info Feature Coming Soon +This is currently on the [Zilla roadmap](https://github.com/orgs/aklivity/projects/4). Star and watch the [Zilla repo](https://github.com/aklivity/zilla/releases) for new releases! +::: + +Zilla runtime protobuf model + +```yaml {1} +model: protobuf +view: json +catalog: + items-catalog: + - strategy: topic + version: latest + record: EchoMessage + - subject: items-snapshots + version: latest + record: EchoMessage + - id: 1 + record: EchoMessage +``` + +## Summary + +Defines a model to utilize schema from catalog to enforce validation, ensuring adherence to predefined data structures. + +## Configuration + +:::: note Properties + +- [view](#view) +- [catalog\*](#catalog) + - [catalog.strategy](#catalog-strategy) + - [catalog.subject](#catalog-subject) + - [catalog.version](#catalog-version) + - [catalog.id](#catalog-id) + - [catalog.record\*](#catalog-record) + +::: right +\* required +::: + +:::: + +### view + +> `enum` [ "json" ] + +Transforms the model from this data type to the Protobuf schema on produce and to this data type from the Protobuf schema on consume. + +### catalog\* + +> `object` + +To map defined catalog for schema retrieval based on catalog specific parameters. Any of the possible combination can be configured. + +> `id` +> `record` +----- +> `strategy` +> `version` +> `record` +----- +> `subject` +> `version` +> `record` + +#### catalog.strategy + +> `enum` [ "topic" ] + +To determine the subject based on the specified strategy + +#### catalog.subject + +> `string` + +Unique identifier for schema categorization in the catalog. + +#### catalog.version + +> `string` | Default: `"latest"` + +Specific iteration or version of a registered schema in the defined catalog. + +#### catalog.id + +> `integer` + +Define specific schema id to refer from catalog. + +#### catalog.record\* + +> `string` + +Define specific record to refer from Protobuf schema. diff --git a/src/reference/config/models/model-string.md b/src/reference/config/models/model-string.md new file mode 100644 index 00000000..4d27643e --- /dev/null +++ b/src/reference/config/models/model-string.md @@ -0,0 +1,41 @@ +--- +shortTitle: string +description: Zilla runtime string model +category: + - Models +--- + +# string Model + +::: info Feature Coming Soon +This is currently on the [Zilla roadmap](https://github.com/orgs/aklivity/projects/4). Star and watch the [Zilla repo](https://github.com/aklivity/zilla/releases) for new releases! +::: + +Zilla runtime string model + +```yaml {1} +model: string +encoding: utf_8 +``` + +## Summary + +Defines a model to enforce validation for string data. + +## Configuration + +:::: note Properties + +- [encoding\*](#encoding) + +::: right +\* required +::: + +:::: + +### encoding\* + +> `string` + +Define character encoding for unicode. diff --git a/src/reference/config/overview.md b/src/reference/config/overview.md index 1b964850..4b1c3a15 100644 --- a/src/reference/config/overview.md +++ b/src/reference/config/overview.md @@ -38,6 +38,7 @@ telemetry: - [routes.exit](#routes-exit) - [guards](#guards) - [vaults](#vaults) +- [catalogs](#catalogs) - [telemetry](#telemetry) - [attributes](#attributes) - [exporters](#exporters) @@ -102,6 +103,12 @@ See each of the specific `vault` types linked below for more detailed examples. > `object` as map of named [`catalog`](./catalogs/) properties +Each configured `catalog` represent a catalog of schemas of various format based on a specific implementation `type`. + +Catalogs can be used by specific protocol bindings to enforce validation. + +See each of the specific `catalog` types linked below for more detailed examples. + ### telemetry > `object` of [`telemetry`](./telemetry/) properties