Estàndard de Schemas a EventHub

Estàndard de Schemas a EventHub

Navegació

Quan he de consultar aquest estàndard?

Consulta aquest document quan:

• treballes amb Schema Registry a EventHub,
• defineixes o modifiques schemas,
• prepares canvis en contractes de dades,
• revises sol·licituds retornades per errors de schema.

Aquest estàndard és obligatori i s’aplica abans de qualsevol registre o evolució de schemas.

Canigó – Estàndard obligatori

1. Format recomanat

EventHub admet tres formats de schema: JSON, AVRO i PROTOBUF.

El format recomanat per defecte és AVRO pels motius següents:

• Serialització binària compacta (menor ús de xarxa i emmagatzematge).
• Suport natiu als artefactes de referència de Canigó (productor/consumidor, KStreams, KTables).
• Gestió de compatibilitat entre versions integrada amb Schema Registry.

Utilitza JSON Schema si el sistema origen/destí no suporta AVRO o si els missatges han de ser llegibles per humans en entorns de desenvolupament. Utilitza PROTOBUF únicament si existeix una justificació tècnica específica.

2. Nomenclatura dels schemas

El nom del schema ha de coincidir amb el nom complet del topic, incloent el sufix d’entorn:

El camp Nombre_Schema_Generado de la plantilla de sol·licitud genera aquest nom automàticament.

3. Schema de value vs schema de key

En la majoria de casos, la clau és un identificador simple (String) i no requereix schema de key. Registra un schema de key únicament si la clau és un objecte JSON o Avro estructurat.

4. Exemple mínim de schema AVRO

{
  "type": "record",
  "name": "AltaClient",
  "namespace": "cat.gencat.ctti.a1234.crm",
  "fields": [
    {"name": "idClient",   "type": "string",  "doc": "Identificador únic del client"},
    {"name": "nom",        "type": "string",  "doc": "Nom complet"},
    {"name": "email",      "type": ["null", "string"], "default": null, "doc": "Email de contacte (opcional)"},
    {"name": "dataAlta",   "type": "string",  "doc": "Data d'alta en format ISO 8601"}
  ]
}

Regles de l’exemple:

• namespace segueix el patró cat.gencat.ctti.{codi_app}.{domini}.
• Els camps opcionals s’expressen com a union ["null", "tipus"] amb "default": null — requisit per a compatibilitat BACKWARD.
• Proporcionar només la definició del schema, sense metadades de Schema Registry (subject, version, id).

5. Evolució i compatibilitat

• El versionat és automàtic: cada canvi registrat genera una nova versió.
• La política de compatibilitat per defecte és BACKWARD: els consumidors existents poden llegir missatges produïts amb el nou schema.
• Qualsevol canvi de política (FORWARD, FULL, NONE) requereix justificació i aprovació de l’Oficina EventHub.

Canvis compatibles BACKWARD (permesos sense aprovació especial):

• Afegir un camp opcional (amb default).
• Eliminar un camp que tenia default.

Canvis incompatibles (requereixen coordinació):

• Eliminar un camp sense default.
• Canviar el tipus d’un camp existent.
• Renombrar un camp.

Vegeu també

• Ús d’Esquemes
• Autoservei governat