Fix the schemas for custom data

[afrittoli]

Changes

The current schema only includes string/base64 which is used for non JSON data.
customData may include either JSON (object) or base64 encoded content (string).

Fix one of the examples in the spec that was possibly misleading.

Signed-off-by: Andrea Frittoli andrea.frittoli@gmail.com

Submitter Checklist

As the author of this PR, please check off the items in this checklist:

• Has the primer doc been updated if a design decision is involved
• Have the JSON schemas been updated if the specification changed
• Has spec version and event versions been updated according to the versioning policy
• Meets the CDEvents contributor standards

[e-backmark-ericsson]

In Eiffel we have the following design rule:

Do not use variable key names: For purposes of automated validation, analysis and search, custom key names shall be avoided. Consequently, for custom key-value pairs { "key": "customKeyName", "value": "customValue" } shall be used instead of { "customKeyName": "customValue" }.

And our customData is defined like this in json schema:

      "customData": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "key": {
                "type": "string"
              },
              "value": {}
            },
            "required": [
              "key",
              "value"
            ],
            "additionalProperties": false
          }
        }

Do you think that should be a valid design rule for CDEvents as well?

It would then be something like this instead:

"customData": {
    "oneOf": [
        {
            "type": "string",
            "contentEncoding": "base64"
        },
        {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "key": {
                        "type": "string"
                    },
                    "value": {}
                },
                "required": [
                    "key",
                    "value"
                ],
                "additionalProperties": false
            }
        }
    ]
}

[afrittoli]

In Eiffel we have the following design rule:

Do not use variable key names: For purposes of automated validation, analysis and search, custom key names shall be avoided. Consequently, for custom key-value pairs { "key": "customKeyName", "value": "customValue" } shall be used instead of { "customKeyName": "customValue" }.

And our customData is defined like this in json schema:

      "customData": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "key": {
                "type": "string"
              },
              "value": {}
            },
            "required": [
              "key",
              "value"
            ],
            "additionalProperties": false
          }
        }

Do you think that should be a valid design rule for CDEvents as well?

It would then be something like this instead:

"customData": {
    "oneOf": [
        {
            "type": "string",
            "contentEncoding": "base64"
        },
        {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "key": {
                        "type": "string"
                    },
                    "value": {}
                },
                "required": [
                    "key",
                    "value"
                ],
                "additionalProperties": false
            }
        }
    ]
}

Thanks, @e-backmark-ericsson - yeah I can see how that could make sense - k8s has a somewhat similar policy about using arrays instead of maps in the API. We could then customData added from different sources, for instance in a case where a CDEvent is sent as an aggregation of multiple incoming events.

I'm not sure how that would map to the non-JSON content case. We would probably have to allow for some of the items in the array to carry base64 encoded data, with their own customDataContentType.

The scope of this PR is only to align the schema to what the spec says today, which will allow me to switch the SDK tests to use the schemas from the spec repo.

I would propose we treat your proposal as a follow-up item, would that be ok?

[e-backmark-ericsson]

Sure. My proposal could be considered for 0.2. Will you make a new issue about that, also mentioning the K8s policy, or do you want me to write an issue mostly based on the Eiffel way of defining custom data? I would like to see that new issue written before approving this PR, to make sure we don't forget about it.

[afrittoli]

Issue created: #81