1 Introduction

In the above grammars, the pseudo values that appear in angle brackets have the following meaning:

· operation_name: represents the required symbolic name of the operation as a string.

· operation_description: represents the optional description string for the corresponding operation_name.

· operation_implementation_definition: represents the optional specification of the operation’s implementation).

· property_definitions: represents the optional list of property definitions which the TOSCA orchestrator would make available (i.e., or pass) to the corresponding implementation artifact during its execution.

· property_assignments: represents the optional list of property assignments for passing parameters to Node or Relationship Template operations providing values for properties defined in their respective type definitions.

3.6.15.3 Additional requirements

· The default sub-classing behavior for implementations of operations SHALL be override. That is, implementation artifacts assigned in subclasses override any defined in its parent class.

· Template authors MAY provide property assignments on operation inputs on templates that do not necessarily have a property definition defined in its corresponding type.

· Implementation artifact file names (e.g., script filenames) may include file directory path names that are relative to the TOSCA service template file itself when packaged within a TOSCA Cloud Service ARchive (CSAR) file.

3.6.15.4 Examples

3.6.15.4.1 Single-line example

interfaces:

Standard:

start: scripts/start_server.sh

3.6.15.4.2 Multi-line example with shorthand implementation definitions

interfaces:

Configure:

pre_configure_source:

implementation:

primary: scripts/pre_configure_source.sh

dependencies:

- scripts/setup.sh

- binaries/library.rpm

- scripts/register.py

3.6.15.4.3 Multi-line example with extended implementation definitions

interfaces:

Configure:

pre_configure_source:

implementation:

primary:

file: scripts/pre_configure_source.sh

type: tosca.artifacts.Implementation.Bash

repository: my_service_catalog

dependencies: - file : scripts/setup.sh

type : tosca.artifacts.Implementation.Bash

Repository : my_service_catalog

3.6.16 Interface definition

An interface definition defines a named interface that can be associated with a Node or Relationship Type

3.6.16.1 Keynames

The following is the list of recognized keynames for a TOSCA interface definition:

Keyname

Required

Type

Description

inputs

list of

property definitions

The optional list of input property definitions available to all defined operations for interface definitions that are within TOSCA Node or Relationship Type definitions. This includes when interface definitions are included as part of a Requirement definition in a Node Type.

list of

property assignments

The optional list of input property assignments (i.e., parameters assignments) for interface definitions that are within TOSCA Node or Relationship Template definitions. This includes when interface definitions are referenced as part of a Requirement assignment in a Node Template.

3.6.16.2 Grammar

Interface definitions have the following grammar:

3.6.16.2.1 Extended notation for use in Type definitions

The following multi-line grammar may be used in Node or Relationship Type definitions:

<interface_definition_name>:

type: <interface_type_name>

inputs:

<operation_definitions>

3.6.16.2.2 Extended notation for use in Template definitions

The following multi-line grammar may be used in Node or Relationship Template definitions:

<interface_definition_name>:

inputs:

<event_filter_definition>

<operation_definitions>

In the above grammars, the pseudo values that appear in angle brackets have the following meaning:

· interface_definition_name: represents the required symbolic name of the interface as a string.

· interface_type_name: represents the required name of the Interface Type for the interface definition.

· property_definitions: represents the optional list of property definitions (i.e., parameters) which the TOSCA orchestrator would make available (i.e., or pass) to all defined operations.

- This means these properties and their values would be accessible to the implementation artifacts (e.g., scripts) associated to each operation during their execution.

· operation_definitions: represents the required name of one or more operation definitions.

3.6.17 Event Filter definition

An event filter definition defines criteria for selection of an attribute, for the purpose of monitoring it, within a TOSCA entity, or one its capabilities.

3.6.17.1 Keynames

The following is the list of recognized keynames for a TOSCA event filter definition:

Keyname	Required	Type	Description
node	yes	string	The required name of the node type or template that contains either the attribute to be monitored or contains the requirement that references the node that contains the attribute to be monitored.
requirement	no	string	The optional name of the requirement within the filter’s node that can be used to locate a referenced node that contains an attribute to monitor.
capability	no	string	The optional name of a capability within the filter’s node or within the node referenced by its requirement that contains the attribute to monitor.

3.6.17.2 Grammar

Event filter definitions have following grammar:

node: <node_type_name> | <node_template_name>

requirement: <requirement_name>

capability: <capability_name>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· node_type_name: represents the required name of the node type that would be used to select (filter) the node that contains the attribute to monitor or contains the requirement that references another node that contains the attribute to monitor.

· node_template_name: represents the required name of the node template that would be used to select (filter) the node that contains the attribute to monitor or contains the requirement that references another node that contains the attribute to monitor.

· requirement_name: represents the optional name of the requirement that would be used to select (filter) a referenced node that contains the attribute to monitor.

· capability_name: represents the optional name of a capability that would be used to select (filter) the attribute to monitor.

3.6.18 Trigger definition

A trigger definition defines the event, condition and action that is used to “trigger” a policy it is associated with.

3.6.18.1 Keynames

The following is the list of recognized keynames for a TOSCA trigger definition:

Keyname	Required	Type	Description
description	no	description	The optional description string for the named trigger.
event_type	no	string	The required name of the event type that activates the trigger’s action.
schedule	no	TimeInterval	The optional time interval during which the trigger is valid (i.e., during which the declared actions will be processed).
target_filter	no	event filter	The optional filter used to locate the attribute to monitor for the trigger’s defined condition. This filter helps locate the TOSCA entity (i.e., node or relationship) or further a specific capability of that entity that contains the attribute to monitor.
condition	no	List of condition clause definition	The optional condition which contains a condition clause definition specifying one or multiple attribute constraint that can be monitored. Note: this is optional since sometimes the event occurrence itself is enough to trigger the action.
action	yes	string or operation	The if of the workflow to be invoked when the event is triggered and the condition is met (i.e, evaluates to true). Or The required operation to invoke when the event is triggered and the condition is met (i.e., evaluates to true).

3.6.18.2 Additional keynames for the extended condition notation

Keyname	Required	Type	Description
constraint	no	List of condition clause definition	The optional condition which contains a condition clause definition specifying one or multiple attribute constraint that can be monitored. Note: this is optional since sometimes the event occurrence itself is enough to trigger the action.
period	no	scalar-unit.time	The optional period to use to evaluate for the condition.
evaluations	no	integer	The optional number of evaluations that must be performed over the period to assert the condition exists.
method	no	string	The optional statistical method name to use to perform the evaluation of the condition.

3.6.18.3 Grammar

Trigger definitions have the following grammars:

3.6.18.3.1 Short notation

<trigger_name>:

description: <trigger_description>

event: <event_type_name>

schedule: <time_interval_for_trigger>

target_filter:

condition:

<condition_clause_definition>

action:

<operation_definition>

3.6.18.3.2 Extended notation:

<trigger_name>:

description: <trigger_description>

event:

type: <event_type_name>

schedule: <time_interval_for_trigger>

target_filter:

<event_filter_definition>

condition:

constraint: <condition_clause_definition>

period: <scalar-unit.time> # e.g., 60 sec

evaluations: <integer> # e.g., 1

method: <string> # e.g., average

action:

<operation_definition>

In the above grammars, the pseudo values that appear in angle brackets have the following meaning:

· trigger_name: represents the required symbolic name of the trigger as a string.

· trigger_description: represents the optional description string for the corresponding trigger_name.

· event_type_name: represents the required name of the TOSCA Event Type that would be monitored on the identified resource (node).

· time_interval_for_trigger: represents the optional time interval that the trigger is valid for.

· event_filter_definition: represents the optional filter to use to locate the resource (node) or capability attribute to monitor.

· attribute_constraint_clause: represents the optional attribute constraint that would be used to test for a specific condition on the monitored resource.

· operation_definition: represents the required action to take if the event and (optionally) condition are met.

3.6.19 Workflow activity definition

A workflow activity defines an operation to be performed in a TOSCA workflow. Activities allows to:

· Delegate the workflow for a node expected to be provided by the orchestrator

· Set the state of a node

· Call an operation defined on a TOSCA interface of a node, relationship or group

· Inline another workflow defined in the topology (to allow reusability)

3.6.19.1 Keynames

The following is the list of recognized keynames for a TOSCA workflow activity definition. Note that while each of the key is not required, one and only one of them is required (mutualy exclusive).

Keyname	Required	Type	Description
delegate	no	string	The name of the delegate workflow. This activity requires the target to be provided by the orchestrator (no-op node or relationship)
set_state	no	string	Value of the node state.
call_operation	no	string	A string that defines the name of the interface and operation to be called on the node using the <interface_name>.<operation_name> notation.
inline	no	string	The name of a workflow to be inlined.

3.6.19.2 Grammar

Workflow activity definitions have one of the following grammars:

3.6.19.2.1 Delegate activity

- delegate: <delegate_workflow_name>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· delegate_workflow_name: represents the name of the workflow of the node provided by the TOSCA orchestrator.

3.6.19.2.2 Set state activity

- set_state: <new_node_state>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· new_node_state: represents the state that will be affected to the node once the activity is performed.

3.6.19.2.3 Call operation activity:

- call_operation: <interface_name>.<operation_name>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· interface_name: represents the name of the interface in which the operation to be called is defined.

· operation_name: represents the name of the operation of the interface that will be called during the workflow execution.

3.6.19.2.4 Inline activity

- inline: <workflow_name>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· workflow_name: represents the name of the workflow to inline.

3.6.19.3 Additional Requirements

· Keynames are mutually exclusive, i.e. an activity MUST define only one of delegate, set_state, call_operation or inline keyname.

3.6.19.4 Example

following represents a list of workflow activity definitions:

- delegate: deploy

- set_state: started

- call_operation: tosca.interfaces.node.lifecycle.Standard.start

- inline: my_workflow

3.6.20 Assertion definition

A workflow assertion is used to specify a single condition on a workflow filter definition. The assertion allows to assert the value of an attribute based on TOSCA constraints.

3.6.20.1 Keynames

The TOSCA workflow assertion definition has no keynames.

3.6.20.2 Grammar

Workflow assertion definitions have the following grammar:

<attribute_name>: <list_of_constraint_clauses>

In the above grammars, the pseudo values that appear in angle brackets have the following meaning:

· attribute_name: represents the name of an attribute defined on the assertion context entity (node instance, relationship instance, group instance) and from which value will be evaluated against the defined constraint clauses.

· list_of_constraint_clauses: represents the list of constraint clauses that will be used to validate the attribute assertion.

3.6.20.3 Example

Following represents a workflow assertion with a single equals constraint:

my_attribute: [{equal : my_value}]

Following represents a workflow assertion with mutliple constraints:

my_attribute:

- min_length: 8

- max_length : 10

3.6.21 Condition clause definition

A workflow condition clause definition is used to specify a condition that can be used within a workflow precondition or workflow filter.

3.6.21.1 Keynames

The following is the list of recognized keynames for a TOSCA workflow condition definition:

Keyname	Required	Type	Description
and	no	list of condition clause definition	An and clause allows to define sub-filter clause definitions that must all be evaluated truly so the and clause is considered as true.
or	no	list of condition clause definition	An or clause allows to define sub-filter clause definitions where one of them must all be evaluated truly so the or clause is considered as true.
assert	no	list of assertion definition	A list of filter assertions to be evaluated on entity attributes. Assert acts as a and clause, i.e. every defined filter assertion must be true so the assertion is considered as true.

Note : It is allowed to add assertion definition directly as keynames of the condition clause definition. An and clause is performed for all direct assertion definition.

3.6.21.2 Grammar

Workflow assertion definitions have the following grammars:

3.6.21.2.1 And clause

and: <list_of_condition_clause_definition>

In the above grammars, the pseudo values that appear in angle brackets have the following meaning:

· list_of_condition_clause_definition: represents the list of condition clauses. All condition clauses MUST be asserted to true so that the and clause is asserted to true.

3.6.21.2.2 Or clause

or: <list_of_condition_clause_definition>

In the above grammars, the pseudo values that appear in angle brackets have the following meaning:

· list_of_condition_clause_definition: represents the list of condition clauses. One of the condition clause have to be asserted to true so that the or clause is asserted to true.

3.6.21.2.3 Assert clause

assert: <list_of_assertion_definition>

In the above grammars, the pseudo values that appear in angle brackets have the following meaning:

· list_of_assertion_definition: represents the list of assertions. All assertions MUST be asserted to true so that the assert clause is asserted to true.

3.6.21.3 Direct assertion definition

<attribute_name>: <list_of_constraint_clauses>

In the above grammars, the pseudo values that appear in angle brackets have the following meaning:

· list_of_constraint_clauses: represents the list of constraint clauses that will be used to validate the attribute assertion.

3.6.21.4 Additional Requirement

· Keynames are mutually exclusive, i.e. a filter definition can define only one of and, or, or assert keyname.

3.6.21.5 Notes

· The TOSCA processor SHOULD perform assertion in the order of the list for every defined condition clause or assertion definition.

3.6.21.6 Example

Following represents a workflow condition clause with a single equals constraint:

condition:

- assert:

- my_attribute: [{equal: my_value}]

Following represents a workflow condition clause with a single equals constraints on two different attributes:

condition:

- assert:

- my_attribute: [{equal: my_value}]}

- my_other_attribute: [{equal: my_other_value}]}

Following represents a workflow condition clause with a or constraint on two different assertions:

condition:

- or:

- assert:

- my_attribute: [{equal: my_value}]}

- assert:

- my_other_attribute: [{equal: my_other_value}]}

Following represents multiple levels of condition clauses with direct assertion definition usage to build the following logic: one_attribute equal one_value AND (my_attribute equal my_value OR my_other_attribute equal my_other_value):

condition:

- one_attribute: [{equal: one_value }]

- or:

- assert:

- my_attribute: [{equal: my_value}]}

- assert:

- my_other_attribute: [{equal: my_other_value}]}

3.6.22 Workflow precondition definition

A workflow condition can be used as a filter or precondition to check if a workflow can be processed or not based on the state of the instances of a TOSCA topology deployment. When not met, the workflow will not be triggered.

3.6.22.1 Keynames

The following is the list of recognized keynames for a TOSCA workflow condition definition:

Keyname	Required	Type	Description
target	yes	string	The target of the precondition (this can be a node template name, a group name)
target_relationship	no	string	The optional name of a requirement of the target in case the precondition has to be processed on a relationship rather than a node or group. Note that this is applicable only if the target is a node.
condition	no	list of condition clause definitions	A list of workflow condition clause definitions. Assertion between elements of the condition are evaluated as an AND condition.

3.6.22.2 Grammar

Workflow precondition definitions have the following grammars:

- target: <target_name>

target_relationship: <target_requirement_name>

condition:

<list_of_condition_clause_definition>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· target_name: represents the name of a node template or group in the topology.

· target_requirement_name: represents the name of a requirement of the node template (in case target_name refers to a node template.

· list_of_condition_clause_definition: represents the list of condition clauses to be evaluated. The value of the resulting condition is evaluated as an AND clause between the different elements.

3.6.23 Workflow step definition

A workflow step allows to define one or multiple sequenced activities in a workflow and how they are connected to other steps in the workflow. They are the building blocks of a declarative workflow.

3.6.23.1 Keynames

The following is the list of recognized keynames for a TOSCA workflow step definition:

Keyname	Required	Type	Description
target	yes	string	The target of the step (this can be a node template name, a group name)
target_relationship	no	string	The optional name of a requirement of the target in case the step refers to a relationship rather than a node or group. Note that this is applicable only if the target is a node.
operation_host	no	string	The node on which operations should be executed (for TOSCA call_operation activities). This element is required only for relationships and groups target. If target is a relationships operation_host is required and valid_values are SOURCE or TARGET – referring to the relationship source or target node. If target is a group operation_host is optional. If not specified the operation will be triggered on every node of the group. If specified the valid_value is a node_type or the name of a node template.
filter	no	list of constraint clauses	Filter is a map of attribute name, list of constraint clause that allows to provide a filtering logic.
activities	yes	list of activity_definition	The list of sequential activities to be performed in this step.
on_success	no	list of string	The optional list of step names to be performed after this one has been completed with success (all activities has been correctly processed).
on_failure	no	list of string	The optional list of step names to be called after this one in case one of the step activity failed.

3.6.23.2 Grammar

Workflow step definitions have the following grammars:

steps:

<step_name>

target: <target_name>

target_relationship: <target_requirement_name>

operation_host: <operation_host_name>

filter:

- <list_of_condition_clause_definition>

activities:

- <list_of_activity_definition>

on_success:

- <target_step_name>

on_failure:

- <target_step_name>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· target_name: represents the name of a node template or group in the topology.

· target_requirement_name: represents the name of a requirement of the node template (in case target_name refers to a node template.

· operation_host: the node on which the operation should be executed

· <list_of_condition_clause_definition>: represents a list of condition clause definition.

· list_of_activity_definition: represents a list of activity definition

· target_step_name: represents the name of another step of the workflow.

3.7 Type-specific definitions

3.7.1 Entity Type Schema

An Entity Type is the common, base, polymorphic schema type which is extended by TOSCA base entity type schemas (e.g., Node Type, Relationship Type, Artifact Type, etc.) and serves to define once all the commonly shared keynames and their types. This is a “meta” type which is abstract and not directly instantiatable.

3.7.1.1 Keynames

The following is the list of recognized keynames for a TOSCA Entity Type definition:

Keyname	Required	Type	Constraints	Description
derived_from	no	string	‘None’ is the only allowed value	An optional parent Entity Type name the Entity Type derives from.
version	no	version	N/A	An optional version for the Entity Type definition.
metadata	no	map of string	N/A	Defines a section used to declare additional metadata information.
description	no	description	N/A	An optional description for the Entity Type.

3.7.1.2 Grammar

Entity Types have following grammar:

<entity_keyname>:

# The only allowed value is ‘None’

derived_from: None

version: <version_number>

metadata:

<metadata_map>

description: <interface_description>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· version_number: represents the optional TOSCA version number for the entity.

· entity_description: represents the optional description string for the entity.

· metadata_map: represents the optional map of string.

3.7.1.3 Additional Requirements

· The TOSCA Entity Type SHALL be the common base type used to derive all other top-level base TOSCA Types.

· The TOSCA Entity Type SHALL NOT be used to derive or create new base types apart from those defined in this specification or a profile of this specification.

3.7.2 Capability definition

A capability definition defines a named, typed set of data that can be associated with Node Type or Node Template to describe a transparent capability or feature of the software component the node describes.

3.7.2.1 Keynames

The following is the list of recognized keynames for a TOSCA capability definition:

Keyname	Required	Type	Constraints	Description
type	yes	string	N/A	The required name of the Capability Type the capability definition is based upon.
description	no	description	N/A	The optional description of the Capability definition.
properties	no	list of property definitions	N/A	An optional list of property definitions for the Capability definition.
attributes	no	list of attribute definitions	N/A	An optional list of attribute definitions for the Capability definition.
valid_source_types	no	string[]	N/A	An optional list of one or more valid names of Node Types that are supported as valid sources of any relationship established to the declared Capability Type.
occurrences	no	range of integer	implied default of [1,UNBOUNDED]	The optional minimum and maximum occurrences for the capability. By default, an exported Capability should allow at least one relationship to be formed with it with a maximum of UNBOUNDED relationships. Note: the keyword UNBOUNDED is also supported to represent any positive integer.

3.7.2.2 Grammar

Capability definitions have one of the following grammars:

3.7.2.2.1 Short notation

The following grammar may be used when only a list of capability definition names needs to be declared:

<capability_definition_name>: <capability_type>

3.7.2.2.2 Extended notation

The following multi-line grammar may be used when additional information on the capability definition is needed:

<capability_definition_name>:

type: <capability_type>

description: <capability_description>

properties:

attributes:

<requirement_definition_name>:

valid_source_types: [ <node type_names> ]

In the above grammars, the pseudo values that appear in angle brackets have the following meaning:

· capability_definition_name: represents the symbolic name of the capability as a string.

· capability_type: represents the required name of a capability type the capability definition is based upon.

· capability_description: represents the optional description of the capability definition.

· property_definitions: represents the optional list of property definitions for the capability definition.

· attribute_definitions: represents the optional list of attribute definitions for the capability definition.

· node_type_names: represents the optional list of one or more names of Node Types that the Capability definition supports as valid sources for a successful relationship to be established to itself.

3.7.2.3 Examples

The following examples show capability definitions in both simple and full forms:

3.7.2.3.1 Simple notation example

# Simple notation, no properties defined or augmented

some_capability: mytypes.mycapabilities.MyCapabilityTypeName

3.7.2.3.2 Full notation example

# Full notation, augmenting properties of the referenced capability type

some_capability:

type: mytypes.mycapabilities.MyCapabilityTypeName

properties:

limit:

type: integer

default: 100

3.7.2.4 Additional requirements

· Any Node Type (names) provides as values for the valid_source_types keyname SHALL be type-compatible (i.e., derived from the same parent Node Type) with any Node Types defined using the same keyname in the parent Capability Type.

· Capability symbolic names SHALL be unique; it is an error if a capability name is found to occur more than once.

3.7.2.5 Notes

The Capability Type, in this example MyCapabilityTypeName, would be defined elsewhere and have an integer property named limit.
This definition directly maps to the CapabilitiesDefinition of the Node Type entity as defined in the TOSCA v1.0 specification.

3.7.3 Requirement definition

The Requirement definition describes a named requirement (dependencies) of a TOSCA Node Type or Node template which needs to be fulfilled by a matching Capability definition declared by another TOSCA modelable entity. The requirement definition may itself include the specific name of the fulfilling entity (explicitly) or provide an abstract type, along with additional filtering characteristics, that a TOSCA orchestrator can use to fulfill the capability at runtime (implicitly).

3.7.3.1 Keynames

The following is the list of recognized keynames for a TOSCA requirement definition:

Keyname	Required	Type	Constraints	Description
capability	yes	string	N/A	The required reserved keyname used that can be used to provide the name of a valid Capability Type that can fulfill the requirement.
node	no	string	N/A	The optional reserved keyname used to provide the name of a valid Node Type that contains the capability definition that can be used to fulfill the requirement.
relationship	no	string	N/A	The optional reserved keyname used to provide the name of a valid Relationship Type to construct when fulfilling the requirement.
occurrences	no	range of integer	implied default of [1,1]	The optional minimum and maximum occurrences for the requirement. Note: the keyword UNBOUNDED is also supported to represent any positive integer.

3.7.3.1.1 Additional Keynames for multi-line relationship grammar

The Requirement definition contains the Relationship Type information needed by TOSCA Orchestrators to construct relationships to other TOSCA nodes with matching capabilities; however, it is sometimes recognized that additional properties may need to be passed to the relationship (perhaps for configuration). In these cases, additional grammar is provided so that the Node Type may declare additional Property definitions to be used as inputs to the Relationship Type’s declared interfaces (or specific operations of those interfaces).

Keyname	Required	Type	Constraints	Description
type	yes	string	N/A	The optional reserved keyname used to provide the name of the Relationship Type for the requirement definition’s relationship keyname.
interfaces	no	list of interface definitions	N/A	The optional reserved keyname used to reference declared (named) interface definitions of the corresponding Relationship Type in order to declare additional Property definitions for these interfaces or operations of these interfaces.

3.7.3.2 Grammar

Requirement definitions have one of the following grammars:

3.7.3.2.1 Simple grammar (Capability Type only)

<requirement_definition_name>: <capability_type_name>

3.7.3.2.2 Extended grammar (with Node and Relationship Types)

capability: <capability_type_name>

node: <node_type_name>

relationship: <relationship_type_name>

occurrences: [ <min_occurrences>, <max_occurrences> ]

3.7.3.2.3 Extended grammar for declaring Property Definitions on the relationship’s Interfaces

The following additional multi-line grammar is provided for the relationship keyname in order to declare new Property definitions for inputs of known Interface definitions of the declared Relationship Type.

<requirement_definition_name>:

# Other keynames omitted for brevity

relationship:

type: <relationship_type_name>

interfaces:

In the above grammars, the pseudo values that appear in angle brackets have the following meaning:

· requirement_definition_name: represents the required symbolic name of the requirement definition as a string.

· capability_type_name: represents the required name of a Capability type that can be used to fulfill the requirement.

· node_type_name: represents the optional name of a TOSCA Node Type that contains the Capability Type definition the requirement can be fulfilled by.

· relationship_type_name: represents the optional name of a Relationship Type to be used to construct a relationship between this requirement definition (i.e., in the source node) to a matching capability definition (in a target node).

· min_occurrences, max_occurrences: represents the optional minimum and maximum occurrences of the requirement (i.e., its cardinality).

· interface_definitions: represents one or more already declared interface definitions in the Relationship Type (as declared on the type keyname) allowing for the declaration of new Property definition for these interfaces or for specific Operation definitions of these interfaces.

3.7.3.3 Additional Requirements

· Requirement symbolic names SHALL be unique; it is an error if a requirement name is found to occur more than once.

· If the occurrences keyname is not present, then the occurrence of the requirement SHALL be one and only one; that is a default declaration as follows would be assumed:

o occurrences: [1,1]

3.7.3.4 Notes

· This element directly maps to the RequirementsDefinition of the Node Type entity as defined in the TOSCA v1.0 specification.

· The requirement symbolic name is used for identification of the requirement definition only and not relied upon for establishing any relationships in the topology.

3.7.3.5 Requirement Type definition is a tuple

A requirement definition allows type designers to govern which types are allowed (valid) for fulfillment using three levels of specificity with only the Capability Type being required.

1. Node Type (optional)

2. Relationship Type (optional)

3. Capability Type (required)

The first level allows selection, as shown in both the simple or complex grammar, simply providing the node’s type using the node keyname. The second level allows specification of the relationship type to use when connecting the requirement to the capability using the relationship keyname. Finally, the specific named capability type on the target node is provided using the capability keyname.

3.7.3.5.1 Property filter

In addition to the node, relationship and capability types, a filter, with the keyname node_filter, may be provided to constrain the allowed set of potential target nodes based upon their properties and their capabilities’ properties. This allows TOSCA orchestrators to help find the “best fit” when selecting among multiple potential target nodes for the expressed requirements.

3.7.4 Artifact Type

An Artifact Type is a reusable entity that defines the type of one or more files that are used to define implementation or deployment artifacts that are referenced by nodes or relationships on their operations.

3.7.4.1 Keynames

The Artifact Type is a TOSCA Entity and has the common keynames listed in section 3.7.1 TOSCA Entity Schema.

In addition, the Artifact Type has the following recognized keynames:

Keyname	Required	Type	Description
mime_type	no	string	The required mime type property for the Artifact Type.
file_ext	no	string[]	The required file extension property for the Artifact Type.
properties	no	list of property definitions	An optional list of property definitions for the Artifact Type.

3.7.4.2 Grammar

Artifact Types have following grammar:

<artifact_type_name>:

derived_from: <parent_artifact_type_name>

version: <version_number>

metadata:

description: <artifact_description>

mime_type: <mime_type_string>

file_ext: [ <file_extensions> ]

properties:

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· artifact_type_name: represents the name of the Artifact Type being declared as a string.

· parent_artifact_type_name: represents the name of the Artifact Type this Artifact Type definition derives from (i.e., its “parent” type).

· version_number: represents the optional TOSCA version number for the Artifact Type.

· artifact_description: represents the optional description string for the Artifact Type.

· mime_type_string: represents the optional Multipurpose Internet Mail Extensions (MIME) standard string value that describes the file contents for this type of Artifact Type as a string.

· file_extensions: represents the optional list of one or more recognized file extensions for this type of artifact type as strings.

· property_definitions: represents the optional list of property definitions for the artifact type.

3.7.4.3 Examples

my_artifact_type:

description: Java Archive artifact type

derived_from: tosca.artifact.Root

  mime_type: application/java-archive

file_ext: [ jar ]

3.7.4.4 Notes

· The ‘mime_type’ keyname is meant to have values that are Apache mime types such as those defined here: http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types

3.7.5 Interface Type

An Interface Type is a reusable entity that describes a set of operations that can be used to interact with or manage a node or relationship in a TOSCA topology.

3.7.5.1 Keynames

The Interface Type is a TOSCA Entity and has the common keynames listed in section 3.7.1 TOSCA Entity Schema.

In addition, the Interface Type has the following recognized keynames:

Keyname

Required

Type

Description

inputs

list of

property definitions

The optional list of input parameter definitions.

3.7.5.2 Grammar

Interface Types have following grammar:

<interface_type_name>:

derived_from: <parent_interface_type_name>

version: <version_number>

metadata:

description: <interface_description>

inputs:

<operation_definitions>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· interface_type_name: represents the required name of the interface as a string.

· parent_interface_type_name: represents the name of the Interface Type this Interface Type definition derives from (i.e., its “parent” type).

· version_number: represents the optional TOSCA version number for the Interface Type.

· interface_description: represents the optional description string for the Interface Type.

· property_definitions: represents the optional list of property definitions (i.e., parameters) which the TOSCA orchestrator would make available (i.e., or pass) to all implementation artifacts for operations declared on the interface during their execution.

· operation_definitions: represents the required list of one or more operation definitions.

3.7.5.3 Example

The following example shows a custom interface used to define multiple configure operations.

mycompany.mytypes.myinterfaces.MyConfigure:

derived_from: tosca.interfaces.relationship.Root

description: My custom configure Interface Type

inputs:

mode:

type: string

pre_configure_service:

description: pre-configure operation for my service

post_configure_service:

description: post-configure operation for my service

3.7.5.4 Additional Requirements

· Interface Types MUST NOT include any implementations for defined operations; that is, the implementation keyname is invalid.

· The inputs keyname is reserved and SHALL NOT be used for an operation name.

3.7.6 Data Type

A Data Type definition defines the schema for new named datatypes in TOSCA.

3.7.6.1 Keynames

The Data Type is a TOSCA Entity and has the common keynames listed in section 3.7.1 TOSCA Entity Schema.

In addition, the Data Type has the following recognized keynames:

Keyname

Required

Type

Description

constraints

list of

constraint clauses

The optional list of sequenced constraint clauses for the Data Type.

properties

list of

property definitions

The optional list property definitions that comprise the schema for a complex Data Type in TOSCA.

3.7.6.2 Grammar

Data Types have the following grammar:

<data_type_name>:

derived_from: <existing_type_name>

version: <version_number>

metadata:

description: <datatype_description>

constraints:

- <type_constraints>

properties:

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· data_type_name: represents the required symbolic name of the Data Type as a string.

· version_number: represents the optional TOSCA version number for the Data Type.

· datatype_description: represents the optional description for the Data Type.

· existing_type_name: represents the optional name of a valid TOSCA type this new Data Type would derive from.

· type_constraints: represents the optional sequenced list of one or more type-compatible constraint clauses that restrict the Data Type.

· property_definitions: represents the optional list of one or more property definitions that provide the schema for the Data Type.

3.7.6.3 Additional Requirements

· A valid datatype definition MUST have either a valid derived_from declaration or at least one valid property definition.

· Any constraint clauses SHALL be type-compatible with the type declared by the derived_from keyname.

· If a properties keyname is provided, it SHALL contain one or more valid property definitions.

3.7.6.4 Examples

The following example represents a Data Type definition based upon an existing string type:

3.7.6.4.1 Defining a complex datatype

# define a new complex datatype

mytypes.phonenumber:

description: my phone number datatype

properties:

countrycode:

type: integer

areacode:

type: integer

number:

type: integer

3.7.6.4.2 Defining a datatype derived from an existing datatype

# define a new datatype that derives from existing type and extends it

mytypes.phonenumber.extended:

derived_from: mytypes.phonenumber

description: custom phone number type that extends the basic phonenumber type

properties:

phone_description:

type: string

constraints:

- max_length: 128

3.7.7 Capability Type

A Capability Type is a reusable entity that describes a kind of capability that a Node Type can declare to expose. Requirements (implicit or explicit) that are declared as part of one node can be matched to (i.e., fulfilled by) the Capabilities declared by another node.

3.7.7.1 Keynames

The Capability Type is a TOSCA Entity and has the common keynames listed in section 3.7.1 TOSCA Entity Schema.

In addition, the Capability Type has the following recognized keynames:

Keyname	Required	Type	Description
properties	no	list of property definitions	An optional list of property definitions for the Capability Type.
attributes	no	list of attribute definitions	An optional list of attribute definitions for the Capability Type.
valid_source_types	no	string[]	An optional list of one or more valid names of Node Types that are supported as valid sources of any relationship established to the declared Capability Type.

3.7.7.2 Grammar

Capability Types have following grammar:

<capability_type_name>:

derived_from: <parent_capability_type_name>

version: <version_number>

description: <capability_description>

properties:

attributes:

valid_source_types: [ <node type_names> ]

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· capability_type_name: represents the required name of the Capability Type being declared as a string.

· parent_capability_type_name: represents the name of the Capability Type this Capability Type definition derives from (i.e., its “parent” type).

· version_number: represents the optional TOSCA version number for the Capability Type.

· capability_description: represents the optional description string for the corresponding capability_type_name.

· property_definitions: represents an optional list of property definitions that the Capability type exports.

· attribute_definitions: represents the optional list of attribute definitions for the Capability Type.

· node_type_names: represents the optional list of one or more names of Node Types that the Capability Type supports as valid sources for a successful relationship to be established to itself.

3.7.7.3 Example

mycompany.mytypes.myapplication.MyFeature:

derived_from: tosca.capabilities.Root

description: a custom feature of my company’s application

properties:

my_feature_setting:

type: string

my_feature_value:

type: integer

3.7.8 Requirement Type

A Requirement Type is a reusable entity that describes a kind of requirement that a Node Type can declare to expose. The TOSCA Simple Profile seeks to simplify the need for declaring specific Requirement Types from nodes and instead rely upon nodes declaring their features sets using TOSCA Capability Types along with a named Feature notation.

Currently, there are no use cases in this TOSCA Simple Profile in YAML specification that utilize an independently defined Requirement Type. This is a desired effect as part of the simplification of the TOSCA v1.0 specification.

3.7.9 Node Type

A Node Type is a reusable entity that defines the type of one or more Node Templates. As such, a Node Type defines the structure of observable properties via a Properties Definition, the Requirements and Capabilities of the node as well as its supported interfaces.

3.7.9.1 Keynames

The Node Type is a TOSCA Entity and has the common keynames listed in section 3.7.1 TOSCA Entity Schema.

In addition, the Node Type has the following recognized keynames:

Keyname	Required	Type	Description
attributes	no	list of attribute definitions	An optional list of attribute definitions for the Node Type.
properties	no	list of property definitions	An optional list of property definitions for the Node Type.
requirements	no	list of requirement definitions	An optional sequenced list of requirement definitions for the Node Type.
capabilities	no	list of capability definitions	An optional list of capability definitions for the Node Type.
interfaces	no	list of interface definitions	An optional list of interface definitions supported by the Node Type.
artifacts	no	list of artifact definitions	An optional list of named artifact definitions for the Node Type.

3.7.9.2 Grammar

Node Types have following grammar:

<node_type_name>:

derived_from: <parent_node_type_name>

version: <version_number>

metadata:

description: <node_type_description>

attributes:

properties:

requirements:

- <requirement_definitions>

capabilities:

<capability_definitions>

interfaces:

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

artifacts:

<artifact_definitions>

· node_type_name: represents the required symbolic name of the Node Type being declared.

· parent_node_type_name: represents the name (string) of the Node Type this Node Type definition derives from (i.e., its “parent” type).

· version_number: represents the optional TOSCA version number for the Node Type.

· node_type_description: represents the optional description string for the corresponding node_type_name.

· property_definitions: represents the optional list of property definitions for the Node Type.

· attribute_definitions: represents the optional list of attribute definitions for the Node Type.

· requirement_definitions: represents the optional sequenced list of requirement definitions for the Node Type.

· capability_definitions: represents the optional list of capability definitions for the Node Type.

· interface_definitions: represents the optional list of one or more interface definitions supported by the Node Type.

· artifact_definitions: represents the optional list of artifact definitions for the Node Type.

3.7.9.3 Additional Requirements

· Requirements are intentionally expressed as a sequenced list of TOSCA Requirement definitions which SHOULD be resolved (processed) in sequence order by TOSCA Orchestrators. .

3.7.9.4 Best Practices

· It is recommended that all Node Types SHOULD derive directly (as a parent) or indirectly (as an ancestor) of the TOSCA Root Node Type (i.e., tosca.nodes.Root) to promote compatibility and portability. However, it is permitted to author Node Types that do not do so.

· TOSCA Orchestrators, having a full view of the complete application topology template and its resultant dependency graph of nodes and relationships, MAY prioritize how they instantiate the nodes and relationships for the application (perhaps in parallel where possible) to achieve the greatest efficiency

3.7.9.5 Example

my_company.my_types.my_app_node_type:

derived_from: tosca.nodes.SoftwareComponent

description: My company’s custom applicaton

properties:

my_app_password:

type: string

description: application password

constraints:

- min_length: 6

- max_length: 10

attributes:

my_app_port:

type: integer

description: application port number

requirements:

- some_database:

capability: EndPoint.Database

node: Database

relationship: ConnectsTo

3.7.10 Relationship Type

A Relationship Type is a reusable entity that defines the type of one or more relationships between Node Types or Node Templates.

3.7.10.1 Keynames

The Relationship Type is a TOSCA Entity and has the common keynames listed in section 3.7.1 TOSCA Entity Schema.

In addition, the Relationship Type has the following recognized keynames:

Keyname	Required	Definition/Type	Description
properties	no	list of property definitions	An optional list of property definitions for the Relationship Type.
attributes	no	list of attribute definitions	An optional list of attribute definitions for the Relationship Type.
interfaces	no	list of interface definitions	An optional list of interface definitions interfaces supported by the Relationship Type.
valid_target_types	no	string[]	An optional list of one or more names of Capability Types that are valid targets for this relationship.

3.7.10.2 Grammar

Relationship Types have following grammar:

<relationship_type_name>:

derived_from: <parent_relationship_type_name>

version: <version_number>

metadata:

description: <relationship_description>

properties:

attributes:

interfaces:

valid_target_types: [ <capability_type_names> ]

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· relationship_type_name: represents the required symbolic name of the Relationship Type being declared as a string.

· parent_relationship_type_name: represents the name (string) of the Relationship Type this Relationship Type definition derives from (i.e., its “parent” type).

· relationship_description: represents the optional description string for the corresponding relationship_type_name.

· version_number: represents the optional TOSCA version number for the Relationship Type.

· property_definitions: represents the optional list of property definitions for the Relationship Type.

· attribute_definitions: represents the optional list of attribute definitions for the Relationship Type.

· interface_definitions: represents the optional list of one or more names of valid interface definitions supported by the Relationship Type.

· capability_type_names: represents one or more names of valid target types for the relationship (i.e., Capability Types).

3.7.10.3 Best Practices

· For TOSCA application portability, it is recommended that designers use the normative Relationship types defined in this specification where possible and derive from them for customization purposes.

· The TOSCA Root Relationship Type (tosca.relationships.Root) SHOULD be used to derive new types where possible when defining new relationships types. This assures that its normative configuration interface (tosca.interfaces.relationship.Configure) can be used in a deterministic way by TOSCA orchestrators.

3.7.10.4 Examples

mycompanytypes.myrelationships.AppDependency:

derived_from: tosca.relationships.DependsOn

valid_target_types: [ mycompanytypes.mycapabilities.SomeAppCapability ]

3.7.11 Group Type

A Group Type defines logical grouping types for nodes, typically for different management purposes. Groups can effectively be viewed as logical nodes that are not part of the physical deployment topology of an application, yet can have capabilities and the ability to attach policies and interfaces that can be applied (depending on the group type) to its member nodes.

Conceptually, group definitions allow the creation of logical “membership” relationships to nodes in a service template that are not a part of the application’s explicit requirement dependencies in the topology template (i.e. those required to actually get the application deployed and running). Instead, such logical membership allows for the introduction of things such as group management and uniform application of policies (i.e., requirements that are also not bound to the application itself) to the group’s members.

3.7.11.1 Keynames

The Group Type is a TOSCA Entity and has the common keynames listed in section 3.7.1 TOSCA Entity Schema.

In addition, the Group Type has the following recognized keynames:

Keyname	Required	Type	Description
attributes	no	list of attribute definitions	An optional list of attribute definitions for the Group Type.
properties	no	list of property definitions	An optional list of property definitions for the Group Type.
members	no	string[]	An optional list of one or more names of Node Types that are valid (allowed) as members of the Group Type. Note: This can be viewed by TOSCA Orchestrators as an implied relationship from the listed members nodes to the group, but one that does not have operational lifecycle considerations. For example, if we were to name this as an explicit Relationship Type we might call this “MemberOf” (group).
requirements	no	list of requirement definitions	An optional sequenced list of requirement definitions for the Group Type.
capabilities	no	list of capability definitions	An optional list of capability definitions for the Group Type.
interfaces	no	list of interface definitions	An optional list of interface definitions supported by the Group Type.

3.7.11.2 Grammar

Group Types have one the following grammars:

<group_type_name>:

derived_from: <parent_group_type_name>

version: <version_number>

metadata:

description: <group_description>

properties:

members: [ <list_of_valid_member_types> ]

requirements:

- <requirement_definitions>

capabilities:

<capability_definitions>

interfaces:

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· group_type_name: represents the required symbolic name of the Group Type being declared as a string.

· parent_group_type_name: represents the name (string) of the Group Type this Group Type definition derives from (i.e., its “parent” type).

· version_number: represents the optional TOSCA version number for the Group Type.

· group_description: represents the optional description string for the corresponding group_type_name.

· property_definitions: represents the optional list of property definitions for the Group Type.

· list_of_valid_member_types: represents the optional list of TOSCA types (e.g.,., Node, Capability or even other Group Types) that are valid member types for being added to (i.e., members of) the Group Type.

· interface_definitions: represents the optional list of one or more interface definitions supported by the Group Type.

3.7.11.3 Additional Requirements

· Group definitions SHOULD NOT be used to define or redefine relationships (dependencies) between nodes that can be expressed using normative TOSCA Relationships (e.g., HostedOn, ConnectsTo, etc.) within a TOSCA topology template.

· The list of values associated with the “members” keyname MUST only contain types that or homogenous (i.e., derive from the same type hierarchy).

3.7.11.4 Example

The following represents a Group Type definition:

group_types:

mycompany.mytypes.groups.placement:

description: My company’s group type for placing nodes of type Compute

members: [ tosca.nodes.Compute ]

3.7.12 Policy Type

A Policy Type defines a type of requirement that affects or governs an application or service’s topology at some stage of its lifecycle, but is not explicitly part of the topology itself (i.e., it does not prevent the application or service from being deployed or run if it did not exist).

3.7.12.1 Keynames

The Policy Type is a TOSCA Entity and has the common keynames listed in section 3.7.1 TOSCA Entity Schema.

In addition, the Policy Type has the following recognized keynames:

Keyname	Required	Type	Description
properties	no	list of property definitions	An optional list of property definitions for the Policy Type.
targets	no	string[]	An optional list of valid Node Types or Group Types the Policy Type can be applied to. Note: This can be viewed by TOSCA Orchestrators as an implied relationship to the target nodes, but one that does not have operational lifecycle considerations. For example, if we were to name this as an explicit Relationship Type we might call this “AppliesTo” (node or group).
triggers	no	list of trigger	An optional list of policy triggers for the Policy Type.

3.7.12.2 Grammar

Policy Types have the following grammar:

<policy_type_name>:

derived_from: <parent_policy_type_name>

version: <version_number>

metadata:

description: <policy_description>

properties:

<list_of_trigger_definitions>

targets: [ <list_of_valid_target_types> ]

triggers:

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· policy_type_name: represents the required symbolic name of the Policy Type being declared as a string.

· parent_policy_type_name: represents the name (string) of the Policy Type this Policy Type definition derives from (i.e., its “parent” type).

· version_number: represents the optional TOSCA version number for the Policy Type.

· policy_description: represents the optional description string for the corresponding policy_type_name.

· property_definitions: represents the optional list of property definitions for the Policy Type.

· list_of_valid_target_types: represents the optional list of TOSCA types (i.e., Group or Node Types) that are valid targets for this Policy Type.

· list_of_trigger_definitions: represents the optional list of trigger definitions for the policy.

3.7.12.3 Example

The following represents a Policy Type definition:

policy_types:

mycompany.mytypes.policies.placement.Container.Linux:

description: My company’s placement policy for linux

derived_from: tosca.policies.Root

3.8 Template-specific definitions

The definitions in this section provide reusable modeling element grammars that are specific to the Node or Relationship templates.

3.8.1 Capability assignment

A capability assignment allows node template authors to assign values to properties and attributes for a named capability definition that is part of a Node Template’s type definition.

3.8.1.1 Keynames

The following is the list of recognized keynames for a TOSCA capability assignment:

Keyname

Required

Type

Description

properties

list of

property assignments

An optional list of property definitions for the Capability definition.

attributes

list of

attribute assignments

An optional list of attribute definitions for the Capability definition.

3.8.1.2 Grammar

Capability assignments have one of the following grammars:

<capability_definition_name>:

properties:

attributes:

<attribute_assignments>

In the above grammars, the pseudo values that appear in angle brackets have the following meaning:

· capability_definition_name: represents the symbolic name of the capability as a string.

· property_assignments: represents the optional list of property assignments for the capability definition.

· attribute_assignments: represents the optional list of attribute assignments for the capability definition.

3.8.1.3 Example

The following example shows a capability assignment:

3.8.1.3.1 Notation example

node_templates:

some_node_template:

capabilities:

some_capability:

properties:

limit: 100

3.8.2 Requirement assignment

A Requirement assignment allows template authors to provide either concrete names of TOSCA templates or provide abstract selection criteria for providers to use to find matching TOSCA templates that are used to fulfill a named requirement’s declared TOSCA Node Type.

3.8.2.1 Keynames

The following is the list of recognized keynames for a TOSCA requirement assignment:

Keyname	Required	Type	Description
capability	no	string	The optional reserved keyname used to provide the name of either a: · Capability definition within a target node template that can fulfill the requirement. · Capability Type that the provider will use to select a type-compatible target node template to fulfill the requirement at runtime.
node	no	string	The optional reserved keyname used to identify the target node of a relationship. specifically, it is used to provide either a: · Node Template name that can fulfill the target node requirement. · Node Type name that the provider will use to select a type-compatible node template to fulfill the requirement at runtime.
relationship	no	string	The optional reserved keyname used to provide the name of either a: · Relationship Template to use to relate the source node to the (capability in the) target node when fulfilling the requirement. · Relationship Type that the provider will use to select a type-compatible relationship template to relate the source node to the target node at runtime.
node_filter	no	node filter	The optional filter definition that TOSCA orchestrators or providers would use to select a type-compatible target node that can fulfill the associated abstract requirement at runtime.

The following is the list of recognized keynames for a TOSCA requirement assignment’s relationship keyname which is used when Property assignments need to be provided to inputs of declared interfaces or their operations:

Keyname

Required

Type

Description

type

string

The optional reserved keyname used to provide the name of the Relationship Type for the requirement assignment’s relationship keyname.

properties

list of

interface definitions

The optional reserved keyname used to reference declared (named) interface definitions of the corresponding Relationship Type in order to provide Property assignments for these interfaces or operations of these interfaces.

3.8.2.2 Grammar

Named requirement assignments have one of the following grammars:

3.8.2.2.1 Short notation:

The following single-line grammar may be used if only a concrete Node Template for the target node needs to be declared in the requirement:

<requirement_name>: <node_template_name>

This notation is only valid if the corresponding Requirement definition in the Node Template’s parent Node Type declares (at a minimum) a valid Capability Type which can be found in the declared target Node Template. A valid capability definition always needs to be provided in the requirement declaration of the source node to identify a specific capability definition in the target node the requirement will form a TOSCA relationship with.

3.8.2.2.2 Extended notation:

The following grammar would be used if the requirement assignment needs to provide more information than just the Node Template name:

<requirement_name>:

node: <node_template_name> | <node_type_name>

relationship: <relationship_template_name> | <relationship_type_name>

capability: <capability_symbolic_name> | <capability_type_name>

node_filter:

<node_filter_definition>

occurrences: [ min_occurrences, max_occurrences ]

3.8.2.2.3 Extended grammar with Property Assignments for the relationship’s Interfaces

The following additional multi-line grammar is provided for the relationship keyname in order to provide new Property assignments for inputs of known Interface definitions of the declared Relationship Type.

<requirement_name>:

# Other keynames omitted for brevity

relationship:

type: <relationship_template_name> | <relationship_type_name>

properties:

interfaces:

<interface_assignments>

Examples of uses for the extended requirement assignment grammar include:

· The need to allow runtime selection of the target node based upon an abstract Node Type rather than a concrete Node Template. This may include use of the node_filter keyname to provide node and capability filtering information to find the “best match” of a concrete Node Template at runtime.

· The need to further clarify the concrete Relationship Template or abstract Relationship Type to use when relating the source node’s requirement to the target node’s capability.

· The need to further clarify the concrete capability (symbolic) name or abstract Capability Type in the target node to form a relationship between.

· The need to (further) constrain the occurrences of the requirement in the instance model.

In the above grammars, the pseudo values that appear in angle brackets have the following meaning:

· requirement_name: represents the symbolic name of a requirement assignment as a string.

· node_template_name: represents the optional name of a Node Template that contains the capability this requirement will be fulfilled by.

· relationship_template_name: represents the optional name of a Relationship Type to be used when relating the requirement appears to the capability in the target node.

· capability_symbolic_name: represents the optional ordered list of specific, required capability type or named capability definition within the target Node Type or Template.

· node_type_name: represents the optional name of a TOSCA Node Type the associated named requirement can be fulfilled by. This must be a type that is compatible with the Node Type declared on the matching requirement (same symbolic name) the requirement’s Node Template is based upon.

· relationship_type_name: represents the optional name of a Relationship Type that is compatible with the Capability Type in the target node.

· property_assignments: represents the optional list of property value assignments for the declared relationship.

· interface_assignments: represents the optional list of interface definitions for the declared relationship used to provide property assignments on inputs of interfaces and operations.

· capability_type_name: represents the optional name of a Capability Type definition within the target Node Type this requirement needs to form a relationship with.

· node_filter_definition: represents the optional node filter TOSCA orchestrators would use to fulfill the requirement for selecting a target node. Note that this SHALL only be valid if the node keyname’s value is a Node Type and is invalid if it is a Node Template.

3.8.2.3 Examples

3.8.2.3.1 Example 1 – Abstract hosting requirement on a Node Type

A web application node template named ‘my_application_node_template’ of type WebApplication declares a requirement named ‘host’ that needs to be fulfilled by any node that derives from the node type WebServer.

# Example of a requirement fulfilled by a specific web server node template

node_templates:

my_application_node_template:

type: tosca.nodes.WebApplication

...

requirements:

- host:

node: tosca.nodes.WebServer

In this case, the node template’s type is WebApplication which already declares the Relationship Type HostedOn to use to relate to the target node and the Capability Type of Container to be the specific target of the requirement in the target node.

3.8.2.3.2 Example 2 - Requirement with Node Template and a custom Relationship Type

This example is similar to the previous example; however, the requirement named ‘database’ describes a requirement for a connection to a database endpoint (Endpoint.Database) Capability Type in a named node template (my_database). However, the connection requires a custom Relationship Type (my.types.CustomDbConnection’) declared on the keyname ‘relationship’.

# Example of a (database) requirement that is fulfilled by a node template named

# “my_database”, but also requires a custom database connection relationship

my_application_node_template:

requirements:

- database:

node: my_database

capability: Endpoint.Database

relationship: my.types.CustomDbConnection

3.8.2.3.3 Example 3 - Requirement for a Compute node with additional selection criteria (filter)

This example shows how to extend an abstract ‘host’ requirement for a Compute node with a filter definition that further constrains TOSCA orchestrators to include additional properties and capabilities on the target node when fulfilling the requirement.

node_templates:

mysql:

type: tosca.nodes.DBMS.MySQL

properties:

# omitted here for brevity

requirements:

- host:

node: tosca.nodes.Compute

node_filter:

capabilities:

- host:

properties:

- num_cpus: { in_range: [ 1, 4 ] }

- mem_size: { greater_or_equal: 512 MB }

- os:

properties:

- architecture: { equal: x86_64 }

- type: { equal: linux }

- distribution: { equal: ubuntu }

- mytypes.capabilities.compute.encryption:

properties:

- algorithm: { equal: aes }

- keylength: { valid_values: [ 128, 256 ] }

3.8.3 Node Template

A Node Template specifies the occurrence of a manageable software component as part of an application’s topology model which is defined in a TOSCA Service Template. A Node template is an instance of a specified Node Type and can provide customized properties, constraints or operations which override the defaults provided by its Node Type and its implementations.

3.8.3.1 Keynames

The following is the list of recognized keynames for a TOSCA Node Template definition:

Keyname	Required	Type	Description
type	yes	string	The required name of the Node Type the Node Template is based upon.
description	no	description	An optional description for the Node Template.
metadata	no	map of string	Defines a section used to declare additional metadata information.
directives	no	string[]	An optional list of directive values to provide processing instructions to orchestrators and tooling.
properties	no	list of property assignments	An optional list of property value assignments for the Node Template.
attributes	no	list of attribute assignments	An optional list of attribute value assignments for the Node Template.
requirements	no	list of requirement assignments	An optional sequenced list of requirement assignments for the Node Template.
capabilities	no	list of capability assignments	An optional list of capability assignments for the Node Template.
interfaces	no	list of interface definitions	An optional list of named interface definitions for the Node Template.
artifacts	no	list of artifact definitions	An optional list of named artifact definitions for the Node Template.
node_filter	no	node filter	The optional filter definition that TOSCA orchestrators would use to select the correct target node. This keyname is only valid if the directive has the value of “selectable” set.
copy	no	string	The optional (symbolic) name of another node template to copy into (all keynames and values) and use as a basis for this node template.

3.8.3.2 Grammar

<node_template_name>:

type: <node_type_name>

description: <node_template_description>

directives: [<directives>]

metadata:

properties:

attributes:

<attribute_assignments>

requirements:

- <requirement_assignments>

capabilities:

<capability_assignments>

interfaces:

artifacts:

<artifact_definitions>

node_filter:

<node_filter_definition>

copy: <source_node_template_name>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· node_template_name: represents the required symbolic name of the Node Template being declared.

· node_type_name: represents the name of the Node Type the Node Template is based upon.

· node_template_description: represents the optional description string for Node Template.

· directives: represents the optional list of processing instruction keywords (as strings) for use by tooling and orchestrators.

· property_assignments: represents the optional list of property assignments for the Node Template that provide values for properties defined in its declared Node Type.

· attribute_assignments: represents the optional list of attribute assignments for the Node Template that provide values for attributes defined in its declared Node Type.

· requirement_assignments: represents the optional sequenced list of requirement assignments for the Node Template that allow assignment of type-compatible capabilities, target nodes, relationships and target (node filters) for use when fulfilling the requirement at runtime.

· capability_assignments: represents the optional list of capability assignments for the Node Template that augment those provided by its declared Node Type.

· interface_definitions: represents the optional list of interface definitions for the Node Template that augment those provided by its declared Node Type.

· artifact_definitions: represents the optional list of artifact definitions for the Node Template that augment those provided by its declared Node Type.

· node_filter_definition: represents the optional node filter TOSCA orchestrators would use for selecting a matching node template.

· source_node_template_name: represents the optional (symbolic) name of another node template to copy into (all keynames and values) and use as a basis for this node template.

3.8.3.3 Additional requirements

· The node_filter keyword (and supporting grammar) SHALL only be valid if the Node Template has a directive keyname with the value of “selectable” set.

· The source node template provided as a value on the copy keyname MUST NOT itself use the copy keyname (i.e., it must itself be a complete node template description and not copied from another node template).

3.8.3.4 Example

node_templates:

mysql:

type: tosca.nodes.DBMS.MySQL

properties:

root_password: { get_input: my_mysql_rootpw }

port: { get_input: my_mysql_port }

requirements:

- host: db_server

interfaces:

Standard:

configure: scripts/my_own_configure.sh

3.8.4 Relationship Template

A Relationship Template specifies the occurrence of a manageable relationship between node templates as part of an application’s topology model that is defined in a TOSCA Service Template. A Relationship template is an instance of a specified Relationship Type and can provide customized properties, constraints or operations which override the defaults provided by its Relationship Type and its implementations.

3.8.4.1 Keynames

The following is the list of recognized keynames for a TOSCA Relationship Template definition:

Keyname	Required	Type	Description
type	yes	string	The required name of the Relationship Type the Relationship Template is based upon.
description	no	description	An optional description for the Relationship Template.
metadata	no	map of string	Defines a section used to declare additional metadata information.
properties	no	list of property assignments	An optional list of property assignments for the Relationship Template.
attributes	no	list of attribute assignments	An optional list of attribute assignments for the Relationship Template.
interfaces	no	list of interface definitions	An optional list of named interface definitions for the Node Template.
copy	no	string	The optional (symbolic) name of another relationship template to copy into (all keynames and values) and use as a basis for this relationship template.

3.8.4.2 Grammar

<relationship_template_name>:

type: <relationship_type_name>

description: <relationship_type_description>

metadata:

properties:

attributes:

<attribute_assignments>

interfaces:

<source_relationship_template_name>

copy:

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· relationship_template_name: represents the required symbolic name of the Relationship Template being declared.

· relationship_type_name: represents the name of the Relationship Type the Relationship Template is based upon.

· relationship_template_description: represents the optional description string for the Relationship Template.

· property_assignments: represents the optional list of property assignments for the Relationship Template that provide values for properties defined in its declared Relationship Type.

· attribute_assignments: represents the optional list of attribute assignments for the Relationship Template that provide values for attributes defined in its declared Relationship Type.

· interface_definitions: represents the optional list of interface definitions for the Relationship Template that augment those provided by its declared Relationship Type.

· source_relationship_template_name: represents the optional (symbolic) name of another relationship template to copy into (all keynames and values) and use as a basis for this relationship template.

3.8.4.3 Additional requirements

· The source relationship template provided as a value on the copy keyname MUST NOT itself use the copy keyname (i.e., it must itself be a complete relationship template description and not copied from another relationship template).

3.8.4.4 Example

relationship_templates:

storage_attachment:

type: AttachesTo

properties:

location: /my_mount_point

3.8.5 Group definition

A group definition defines a logical grouping of node templates, typically for management purposes, but is separate from the application’s topology template.

3.8.5.1 Keynames

The following is the list of recognized keynames for a TOSCA group definition:

Keyname	Required	Type	Description
type	yes	string	The required name of the group type the group definition is based upon.
description	no	description	The optional description for the group definition.
metadata	no	map of string	Defines a section used to declare additional metadata information.
properties	no	list of property assignments	An optional list of property value assignments for the group definition.
members	no	list of string	The optional list of one or more node template names that are members of this group definition.
interfaces	no	list of interface definitions	An optional list of named interface definitions for the group definition.

3.8.5.2 Grammar

Group definitions have one the following grammars:

<group_name>:

type: <group_type_name>

description: <group_description>

metadata:

properties:

members: [ <list_of_node_templates> ]

interfaces:

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· group_name: represents the required symbolic name of the group as a string.

· group_type_name: represents the name of the Group Type the definition is based upon.

· group_description: contains an optional description of the group.

· property_assignments: represents the optional list of property assignments for the group definition that provide values for properties defined in its declared Group Type.

· list_of_node_templates: contains the required list of one or more node template names (within the same topology template) that are members of this logical group.

· interface_definitions: represents the optional list of interface definitions for the group definition that augment those provided by its declared Group Type.

3.8.5.3 Additional Requirements

· Group definitions SHOULD NOT be used to define or redefine relationships (dependencies) for an application that can be expressed using normative TOSCA Relationships within a TOSCA topology template.

3.8.5.4 Example

The following represents a group definition:

groups:

my_app_placement_group:

type: tosca.groups.Root

description: My application’s logical component grouping for placement

members: [ my_web_server, my_sql_database ]

3.8.6 Policy definition

A policy definition defines a policy that can be associated with a TOSCA topology or top-level entity definition (e.g., group definition, node template, etc.).

3.8.6.1 Keynames

The following is the list of recognized keynames for a TOSCA policy definition:

Keyname	Required	Type	Description
type	yes	string	The required name of the policy type the policy definition is based upon.
description	no	description	The optional description for the policy definition.
metadata	no	map of string	Defines a section used to declare additional metadata information.
properties	no	list of property assignments	An optional list of property value assignments for the policy definition.
targets	no	string[]	An optional list of valid Node Templates or Groups the Policy can be applied to.
triggers	no	list of trigger definitions	An optional list of trigger definitions to invoke when the policy is applied by an orchestrator against the associated TOSCA entity.

3.8.6.2 Grammar

Policy definitions have one the following grammars:

<policy_name>:

type: <policy_type_name>

description: <policy_description>

metadata:

properties:

targets: [<list_of_policy_targets>]

triggers:

<list_of_trigger_definitions>

In the above grammar, the pseudo values that appear in angle brackets have the following meaning:

· policy_name: represents the required symbolic name of the policy as a string.

· policy_type_name: represents the name of the policy the definition is based upon.

· policy_description: contains an optional description of the policy.

· property_assignments: represents the optional list of property assignments for the policy definition that provide values for properties defined in its declared Policy Type.

· list_of_policy_targets: represents the optional list of names of node templates or groups that the policy is to applied to.

· list_of_trigger_definitions: represents the optional list of trigger definitions for the policy.

3.8.6.3 Example

The following represents a policy definition:

policies:

- my_compute_placement_policy:

type: tosca.policies.placement

description: Apply my placement policy to my application’s servers

targets: [ my_server_1, my_server_2 ]

# remainder of policy definition left off for brevity

3.8.7 Imperative Workflow definition

A workflow definition defines an imperative workflow that is associated with a TOSCA topology.

3.8.7.1 Keynames

The following is the list of recognized keynames for a TOSCA workflow definition:

Keyname	Required	Type	Description
description	no	description	The optional description for the workflow definition.
metadata	no	map of string	Defines a section used to declare additional metadata information.
inputs	no	list of property definitions	The optional list of input parameter definitions.
preconditions	no	list of precondition definitions	List of preconditions to be validated before the workflow can be processed.
steps	No	list of step definitions	An optional list of valid Node Templates or Groups the Policy can be applied to.

3.8.7.2 Grammar

Imperative workflow definitions have the following grammar:

<workflow_name>:

description: <workflow_description>

metadata:

inputs: