4.3.7. Annotation Types

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

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

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

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:

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