About requirement refinement

[Roberto-Mameli-Eng]

Hi all,

the abstract profiles from the community have been recently updated and, in some of the node types defined in application and platform profiles now we have a requirement refinement.

For example, the ServerPlatform node type defined in the platform profile derives from Platform, which in turn derives from the Base node type defined in the base profile.

Base node defines a host requirement, which is refined in the ServerPlatform node type by adding a node definition, as shown below:

node_types:
  ServerPlatform:
    description: |
      Represents a single device. This could be a server with
      operating system software or firmware installed or a bare metal
      device on which operating system or hypervisor software needs to
      be installed.
    ...
    requirements:
      - host:
          node: VirtualizationPlatform

The refinement is allowed by the standard, but it is not clear whether the mandatory keynames used in requirement definition (i.e. capability and relationship, see sec. 8.4) must be repeated or not in the refinement (sec. 8.4.1). The text just states that:

"the type of the [capability|relationship] must be derived from (or the same as) the [capability|relationship] type in the requirement definition in the parent node type definition"

As a matter of fact, I think that today ubicity and puccini behaves differently when parsing the latest revisions of abstract profiles. I assume that ubicity accepts them without problems (@lauwers correct me if I'm wrong), while puccini originates a parsing error:

TOSCA Errors
../profiles/abstract/platform/profile.yaml
• node_types.ServerPlatform.requirements[0].host §41.9→13
  missing required key: "relationship"
• node_types.ServerPlatform.requirements[0].host §41.9→13
  missing required key: "capability"

I think that both behaviors are compatible with the content of sec. 8.4.1, since the text is slightly ambiguous. However, this is something that shall be agreed on and clarified explicitly in an errata doc or in a later version of the standard.

In the short term, I propose to modify the profiles by repeating in the refinement the relationship and capability already defined in the Base type, such as in the example below:

node_types:
  ServerPlatform:
    description: |
      Represents a single device. This could be a server with
      operating system software or firmware installed or a bare metal
      device on which operating system or hypervisor software needs to
      be installed.
    ...
    requirements:
      - host:
          capability: Host
          relationship: HostedOn
          node: VirtualizationPlatform

Any comment/observation from the community?

[pmjordan]

I see no reason why the keynames must be repeated in a derivation.

[lauwers]

The spec does address this issue, but only in the general derivation rules rather than in 8.4.1. Section 6.4.2 (Type Derivation) says:

For definitions that are inherited, a refinement of the inherited definition is not mandatory even for mandatory keynames (since it has been inherited). A definition refinement that is exactly the same as the definition in the parent type does not change in any way the inherited definition. While unnecessary, it is not wrong.

So the host requirement in ServerPlatform inherits capability: Host and relationship: HostedOn from Base, and the profiles are valid as written. Ubicity correctly accepts them.

That said, I agree that the discussion in 8.4.1 could be clearer. Section 8.2.1 already restates the rule for capability refinements ("the type keyname is no longer mandatory"), but 8.4.1 has no matching sentence. We should clarify that in future versions, for example as follows:

• In a requirement refinement, the capability and relationship keynames are no longer mandatory. If omitted, the values from the refined requirement definition are used.

Your workaround is harmless, but i would still rather keep the profiles as they are, since they follow the spec and more clearly indicate a refinement rather than a new definition.

[tliron]

I also wish this could be automatically derived, as it is unnecessarily verbose to include it.

Unfortunately the spec shows many keynames as "mandatory" in the table of keynames. This doesn't leave much room for implementors to decide what to do unless they want to break this "mandatory" specification. I wrestles with this and decided to stick to the spec.

I think we should relax this "mandatory" in future versions of TOSCA. E.g., the column can say "mandatory if not derived" or similar. There are several places in the spec where this makes sense.

[lauwers]

I think the general rule is extremely simple: in a derivation, none of the keywords are mandatory, under the assumption that they are extending an entity definition that was already valid in its own right, in which case all the mandatory keynames are already present in the entity definition that is being extended.

[tliron]

This is a good general rule to put forth, but I think it would still be nice to provide more details on keynames that could be potentially be derived, for additional clarity for implementors. Because there are indeed keynames that are always mandatory vs. those that in same cases are not.