Developing a Specification for Defining OpenTEAM Conventions

Last week, @gbathree, @clevinson and myself met to discuss steps forward for specifying OpenTEAM conventions, which will be based on the farmOS data model currently open as an RFC. There is already some language in that RFC, drafted by @mstenta, and I will leave it to @gbathree to flesh out more details here, along with a brief synopsis of the intent behind these conventions.

For now I'm just going to copy'n'paste what I wrote in an email to @clevinson and @gbathree:

The first and most crucial thing we need to have consensus on is how we describe/share/version/enforce these conventions; the conventions themselves can follow on that. Some good example schemas would be great, but that's in service of advancing the conversation around how.

Maybe we can start with some basic guidelines like:

• Conventions should be published in [repo url].
• It should have the following identifiers:
  • The entity and bundle it constrains (eg, "log--input")
  • The convention name or id
  • The convention version number
• It should define a set of constraints, each of which includes:
  • The field it constrains
  • The subschema that field must validate against (as JSON Schema, protobuf, or what have you)
  • Maybe some info on what orgs are using this convention?
• etc...

And then see where the conversation goes.

My next step will be to create a conventions directory in this repo, and within that I will create a README, which can perhaps serve as the primary document for the specification, as well as JSON Schema documents for some of the standard farmOS entities/bundles that these conventions will be based upon (maybe some example bundles themselves, too, in plain JSON). I'll leave it to @gbathree to add our first conventions to that directory. Over time, it's hoped that this will grow into a larger collection of conventions, which might make sense to spin-off into its own repo.