Empty source object in ArtC is misleading and can cause problems

[magnusbaeck]

Description

The backend.json example for ArtC has the following meta property:

"meta": {
  "type": "EiffelArtifactCreatedEvent",
  "version": "3.0.0",
  "time": 1234567890,
  "source": {
  },
  "id": "aaaaaaaa-bbbb-5ccc-8ddd-eeeeeeeeeee0"
}

The empty meta.source property is technically okay since its schema only contains optional properties. However, it's rather nonsensical and doesn't set a very good example.

It can also create a concrete problem if you deserialize this JSON string into a data structure using a JSON mapper and reserialize it back to JSON. When modeling Eiffel events with classes or structs you'll typically want to configure the mapping library to omit null/empty attributes, but then you can't use these example files to test that serialization.

Motivation

Our example files should be held to a high standard and not include gratuitous empty values even if the schema technically allows it. Also, we shouldn't make it harder than necessary to use the example files to test e.g. event SDKs.

Exemplification

I ran into this while writing tests for eiffelevents-sdk-go. I wanted a test to deserialize all examples into the SDK's Go structs and then back to JSON again and compare against the original example file. They should obviously match (if object key order is ignored), but they didn't since the struct field corresponding to meta.source was defined like this:

type ArtCV3Meta struct {
	// Mandatory fields
	ID      string `json:"id"`
	Time    int    `json:"time"`
	Type    string `json:"type"`
	Version string `json:"version"`

	// Optional fields
	Security ArtCV3MetaSecurity `json:"security,omitempty"`
	Source   ArtCV3MetaSource   `json:"source,omitempty"` // <--- HERE
	Tags     []string           `json:"tags,omitempty"`
}

Note how optional fields have an omitempty tag. Without it they'd be included in the JSON serialization even if they were empty, which would've been totally unnecessary.

Benefits

Decreased risk of confusion over an empty meta.source in an example, less hassle for downstream consumers of these examples.

Possible Drawbacks

None.