4.3.7. Annotation Types
- Anatoly Katzman
Annotation is an extension to the standard TOSCA spec (assumed that standard parsers will ignore the annotations). The Annotations allows putting some extra information on an input value. The information could be various: UI visualization, assignment responsibility (role), uniqueness information, input origin etc. one input value may have a list of annotation definitions.
In order to use annotation, the annotation type should first be defined. The annotation type and annotation definition are described below.
1.1.1.1 Tosca Extension Annotation Type Definition
The Annotation Type has the following recognized keynames:
1.1.1.1.1 Keynames
Keyname | Required | Type | Constraints | Description |
version | No | version | N/A | An optional version for the annotation type definition. |
description | No | description | N/A | An optional description for the annotation type. |
properties | No (An annotation can indicate something by the very fact of its presence. Even without properties) | list of property definitions | N/A | The list property definitions that comprise the schema for an annotation type in TOSCA. |
1.1.1.1.2 Grammar
<annotation_type_name>:
version: <version_number>
description: <annotation_type_description>
properties:
<property_definitions>
In the above grammar, the pseudo values that appear in angle brackets have the following meaning:
annotation_type_name: represents the required symbolic name of the Annotation Type as a string. This type should include full namespace to avoid collisions in annotation types.
version_number: represents the optional TOSCA version number for the Annotation Type.
annotation_type_description: represents the optional description for the Annotation Type.
property_definitions: represents the optional list of one or more property definitions that provide the schema for the Annotation Type. If a properties keyname is provided, it must contain one or more valid property definitions
1.1.1.1.3 Examples
The below are examples only and not supported in SDC.
Annotation without properties
# define a new annotation type
org.myapp.runtime_value:
description: indicates whether this input should be populated during runtime
Annotation with properties
# define annotation with properties
org.myapp.visual:
description: visualization flags
properties:
editable:
type: boolean
visible:
type: boolean
1.1.1.2 SDC Annotation Type Definition
An annotation definition defines a named, typed value and related data that can be associated with an input (parameter definition) defined in the TOSCA spec. Annotations are used by template authors to provide some extra information about the input, which is not a constraint. The annotations on the input can help the template consumer to decide on actions regarding this input.
1.1.1.2.1 keynames
Keyname | Required | Type | Description |
type | yes | The required name of the annotation type the annotation definition is based upon. | |
properties | no | list of | An optional list of property value assignments for the annotation definition. |
1.1.1.2.2 Grammar
<annotation_name>:
type: <annotation_type>
properties:
<property_assignments>
annotation_name: represents the required symbolic name of the annotation as a string.
annotation_type: represents the full name of the annotation type it is based upon.
property_assignments: represents the optional list of property assignments for the annotation definition that provide values for properties defined in its declared Annotation Type.
1.1.1.2.3 Example
ui_info:
type: org.myapp.visual
properties:
visible: false
editable: false
responsibility:
type: org.myapp.runtime_value
1.1.1.3 Extending TOSCA Service Template and Parameter Definition
1.1.1.3.1 Service Template
TOSCA spec defines the Service Template as a yaml document containing element definitions of building blocks. The spec lists the recognized keynames by the service template. To that list, we add the annotation types definition
Keyname | Required | Type | Description |
annotation_types | no | List of Annotation Types | An optional list of annotation types definition. |
1.1.1.3.2 Parameter Definition
TOSCA spec defines Parameter with the several keynames. In order to support the annotations, we extend the Parameter definition with additional keyname:
Keyname | Required | Type | Description |
annotations | no | List of Annotation Definition | An optional list of annotations |
Example:
inputs:
cpus:
type: integer
description: Number of CPUs for the server.
constraints:
- valid_values: [ 1, 2, 4, 8 ]
annotations:
ui_info:
type: org.myapp.visual
properties:
visible: false
editable: false
responsibility:
type: org.myapp.runtime_value
1.1.1.3.3 Annotation Type – org.openecomp.annotations.Source
The first use in annotations in SDC is for identifying the source of the parameter. Inputs in the TOSCA template created by SDC can be originated either from HEAT parameters provided by vendor or it can be added during design. The runtime components downstream would like to identify the origin of the parameter as well as the original name of it.
keynames:
Definition:
annotation_types:
org.openecomp.annotations.Source:
description: Indicates the origin source of an input
properties:
source_type:
type: String
vf_module_label:
type: list
description: List of HEAT file name this input was originated from
entry_schema:
type: String
param_name:
type: String
description: Source parameter name
1.1.1.3.3.1 Example
tosca_definitions_version: tosca_simple_yaml_1_1
metadata:
invariantUUID: ef6c5433-8eb0-4bb3-b900-4ONAPd05bea60f
UUID: a32eefb5-fa54-4934-96ee-90d1eafa56c5
name: Service Groups 1
description: test
type: Service
inputs:
vfgroups10_mmn_data_volume_1_nfc_naming_code: #input without annotations
type: string
vfgroups10_mmn_data_volume_1_volume_id: #input with annotations
type: string
default: volume1_new
annotations:
source:
type: org.openecomp.annotations.Source
properties:
source_type : HEAT
vf_module_label: pxmc_mmn
param_name: mmn_data_volume_id_1