Data Proto Descriptions Are Inconsistent – CAL, Cloud Build, Firebase Auth

[grant]

Expected Behavior

Data proto messages have similar formats and simple descriptions.

Example (good):

https://github.com/googleapis/google-cloudevents/blob/master/proto/google/events/cloud/pubsub/v1/data.proto#L21-L22

// The data received in an event when a message is published to a topic.
message MessagePublishedData {

Actual Behavior

Different have different description formats.

• Specifically, CAL and Cloud Build protos have different descriptions than the others.
• nit: Firebase Auth description does not have a period unlike all other protos.

Example – Cloud Build

https://github.com/googleapis/google-cloudevents/blob/master/proto/google/events/cloud/cloudbuild/v1/data.proto#L24-L28

Expected

// Build event data.
message BuildEventData {

Actual

// Build event data
// Common build format for Google Cloud Platform API operations.
// Copied from
// https://github.com/googleapis/googleapis/blob/master/google/devtools/cloudbuild/v1/cloudbuild.proto.
message BuildEventData {

This is causing the schemas/doc generator to produce not ideal results:

Example Doc Gen Results

Cloud Audit Logs

const {toLogEntryData} = require('@google/events/cloud/audit/v1/LogEntryData');

/**
 * Generic log entry, used as a wrapper for Cloud Audit Logs in events.
 This is copied from
 https://github.com/googleapis/googleapis/blob/master/google/logging/v2/log_entry.proto
 and adapted appropriately.
 */
const data = {
  // ...
};

const jsExample = toLogEntryData(data);
console.log(jsExample);

Cloud Build

const {toBuildEventData} = require('@google/events/cloud/cloudbuild/v1/BuildEventData');

/**
 * Build event data
 Common build format for Google Cloud Platform API operations.
 Copied from
 https://github.com/googleapis/googleapis/blob/master/google/devtools/cloudbuild/v1/cloudbuild.proto.
 */
const data = {
  // ...
};

const jsExample = toBuildEventData(data);
console.log(jsExample);

Cloud Firestore

const {toDocumentEventData} = require('@google/events/cloud/firestore/v1/DocumentEventData');

/**
 * The data within all Firestore document events.
 */
const data = {
  // ...
};

const jsExample = toDocumentEventData(data);
console.log(jsExample);

Cloud Pub/Sub

const {toMessagePublishedData} = require('@google/events/cloud/pubsub/v1/MessagePublishedData');

/**
 * The data received in an event when a message is published to a topic.
 */
const data = {
  // ...
};

const jsExample = toMessagePublishedData(data);
console.log(jsExample);

Cloud Scheduler

const {toSchedulerJobData} = require('@google/events/cloud/scheduler/v1/SchedulerJobData');

/**
 * Scheduler job data.
 */
const data = {
  // ...
};

const jsExample = toSchedulerJobData(data);
console.log(jsExample);

Cloud Storage

const {toStorageObjectData} = require('@google/events/cloud/storage/v1/StorageObjectData');

/**
 * An object within Google Cloud Storage.
 */
const data = {
  // ...
};

const jsExample = toStorageObjectData(data);
console.log(jsExample);

Google Analytics for Firebase

const {toAnalyticsLogData} = require('@google/events/firebase/analytics/v1/AnalyticsLogData');

/**
 * The data within Firebase Analytics log events.
 */
const data = {
  // ...
};

const jsExample = toAnalyticsLogData(data);
console.log(jsExample);

Firebase Authentication

const {toAuthEventData} = require('@google/events/firebase/auth/v1/AuthEventData');

/**
 * The data within all Firebase Auth events
 */
const data = {
  // ...
};

const jsExample = toAuthEventData(data);
console.log(jsExample);

Firebase Realtime Database

const {toReferenceEventData} = require('@google/events/firebase/database/v1/ReferenceEventData');

/**
 * The data within all Firebase Real Time Database reference events.
 */
const data = {
  // ...
};

const jsExample = toReferenceEventData(data);
console.log(jsExample);

Firebase Remote Config

const {toRemoteConfigEventData} = require('@google/events/firebase/remoteconfig/v1/RemoteConfigEventData');

/**
 * The data within all Firebase Remote Config events.
 */
const data = {
  // ...
};

const jsExample = toRemoteConfigEventData(data);
console.log(jsExample);

[grant]

@jskeet, is it possible to simply modify the proto comments? Or are there upstream or concerns?

[jskeet]

Yes, it's fine to modify the proto comments. These were just what I put in to start with. Of course, when the protos use internal source control as a source of truth, we'll need to change them there.

I'm unlikely to get to this myself - are you happy to create a PR to make the changes you want?

[grant]

@jskeet I've created a PR: #120

Do note, that any changes to our protos affect many different parts/repos. I'll file changes to the JSON schemas and repos separately.