avro model

Defines a model to utilize schema from catalog to enforce validation, ensuring adherence to predefined data structures.

model: avro
view: json
catalog:
  items-catalog:
    - strategy: topic
      version: latest
    - subject: items-snapshots
      version: latest
      overlay:
        items-overlay-catalog:
          subject: items-snapshots-overlay
          version: latest
    - id: 1
validate: strict

Configuration (* required)

model: avro

const

Specifies the model is avro.

view

enum [ json ]

Transforms the model from this data type to the Avro schema on encode and to this data type from the Avro schema on decode.

catalog*

object as map of named array

To map defined catalog for schema retrieval based on catalog specific parameters. Any of the possible combination can be configured.

id

---

strategyversion

---

subjectversionoverlay

catalog[].id*

integer

Define specific schema id to refer from catalog.

catalog[].version

string | Default: latest

Specific iteration or version of a registered schema in the defined catalog.

catalog[].strategy*

enum [ topic, encoded ]

To determine the subject based on the specified strategy.

catalog[].subject*

string

Unique identifier for schema categorization in the catalog.

catalog[].overlay

object as map of named object properties

References a second catalog entry whose schema is layered on top of the primary subject schema, resolved by name against the top-level catalog map.

catalog:
  items-catalog:
    - subject: items-snapshots
      version: latest
      overlay:
        items-overlay-catalog:
          subject: items-snapshots-overlay
          version: latest

overlay.subject*

string

Unique identifier for the overlay schema in the referenced catalog.

overlay.version

string | Default: latest

Specific iteration or version of the overlay schema.

validate

enum [ strict, lenient ] as string, or object | Default: strict

Controls how strictly the model enforces conformance to the schema. strict rejects data that doesn't conform to the schema; lenient passes non-conforming data through unmodified. Can also be set independently for decode and encode.

validate:
  decode: lenient
  encode: strict

validate.decode

enum [ strict, lenient ]

Validation mode applied when decoding the value.

validate.encode

enum [ strict, lenient ]

Validation mode applied when encoding the value.

transforms

Available in Zilla Plus

array of object

Defines one or more field-level transforms applied to selected fields of the model's value. encryption encrypts a field on encode; on decode, a session authorized by guarded gets the decrypted value back, and a session that isn't falls back to disclosure — redact, mask, or hash — if configured, or otherwise has the field omitted.

transforms:
  - select:
      - type: structure
        fields:
          - tagged:
              - x-kind: pii
    guarded:
      api-keys:
        - ssn:decrypt
    encryption:
      vault:
        vault0:
          - kek0
          - kek1
    disclosure:
      action: redact

transforms[].select*

array of object

Selects the fields the transform applies to.

select[].type*

enum [ structure, string, bytes ]

The value kind the selected fields belong to.

select[].fields

array of object

Identifies fields either by a tagged schema property (e.g. an x-kind annotation) or by name.

fields:
  - tagged:
      - x-kind: pii
  - named:
      - ssn

fields[].tagged

array of object

Matches fields carrying the given schema annotation, such as x-kind: pii.

fields[].named

array of string

Matches fields by name.

transforms[].guarded

object as map of named array of string

Restricts the transform to sessions authorized by the referenced guard for one of the listed roles. An authorized session gets the field's real value — decrypted, when encryption is configured, unless encryption sets its own nested guarded. An unauthorized session falls back to disclosure if configured, or otherwise has the field omitted.

guarded:
  api-keys:
    - card:full

transforms[].disclosure

Available in Zilla Plus

object

Defines the fallback applied to a selected field for a session not authorized by guarded — or, when paired with encryption, a session unable to decrypt it. Without disclosure, such a session simply has the field omitted.

disclosure.action*

enum [ redact, omit, mask, hash ]

redact replaces the value with a fixed placeholder, omit removes the field, mask replaces matching characters using pattern, mask and reveal, and hash replaces the value with a keyed hash using secret.

disclosure.pattern

string

Required when action is mask; a regular expression identifying the characters to mask.

disclosure.mask

string

The single character used to mask matched characters when action is mask.

disclosure.reveal

string

The single character used to mark characters left unmasked when action is mask.

disclosure.secret

string

The key used to compute the hash when action is hash.

transforms[].encryption

Available in Zilla Plus

object

Encrypts a selected field's value on encode, using a key encryption key (KEK) chain resolved from a vault, and decrypts it back on decode for a session authorized by guarded.

encryption:
  vault:
    vault0:
      - kek0
      - kek1
  guarded:
    api-keys:
      - card:full

encryption.vault*

object as map of named array of string

References a single named vault and the ordered chain of key aliases used to wrap the data encryption key.

encryption.guarded

object as map of named array of string

Overrides the transform's guarded specifically for gating decryption of this field. A disclosure fallback still uses the transform's guarded to decide which sessions it applies to.