Implement JSON Schema and Validator for C8 templates

[pinussilvestrus]

What should we do?

It should be possible to validate my C8 templates against a JSON schema, as we already do with C7 (cf. https://github.com/camunda/element-templates-json-schema + https://github.com/bpmn-io/element-templates-validator).

• Next to the basic rules, it should validate the following bindings (cf. Split up schema and add C8 JSON Schema camunda/element-templates-json-schema#41)
  • zeebe:taskDefinition
  • zeebe:taskHeader
  • zeebe:input
  • zeebe:output
  • groups
  • optional for inputs and outputs
• Prepare element-templates-json-schema to provide two packages
  • @camunda/element-templates-json-schema@0.7.0/resources/schema.json
  • @camunda/zeebe-element-templates-json-schema@0.1.0/resources/schema.json
• Extend element-templates-validator to also validate C8 templates
• Integrate the schema into cloud-element-templates provider
  • check for defined$schema, throw if empty or malformed
  • validate against @camunda/zeebe-element-templates-json-schema

What we should consider here on top

• How do we make C7 and C8 templates distinguishable? Via platform property? Via the existing $schema property?
• How many JSON schemas should we provide? A single one? One for each platform? Three with a "base" JSON schema and two extensions?
• Do we want to make our JSON schemas more composable / easier to maintain?
• Do we need another element-templates-validator or shall it be agnostic?

Miro board for conceptual work: https://miro.com/app/board/uXjVOPpXIIc=/

Why should we do it?

A proper JSON Schema validation helps a lot to build + consume valid templates.

Child of camunda/camunda-modeler#2640

[pinussilvestrus]

During investigations to create a C8 template schema out of our existing schema the smartest way possible, I experimented with json-schema-ref-parser to make our schemas more composable.

Rationale: The current JSON Schema is very huge (768 loc). If we want to prevent us from even extending this to apply C8 element templates, considering splitting the schema up in reasonable chunks could save us a lot of future efforts.

I'll probably conduct a lightning talk for this topic ⚡

WIP branch: https://github.com/camunda/element-templates-json-schema/tree/561-c8-schema

[pinussilvestrus]

Kickoff results (14th Feb)

Board: https://miro.com/app/board/uXjVOPpXIIc=/

• We are going for option 1B => have one base, two schemas
• We are going to have two packages, each for one schema, different versioning
  • "$schema": "https://unpkg.com/@camunda/element-templates-json-schema@0.7.0/resources/schema.json"
  • "$schema": "https://unpkg.com/@camunda/zeebe-element-templates-json-schema@0.1.0/resources/schema.json"
• The naming decision regarding C7/C8 vs. platform/cloud will be handled in general
• We call the schema for C8 "zeebe-element-templates-json-schema"
• We use the $schema property to distinguish
• C7 is the default (backward compatibility) => $schema is required to use C8 templates in the properties panel
• C8 element template will throw if $schema is not defined or malformed
• We extend @bpmn-io/element-templates-validator to validate zeebe templates

[nikku]

C8 element template will throw if $schema is not defined or malformed

Good to know :)

[pinussilvestrus]

We are going to have two packages, each for one schema, different versioning

Some reasoning about this point (since the discussion is not documented)

• Having both schemas the same version, our assumption was that it could be confusing that zeebe schema starts with v0.7.0
• We should avoid releasing a new schema version when there are no changes (which is okay tooling wise, but could cause confusion)
• Our is assumption is that the C8 schema will be subject to change more frequently, we shouldn't release C7 that often then (see above)
• At the end, it should be clearly documented what URL to use