RE: refining and augmenting entity definitions

[Chris Lauwers <lauwers@ubicity.com>]

Hi Calin, one comment about âassigning a fixed valueâ. I understand your concern, but this is already part of the TOSCA grammar: if you look at Section 3.6.14 Parameter Definition (which is an extension of Property Definition), it includes a âvalueâ keyword that âfixesâ the value of the defined property so it can no longer be changed by the orchestrator. (In fact, if an output mapping tries to assign a value to a property with a fixed value, then I believe that should be flagged as an error.)

 

In the example below, the statement

relationship_types:

  MyAttachesTo:

    derived_from: AttachesTo

    properties:

      location: /default_location

 

Is just shorthand syntax for:

 

relationship_types:

  MyAttachesTo:

    derived_from: AttachesTo

    properties:

      location:

        value: /default_location

The âmissing linkâ here, of course, is that the current grammar only uses Parameter Definitions for inputs, not for general-purpose properties. When we âformalizeâ the augmentation and refinement syntax in the spec, I would suggest we allow âParameter Definitionsâ for refinements. This addresses two issues:

-          It would obviously allow the âfixed valueâ scenario.

-          It also makes the âtypeâ keyword optional, which is something else we wanted to allow.

 

Chris

 

From: Calin Curescu [mailto:calin.curescu@ericsson.com]
Sent: Tuesday, December 04, 2018 8:16 AM
To: Katzman, Anatoly; Chris Lauwers; Arturo Martin De Nicolas; Priya T G (priya.g@netcracker.com); anatoly.katzman@att.com; NOSHPITZ, CLAUDE
Subject: Re: refining and augmenting entity definitions

 

Hi,

 

Regarding the proposal I fully agree. Please find some comments inline:

 

General Rules

The following refinement rules apply to all classes of entities (e.g. properties, capabilities, requirements, interfaces, etc.):

1.       If a type definition defines an entity of a specific class (e.g. a property, a capability, a requirement, an interface, etc.) with the same name as an entity of that same class defined in one of its base classes, then this definition is considered a refinement of the previously-defined entity (as opposed to a definition of an entirely new entity that shadows the definition in one of the base classes).

 

As Anatoly suggests, we could add the âaugment rulesâ, i.e. when we add new properties, attributes, interfaces, input parameters, capabilities, requirements, etc.

 

Adding an implementation to an already defined operation I would see it as refining.

 

2.       When specifying an entity refinement, the type keyname is optional:

-       If the type keyname is omitted, the refinement is assumed to specify the same type as the entity it refines. Other keynames in the refinement definition will be used to further specify the refinement (using the rules defined below)

-       If the type keyname is present, the type specified in the refinement must be compatible with the type specified in the original entity definition. Specifically, this means that either the type must be the same as the type specified in the original entity definition, or the type must be derived from the type specified in the original entity definition.

 

I agree that the type keyname should be optional:

         If it is not specified then I regard it as a one-time anonymous type that is derived from the base type (this is what all the added constraints in the node template assignment do anyway). If it is not needed why re-state it, in a derivation we do not write the untouched properties and attributes anyway. Economy is good.

         Now, sometimes we donât want to make the refinement on the spot, since we already derived type in the toolbag. Then the simplest is to just specify the (new) type. If we further want to refine it, then we continue with the refinement. Again, this is the least amount of re-work.

 

Entity Class-Specific Rules

In addition to applying a new type, other mechanisms can be used to further refine entity definitions in base types. These mechanisms are specific to each entity class.

Refining Property Definitions

TOSCA type entities can refine properties defined in one of their parent types by doing one or more of the following:

-          Adding a default value.

-          Adding (additional) constraints. The additional constraints must be narrower than the constraints specified in the original entity definition (i.e. it is not possible for property refinements to relax the constraints specified in the original entity definition).

-          Assigning a fixed value

-          Turning an optional property into a required property

-          Specifying entry_schema and/or key_schema for container types (i.e. lists and maps). If the original entity definition already includes an entry_schema or key_schema, then any such schemas specified in the refinement must derive from the equivalent schema in the original entity definition.

 

Regarding the fixed value, I really donât like the way itâs done in the example in section 10.1.4.:

relationship_types:

  MyAttachesTo:

    derived_from: AttachesTo

    properties:

      location: /default_location

 

It breaks the boundary between entity definition and assignment. Semantically, does it mean an overwriting of the default_value or a fixed_value? When we do an assignment, we set the value of one of the âcharacteristicsâ of that entity, namely the âvalueâ. Itâs like the grammar for âshort notationâ vs.  âextended notationâ.  So I think we need to have a âfixed_valueâ keyword anyway for cases where I am defining the type and assign a fixed value at the same time in the node base type. I.e. see the extra_location addition in the example below:

relationship_types:

  MyAttachesTo:

    derived_from: AttachesTo

    properties:

      location: /default_location

      extra_location:

         type: string

         fixed_value: â/extra_locationâ

 

Now, given that we have added a fixed value, what is the semantics of the âvalueâ assignment in the parameter definition?  It seems this is closer to the âdefault_valueâ than to âfixed_valueâ. It would be good if we can align the definitions of parameters, properties, and attributes.

 

Finally, we need to set the semantics of the fixed value regarding the reflected attribute of a property? Will I be able to change that during runtime?

 

BR,

/Calin

 

 

 

From: "Katzman, Anatoly" <anatoly.katzman@intl.att.com>
Date: Tuesday, 4 December 2018 at 15:45
To: Chris Lauwers <lauwers@ubicity.com>, Calin Curescu <calin.curescu@ericsson.com>, Arturo Martin De Nicolas <arturo.martin-de-nicolas@ericsson.com>, "Priya T G (priya.g@netcracker.com)" <priya.g@netcracker.com>, "anatoly.katzman@att.com" <anatoly.katzman@att.com>, "NOSHPITZ, CLAUDE" <cn5542@att.com>
Subject: RE: refining and augmenting entity definitions

 

1. I would love to see this kind of material all in one place rather than scattered all over the document. Maybe we need to have a chapter titled something like General Aspects, and this document could become the first section in it. It could also be helpful to add references to this section from other parts of the documents.
2. I also added some notes inline in the attached document.

 

BR,

Anatoly

 

From: Chris Lauwers <lauwers@ubicity.com>
Sent: Wednesday, November 28, 2018 1:01 AM
To: Calin Curescu <calin.curescu@ericsson.com>; arturo.martin-de-nicolas@ericsson.com; Priya T G (priya.g@netcracker.com) <priya.g@netcracker.com>; anatoly.katzman@att.com; NOSHPITZ, CLAUDE <cn5542@att.com>
Cc: Chris Lauwers <lauwers@ubicity.com>
Subject: refining and augmenting entity definitions

 

I put together the attached document to illustrate where (and how) the YAML spec uses examples of refining and augmenting entity definitions.  Iâd like to add a section with rules and examples to the spec, but itâs not immediately clear what the best place is for this information. Any ideas?

 

Thanks,

 

Chris