feat(dcs): add map type support for decorator command targets

[jonathan-casey]

Description

This change extends the Decorator Manager to support Map Types. A new optional property mapElement is added to the CommandTarget which allows users to specify the granularity of the intended target on a Map. The legal options of which are KEY, VALUE, or KEY_VALUE (both Key and Value).

Example 1:

{
    "$class" : "[email protected]",
    "name" : "web",
    "version": "1.0.0",
    "commands" : [
 
        {
            "$class" : "[email protected]",
            "type" : "UPSERT",
            "target" : {
                "$class" : "[email protected]",
                "namespace" : "[email protected]",
                "declaration" : "Dictionary",
                "mapElement": "KEY_VALUE"
            },
            "decorator" : {
                "$class" : "[email protected]",
                "name" : "Foo",
                "arguments" : []
            }
        }
    ]
}

In the above sample, the @Foo decorator will be added to both elements for the Map Declaration Dictionary

Example 2:

{
    "$class" : "[email protected]",
    "name" : "web",
    "version": "1.0.0",
    "commands" : [
 
        {
            "$class" : "[email protected]",
            "type" : "UPSERT",
            "target" : {
                "$class" : "[email protected]",
                "namespace" : "[email protected]",
                "declaration" : "Dictionary",
                "type" : "[email protected]",
            },
            "decorator" : {
                "$class" : "[email protected]",
                "name" : "Foo",
                "arguments" : []
            }
        }
    ]
}

In the above sample, the @Foo decorator will be added to the Dictionary Map Declaration, if it contains a StringMapKeyType.

Example 3:

{
    "$class" : "[email protected]",
    "name" : "web",
    "version": "1.0.0",
    "commands" : [
 
        {
            "$class" : "[email protected]",
            "type" : "UPSERT",
            "target" : {
                "$class" : "[email protected]",
                "namespace" : "[email protected]",
                "type" : "[email protected]",
            },
            "decorator" : {
                "$class" : "[email protected]",
                "name" : "Foo",
                "arguments" : []
            }
        }
    ]
}

In the above sample, the @Foo decorator will be added to all MapDeclarations found in the ModelFile, which contain a StringMapKeyType.

Author Checklist

• Ensure you provide a DCO sign-off for your commits using the --signoff option of git commit.
• Vital features and changes captured in unit and/or integration tests
• Commits messages follow AP format

[dselman]

Looks good. element sounds very generic ... Perhaps something more explicitly (map specific) would help in the model? mapElement ?

Alternatively we could co-opt property and properties for maps, but use special property names so we don't need a model change.

property: 'MAP_KEY'
property: 'MAP_VALUE'
properties: ['MAP_KEY', 'MAP_VALUE']

Thinking about this - we will also need to update the Vocabulary and VocabularyManager to check that terms can be retrieved for map key and value.

[jonathan-casey]

Looks good. element sounds very generic ... Perhaps something more explicitly (map specific) would help in the model? mapElement ?

Yes, I'm good with mapElement, although I like the elegance of element, I see your point. Given we don't typically reference anything else as an element I felt it sits nicely in the command.

Alternatively we could co-opt property and properties for maps, but use special property names so we don't need a model change.

property: 'MAP_KEY'
property: 'MAP_VALUE'
properties: ['MAP_KEY', 'MAP_VALUE']

I am less in favour of this suggestion . Strictly speaking, Maps do not contain properties. I think we should align the language of the command to that of the models AST, so as to provide consistency and avoid confusion.

Thinking about this - we will also need to update the Vocabulary and VocabularyManager to check that terms can be retrieved for map key and value.

Yes this came up in a team meeting, will be implemented as part of the ongoing Vocabulary efforts.

[dselman]

Very close! I think making the mapElement an enum will make the model self-describing and improve validation.

[jonathan-casey]

Very close! I think making the mapElement an enum will make the model self-describing and improve validation.

Agree using an Enum set makes sense now that we have DecoratorSet validation changes merged earlier today.

One thing to clarify - do you mean to suggest bumping the concerto version, or the namespace version to [email protected]? It makes sense to bump only the namespace as the changes are scoped to the decoratorcommands version.

[dselman]

Very close! I think making the mapElement an enum will make the model self-describing and improve validation.

Agree using an Enum set makes sense now that we have DecoratorSet validation changes merged earlier today.

One thing to clarify - do you mean to suggest bumping the concerto version, or the namespace version to [email protected]? It makes sense to bump only the namespace as the changes are scoped to the decoratorcommands version.

Validate has been present for a while - the change yesterday exposed it as a standalone method, rather than just doing it implicitly as part of decorateModels.

I meant to bump to [email protected].

[jonathan-casey]

@dselman given we haven't yet cut a release with the [email protected] changes , I suggest we stay with version 0.2.0 for now. This will solve the emergent migration story (in the short term) at DocuSign which surfaces should we move from v0.2.0. Longer term, we need to consider how we support versioning across DCS models, and the metamodel, in a scalable manner.

[dselman]

The problem remaining at v0.2.0 for DCS model will cause is that someone can define a DCS with mapElement and use it with concerto-core v3.13.0 and it will fail validation, even though the namespace version is correct.

I think downstream consumers need to migrate (on the fly or in batch) DCS docs to support what the version of concerto-core supports.

[dselman]

Looking good. A couple of minor changes requested.

[dselman]

Bravo!