Programmatic Derivation of CALM File Type

[Thels]

Feature Request

Description of Problem:

It's programmatically a bit of a pain to determine what sort of file you're validating/visualizing. Primarily as there is no indicator of what type of content you're processing without referring to schemas.

For example for the initial PR of the VSCode extension, this led to logic like if $schema contains /pattern/ then it's an instantization. This isn't ideal and can quickly fall apart if someone refers to a pattern without this handy indicator.

Programmatically determining the type of file being processed could simplify our validation/visualization flows from a CLI perspective too.

Potential Solutions:

• Introduce into the CALM schema the concept of a type - so the JSON files self-describe what they are.

"calm-type": ["pattern", "pattern-instantiation", ...others ]

• Taken from https://github.com/finos/architecture-as-code/discussions/482#discussioncomment-10972300 - go theJS route and introduce file naming convention for the different types.

Type	Suggested File Suffix
Pattern	.pattern.json
Instantization of Pattern	.instance.json
Control Requirement	.requirement.json
Control Evidence	.evidence.json
Layout	.layout.json
Flow	.flow.json

The benefit of having the file names describe what they are documenting would also allow for extra validation to occur - for example if I have a file called .instance.json I know it should have certain elements present.

Names are obviously a discussion point, just wanted to propose what the initial draft could be ( thanks @willosborne for helping with the list! )

[willosborne]

Biased, but I like the second approach more as we discussed during the office hours.

What do people think about the control requirement/evidence part? Do we even want an extension for these domains? I know this was discussed on the call

[yt-ms]

Could I suggest somehow making it less likely to have a collision on the extensions against other things using the same extensions (e.g. .flow.json)? Something like blah.calm-pattern.json seems like a lot of typing, but maybe a compromise is something like blah.cpattern.json or 'blah.c-pattern.json.

[LeighFinegold]

With the definition of models https://github.com/finos/architecture-as-code/pull/902, its possible we don't really need this anymore. Do we still want to promote this as a best practice?

[markscott-ms]

Tangentially discussed in #1453 where CLI options #1456 and dereferencing #1369 were talked about. It was agreed that calm template / calm docify should only dereference specific known property URLs (and potentially additionally configured ones via an advanced template).

I move to close this issue.

@LeighFinegold @Thels ?

[markscott-ms]

Something that identifies the type of a CALM document is also important for metrics - "how widely is CALM used".

When an architecture is generated from a pattern, there is nothing in that architecture JSON that says "I am CALM", only a $schema reference to something we expect to be a CALM pattern (which have a $schema referencing CALM).

Given that CALM documents might not be files (they could be stored in a database) I think something identifiable within the JSON object would avoid the JSON becoming disassociated from its document type.

For example calm generate could add the following metadata to a generated architecture file. It already adds the pattern's $id as the architecture's $schema.

{
   ...,
   "metadata" : {
       "calmType": "architecture",
       "calmSchema": "https://calm.finos.org/release/1.0-rc2/meta/calm.json"
   }
}

• calmType would be architecture, timeline, flow etc.
• calmSchema helps to indicate the version of CALM that the document relates to, in case the pattern is lost or inaccessible.

[ edit, see #1477 which expands on this to propose these properties all fall under a single reserved calm property ]