CloudEvents 1.0.2

What it isCopy Anchor Link

CloudEvents is a CNCF specification for describing an event in a common envelope. Version 1.0.2 defines the context attributes every event carries (specversion, id, source, type) and the optional ones (subject, time, datacontenttype, dataschema). The JSON event format serialises one event as application/cloudevents+json and a batch as a JSON array, application/cloudevents-batch+json. The distributed tracing extension adds W3C Trace Context traceparent and tracestate.

Why it matters for PermDockCopy Anchor Link

• One envelope for every event. Decision, approval, directory, membership, credential and support-session events leave the library in the same shape, so a queue, a webhook receiver or a log pipeline routes on type without reading data.
• Receivers already speak it. Event buses, Knative, Azure Event Grid and most queue consumers accept CloudEvents, so a DecisionSink needs no PermDock code on the far side.
• The data is typed and published. dataschema points at the JSON Schema of the event family, so a receiver in another language validates data without guessing.

How PermDock uses itCopy Anchor Link

toCloudEvent wraps one sink event. source is required and must be an absolute URI; the spec allows a URI-reference, PermDock does not, because a relative source cannot name the producer once the event leaves the app.

import type { DecisionSink } from "permdock";
import { CLOUDEVENTS_BATCH_CONTENT_TYPE, toCloudEvent } from "permdock";

const sink: DecisionSink = {
  async write(events) {
    await fetch("https://events.example.com/ingest", {
      method: "POST",
      headers: { "content-type": CLOUDEVENTS_BATCH_CONTENT_TYPE },
      body: JSON.stringify(
        events.map((event) =>
          toCloudEvent(event, { source: "https://app.example.com" }),
        ),
      ),
    });
  },
};

A receiver validates the batch with parseCloudEventBatch from permdock, or one event with parseCloudEvent (also re-exported by permdock/cloud, typed as PermDockCloudEvent). Both never throw, and both return null for an event outside the closed type list, a reserved type, a dataschema that does not match the data, a data shape that fails its schema, or a __proto__, constructor or prototype key. One invalid event rejects the whole batch.

{
  "specversion": "1.0",
  "type": "com.permdock.decision",
  "source": "https://app.example.com",
  "subject": "post.read",
  "id": "4f6c2a7e-1d0b-4c55-9b7e-2f8f8a1c9d10",
  "time": "2026-01-01T00:00:00.000Z",
  "datacontenttype": "application/json",
  "dataschema": "https://permdock.com/schemas/decision-event-v1.json",
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "data": {
    "type": "decision",
    "outcome": "granted",
    "permission": "post.read"
  }
}

data is abridged here; the full decision event is on wire formats.

TypesCopy Anchor Link

type is com.permdock.<family> or com.permdock.<family>.<operation>. cloudEventType(event) returns it for a sink event, and CLOUD_EVENT_TYPES lists every value.

RESERVED_CLOUD_EVENT_TYPES holds types named for a later release, which the parsers refuse until then. It is empty in this release.

Mapping tableCopy Anchor Link

Webhooks carry a batch signed with Standard Webhooks. The offline evidence export, signDecisionBatch, puts the same CloudEvents in the events claim of a vnd.permdock.evidence+jwt JWS (wire formats).

WhyCopy Anchor Link

com.permdock is the reverse-DNS prefix the specification recommends for type, under the domain PermDock publishes its schemas on. One type per operation lets a subscription filter on type alone, which is the attribute every broker indexes. The list is closed so a receiver can reject an event it does not understand instead of acting on a guess.

SourcesCopy Anchor Link

• CloudEvents 1.0.2 specification
• JSON event format 1.0.2
• Distributed tracing extension
• CloudEvents JSON Schema, vendored as tests/fixtures/standards/cloudevents-1.0.2.schema.json