cloudevents/required-attributes

Since 0.12.0 · In the rulesets: CloudEvents at error

This rule checks that every CloudEvents message declares and requires the four attributes every event has: id, source, specversion and type.

Rule details

A consumer that reads a CloudEvent relies on its required attributes: it routes on type, deduplicates on source and id, and checks specversion. A message that leaves one out, or declares it without requiring it, lets producers send events consumers can’t process.

In binary mode the attributes are headers, named with the prefix of the protocol binding of the channel’s servers (all servers when the channel lists none): ce-id over HTTP, ce_id over Kafka, cloudEvents:id (or cloudEvents_id) over AMQP and id over MQTT 5. When the servers’ protocols have no binary mode, the prefixes the headers use are taken. The rule reads the headers of the message’s traits and of the message as AsyncAPI applies them: the properties of all, and the required of the last one that has it. A trait applied later with headers of its own (trace headers, a correlation id) replaces the required of an earlier CloudEvents trait, which the rule then reports.

In structured mode the attributes are properties of the payload, allOf branches included.

Examples

Good.

asyncapi: 3.0.0
info:
  title: Shipments
  version: 1.0.0
servers:
  kafka:
    host: kafka.example.com:9092
    protocol: kafka
channels:
  shipments:
    address: shipments
    messages:
      created:
        headers:
          type: object
          required: [ce_specversion, ce_id, ce_source, ce_type]
          properties:
            ce_specversion:
              const: '1.0'
            ce_id:
              type: string
            ce_source:
              type: string
              format: uri-reference
            ce_type:
              type: string

Bad. The traced trait comes last, so its required replaces the CloudEvents one.

asyncapi: 3.0.0
info:
  title: Shipments
  version: 1.0.0
servers:
  kafka:
    host: kafka.example.com:9092
    protocol: kafka
channels:
  shipments:
    address: shipments
    messages:
      created:
        traits:
          - $ref: '#/components/messageTraits/cloudEvent'
          - $ref: '#/components/messageTraits/traced'
components:
  messageTraits:
    cloudEvent:
      headers:
        type: object
        required: [ce_specversion, ce_id, ce_source, ce_type]
        properties:
          ce_specversion:
            const: '1.0'
          ce_id:
            type: string
          ce_source:
            type: string
          ce_type:
            type: string
    traced:
      headers:
        type: object
        required: [traceparent]
        properties:
          traceparent:
            type: string

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.asyncapi has the details.

commands:
  lint:
    asyncapi:
      rules:
        cloudevents/required-attributes: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?