# Meta breakout 2022-01-20

https://github.com/eiffel-community/eiffel/issues/256
https://github.com/eiffel-community/eiffel/pull/257

## Open questions

- How can we validate meta.type and meta.version when they're defined in a shared EiffelMetaProperty definition?
- Could we fix this in the flattening process, i.e. flat files are always used for validation and the non-flat files are used for SDKs and documentation? If so, how does that fit with the [Documentation and schemas should be generated from a common source](https://github.com/eiffel-community/eiffel/issues/282) issue?
- If we flatten the schemas, should they be committed into the protocol repo along with the non-flat files (using a GitHub Action workflow to make sure they're in sync)?

## Open tasks

- Examine consequences for JSON validation code when meta is extracted to a separate file. Does it work without too much wrangling in setting up the validators?
- Write script for creating single-file schema files from multi-file schemas.

## Specifying meta fields separately yet validating meta.{type,version}
event.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
      "meta": {
          "allOf": [
              {
                  "type": "object",
                  "properties": {
                      "type": {
                          "type": "string",
                          "pattern": "EiffelTobiasTestarEvent"
                      },
                      "version": {
                          "type": "string",
                          "enum": [ "3.0.0" ],
                          "default": "3.0.0"
                      }
                  }
              },
              { "$ref": "file:///path/to/meta.json" }
          ]
      }
  }
}

meta.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "type": {
        "type": "string",
        "pattern": "^Eiffel[a-zA-Z]*Event$"
    },
    "version": {
        "type": "string",
        "pattern": "^[1-9][0-9]*\\.[0-9]+\\.[0-9]+"
    },
    "id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "source": {
      "type": "object",
      "properties": {
        "domainId": {
          "type": "string"
        },
        "host": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "serializer": {
          "type": "string",
          "pattern": "^pkg:"
        },
        "uri": {
          "type": "string"
        }
      },
      "additionalProperties": false
  }
}
}

validevent.json

{
    "meta": {
        "id": "548b0653-eb7d-480d-9561-5944588a9a5e",
        "type": "EiffelTobiasTestarEvent"
    }
}

## Summary

Tobias found a way to extract the meta object to a separate schema yet still be able to validate meta.{type,version} for each event (see above).

We discussed the possibility of extracting meta.{type,version} to the top level of the event. That would make it easier for consumers to figure out what kind of event they're dealing with but to avoid a massive backwards compatibility break we'd probably have to duplicate the data, resulting in something like this:

{
  "type": "EiffelArtifactCreatedEvent",
  "version": "3.0.0",
  "meta": {
    "type": "EiffelArtifactCreatedEvent",
    "version": "3.0.0",
    ...
  },
  "data": {
    ...
  },
  links: []
}

In the end we decided to pause this activity and instead pursue [Documentation and schemas should be generated from a common source](https://github.com/eiffel-community/eiffel/issues/282). Solving that issue could solve the problems we attempt to solve with the meta breakout (as well as address other things) but the opposite isn't true so completing the meta breakout at this point doesn't quite make sense.