How to tell that you're working with a CALM file

[aidanm3341]

For the purposes of the VSCode Extension and other tooling, we need a way to know that the a given file is intended to be using CALM. We could look for a reference to the schema, but this doesn't always work given that a CALM instance isn't required to be based on a pattern, and therefore doesn't need to reference any external file at all that we could look for containing 'calm'.

I would propose that we have CALM files include it in their file name, e.g. api-gateway.calm.json. It would also be useful to specify a pattern this way, possibly like this - api-gateway.calm-pattern.json. This gives us a clear convention that we can check for in our tooling to know what we're working with, and in general makes it more obvious to users what kinds of files they have.

What do people think of this approach?

[rocketstack-matt]

Given CALM isn't a single schema, but a base meta schema and then a bunch of additional schemas including custom schemas that a user can provide themselves (patterns, control requirements) what does this actually solve? Aren't you still going to have to look inside the file to figure out what the schema is?

[Thels]

#484

Raised

[rocketstack-matt]

I'll raise an issue to review the pre-existing files checked into the repository to validate that they are suiting their purpose.

In terms of patterns/instantiations - I just want to confirm what the expected parsing behaviour is. I know this will need to change in the future for validating other items like controls/flows etc.

If the current file has a $schema contains /pattern/ then it's very likely that you're in an instantiation - with the pattern being that given value.

Otherwise if the $id contains /pattern/ you're likely parsing a pattern itself.

Then the version of CALM to validate it against ( instead of having this hard-coded anywhere in the code like it currently is ) we can simply go through what data we have available ( pattern / instantiation ) to find a reference to calm.json.

This may be hard to enforce, there is nothing preventing you using a URI that does not have the word pattern in; it's a nice convention but nothing more.

[Thels]

Completely agree, this is just for the initial implementation of the extension. We need to have an easier way to derive this context from the file we're processing.

Could we potentially introduce another element into the core schema? I may be massively over-simplifying the problem space though.

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

[willosborne]

This is the approach that Angular uses - .service.ts, .component.ts, etc - and they go further with .spec.ts for tests.
It's really clear, separates things out in the editor and is incredibly easy to work with from a tooling perspective without having to expand the spec.

I guess for CALM this would look like

• .calm.json for CALM architectures/instantiations - this is the base document
• .pattern.json for patterns
• .requirement.json or similar for others? .calm.requirement.json feels a bit excessive

[Thels]

I really like this idea, it would give a clear way to know what you expect your current file to contain without parsing the contents.

[aidanm3341]

Despite establishing that we probably could determine if we're working with CALM based on the file contents, I wonder if it's still worth introducing this just as a naming convention anyway.

Taking again the trader x example, only someone with experience with CALM could look at this and know that it's an instantiation and not a pattern. If we introduce a naming convention, at least someone who is only familiar with the concepts could look at this and understand what they have. I'm thinking more just from a user experience perspective now

[Thels]

But isn't that example incorrect like the one you referenced earlier in this discussion? Shouldn't the $schema refer to the pattern it was created from?

[aidanm3341]

in this case, it wasn't created from a pattern. The traderx example is just a standalone architecture

[Thels]

Ah okay fair point, from looking at the validation code in the CLI, it looks like assumptions were made that all instantiations refer to a pattern. Potentially we need to introduce the concept of validating stand-alone?

[aidanm3341]

yes agreed, this is a limitation of the current validator that we should address

[Thels]

Raised an issue to suggest addressing this.