Propose that metadata object property `calm` is reserved to CALM.

[markscott-ms]

CALM Schema Change Proposal

Target Schema:

core.json#/defs/metadata

Description of Change:

I propose that the metadata property calm is reserved for specification and use by the CALM tooling.

Use Cases:

For example:

{
  "$schema": "https://my.website/my-pattern.json",
  "nodes": [ ... ],
  ...
  "metadata" : {
    "calm": {
      "type": "architecture",
      "schema": "https://github.com/finos/architecture-as-code/blob/main/calm/release/1.0-rc2/meta/calm.json",
      "cliVersion": "0.7.11" 
    }
  }
}

• calm.type: the type of a CALM document: architecture, flow, timeline.
• calm.schema: the core CALM schema the document conforms to. In the case of an architecture generated from a pattern, this is the CALM schema the pattern conforms to. This is useful because the architecture's schema is the pattern itself, not the CALM schema.
• calm.cliVersion: the version of CLI tool that generated the architecture from a pattern.

Current Limitations:

Architectures conforming to the current schema, particularly those generated from a pattern lack any identification that they are CALM documents. #490 proposed some form of document typing, potentially via file name, but file name can be easily lost or non-existent if not persistent to a file system. The lack of a "CALM document type" frustrates metric gathering attempts.

By reserving calm within metadata we allow this and other properties to be added without accidental trampling on user metadata properties.

A calm.schema property assists in versioning the CALM schema used in an architecture document, and also determining that a document is CALM.

A calm.cliVersion property may aid in debugging issues.

Proposed Schema Changes:

The change is to add the description field to metadata. The type does not change.

    "metadata": {
      "description": "Any additional data associated with this CALM document. The property 'calm' is reserved for use by CALM tooling",
      "oneOf": [
        {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        {
          "type": "object",
          "additionalProperties": true
        }
      ]
    }

Backward Compatibility:

• Existing CALM documents remain valid.
• If a current architecture uses a calm property in metadata it could be at risk of being overwritten by tooling.

Validation Strategy:

• All existing tests should pass the addition of the description property in the schema.
• Where the CLI is extended to populate calm property tests will need added for both the object and array-of-object metadata forms.

Implementation Impact:

• calm generate will populate the metadata calm property.
• Existing examples will be extended to have the calm property in metadata.
• Documentation around metadata will need altered to refer to calm property.

Version Strategy:

• This is a minor change that could be added to 1.0 without a new version.

Implementation Checklist:

• [ ] Schema changes drafted and validated
• [ ] Example documents created that validate against the new schema
• [ ] Tests written to verify schema behavior
• [ ] Documentation updated to reflect changes
• [ ] Migration guide created (if applicable)
• [ ] Related schemas updated (if applicable)

Additional Context:

#490 #1476

[Thels]

I like this, but not cliVersion - not all CALM documents will be CLI generated. So that would need to be optional would it not?

Also maybe instead of schema we have schemaVersion - 1.0-rc2 for example?

[markscott-ms]

All metadata properties would be optional. I'm primarily proposing a standard place for 'CALM' ones to exist within metadata, with some potential examples.

I agree on potential change from schema to "schemaVersion": "release/1.0-rc2".

On cliVersion, I definitely don't see CLI being the only source. It could be CALMHub. Each of the CALM tools is free to define a property it may wish to look at / write. Maybe there is a single tool or authoringTool?

{
  "metadata" : {
    "calm": {
      "schemaVersion": "release/1.0-rc2",
      "type": "architecture",
      "authoringTool": "cli v0.7.11"
    }
  }
}

[Thels]

If they're all optional, I think that defeats the purpose as we then lack the critical information to know what sort of file we're dealing with?

The more I think about it, the schema version and type make processing in the future/visualization a lot easier if we mandate them.

[markscott-ms]

The current metadata type (core.json#/defs/metadata) is used at many places in the CALM schema. The metadata top level element is optional.

If we are mandating metadata/calm/schemaVersion and metadata/calm/type, then this becomes a breaking change rather than optional but recommended practice. We would also need to carefully mandate those properties within the top level metadata only. The recommendation would be aided by a CLI that will insert the values and may work better with documents that have the properties.

[rocketstack-matt]

I think as long as all our tools make the calm metadata mandatory that is probably an acceptable level of guarantee. Other users of the schema and proprietary tools could not enforce it's use but I don't think that would effect us.

We could always propose moving it to mandatory at a future major version if we found need to.

I'm in favor of this change.

[markscott-ms]

@jpgough-ms raised a point on #1493 that a top level calm key controlled in the CALM schema may be better than reserving a property 'by convention' in the metadata.

If agreed, I will close this issue and open a new formal CALM schema change proposal with it (for 1.x)

[jpgough-ms]

@markscott-ms this is my preference, and to add to this the calm block would be strongly typed. This will enable users/orgranisations to search by well defined calm level metadata produced by tools etc.