docs/files/dictionary-validation.rst

.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
.. Copyright 2020 Nokia

.. _dictionary_validation:

VNFSDK Dictionary Validation User Guide
==========================================

Library was created to validate Dictionary YAML files which are used in a xNF ETSI NFV onboarding packages - CSAR files.

Basic information
------------------

The Dictionary validation library has two versions:

- validation-dictionary-<version>.jar contains Dictionary YAML validation logic which can be used by any ONAP component. Currently it is used by VNFSDK and SDC.

- validation-dictionary-<version>-standalone.jar contains Dictionary YAML validation logic which can be run from command line.

The Dictionary validation can be started in the two ways:

- as a standalone application
- using an Oclip command

Release Note
------------

The standalone version of Dictionary validation library is available from Honolulu release.

How to download standalone version
----------------------------------

All available jars are available at::

  https://nexus.onap.org/#nexus-search;quick~validation-dictionary

To download a standalone version of Dictionary validation library you need to prepare a link for selected version of file or
manually download the file from Nexus (Viewing Repository: Releases).

Template::

  wget -O validation-dictionary-<VERSION>-standalone.jar https://nexus.onap.org/service/local/artifact/maven/redirect?r=releases&g=org.onap.vnfsdk.validation&a=validation-dictionary&v=<VERSION>&e=jar&c=standalone

For example link for version 1.2.16 looks like::

  wget -O validation-dictionary-1.2.16-standalone.jar https://nexus.onap.org/service/local/artifact/maven/redirect?r=releases&g=org.onap.vnfsdk.validation&a=validation-dictionary&v=1.2.16&e=jar&c=standalone

Application return codes
------------------------

===========  ===========
Return code  Description
===========  ===========
0            No errors, validation passed
1            Validation fails
2            Internal application error
===========  ===========

Application outputs
-------------------

================    ===========
Output              Description
================    ===========
Console             All information's about operation progress, result and errors are logged at user console.
Log file            Application creates a log file where all information's generated by application are logged.
Result json file    Validation result is also available in the file with postfix '-validation-results.json'. The File is stored in a folder with input dictionary file.
================    ===========

How to run standalone application?
----------------------------------

1. Install Java 11 JRE
2. Download standalone version of Dictionary YAML validation application

For example::

  wget -O validation-dictionary-1.2.16-standalone.jar https://nexus.onap.org/service/local/artifact/maven/redirect?r=snapshots&g=org.onap.vnfsdk.validation&a=validation-dictionary&v=1.2.16&e=jar&c=standalone

3. Go to folder with downloaded application and run it.

Code::

  java -jar validation-dictionary-1.2.16-standalone.jar <path to dictionary_file.yaml>

Examples
--------

1. Successful validation.

Code::

    ❯ java -jar validation-dictionary-1.2.16-standalone.jar /home/username/yaml_schema/Simple_Valid_Schema.yaml

    # Executing a 'Validate Dictionary yaml' operation ...
    # ... Done.

    # Operation result:

    {
        "file": "/home/username/yaml_schema/Simple_Valid_Schema.yaml",
        "status": "PASS",
        "errors": []
    }

    # Result was stored in a file: '/home/username/yaml_schema/Simple_Valid_Schema-validation-results.json'

    # Application exits successfully.

    ❯ echo $?
    0

    ❯ cat Simple_Valid_Schema-validation-results.json

    {
        "file": "/home/username/yaml_schema/Simple_Valid_Schema.yaml",
        "status": "PASS",
        "errors": []
    }


2. Failing validation.

Code::

    ❯ java -jar validation-dictionary-1.2.16-standalone.jar /home/username/yaml_schema/Dictionary.yaml

    # Executing a 'Validate Dictionary yaml' operation ...
    # ... Done.

    # Operation result:

    {
        "file": "/home/username/yaml_schema/Dictionary.yaml",
        "status": "FAILED",
        "errors": [
                {
                  "yamlDocumentNumber": 1,
                  "path": "/MetaData/Fields/measResultType",
                  "message": "Value(s) is/are not in array of accepted values.\n value(s):  integer\n  accepted value(s):  [float, uint32, uint64]"
                },
                {
                  "yamlDocumentNumber": 1,
                  "path": "/MetaData/Fields/",
                  "message": "Key not found: measChangeType"
                },
                {
                  "yamlDocumentNumber": 2,
                  "path": "/MetaData/Fields/",
                  "message": "Key not found: measChangeType"
                },
                {
                  "yamlDocumentNumber": 3,
                  "path": "/MetaData/Fields/measAdditionalFields/vendorField1",
                  "message": "Value(s) is/are not in array of accepted values.\n value(s):  [Z, A]\n  accepted value(s):  [X, Y, Z]"
                }
        ]
    }

    # Result was stored in a file: '/home/username/yaml_schema/Dictionary-validation-results.json'

    # Application exits successfully.

    ❯ echo $?
    1

    ❯ cat /home/username/yaml_schema/Dictionary-validation-results.json

    {
        "file": "/home/username/yaml_schema/Dictionary.yaml",
        "status": "FAILED",
        "errors": [
                {
                  "yamlDocumentNumber": 1,
                  "path": "/MetaData/Fields/measResultType",
                  "message": "Value(s) is/are not in array of accepted values.\n value(s):  integer\n  accepted value(s):  [float, uint32, uint64]"
                },
                {
                  "yamlDocumentNumber": 1,
                  "path": "/MetaData/Fields/",
                  "message": "Key not found: measChangeType"
                },
                {
                  "yamlDocumentNumber": 2,
                  "path": "/MetaData/Fields/",
                  "message": "Key not found: measChangeType"
                },
                {
                  "yamlDocumentNumber": 3,
                  "path": "/MetaData/Fields/measAdditionalFields/vendorField1",
                  "message": "Value(s) is/are not in array of accepted values.\n value(s):  [Z, A]\n  accepted value(s):  [X, Y, Z]"
                }
        ]
    }

3. Validation internal error

Code::

    ❯ java -jar validation-dictionary-1.2.16-standalone.jar /home/username/Not_Yaml_File.txt

    # Executing a 'Validate Dictionary yaml' operation ...
    # Command error:
    Provided yaml file has invalid structure!, more information in log file.

    # Application fails with internal error.

    ❯ echo $?
    2

    ❯ cat dictionary-validate.log

    2020-12-14 08:23:31,054 ERROR o.o.v.y.YamlLoader [main] Failed to load multi document YAML file
    ...

How to run Dictionary YAML validation as an Oclip command?
-------------------------------------------------------------

1. Run Oclip and execute a command:

Code::

    oclip --product onap-honolulu dictionary-validate --yaml <path-to-yaml-file>

For example:

Code::

    vnfadmin@ddc559540515:/tmp$ oclip --product onap-honolulu dictionary-validate --yaml /tmp/Simple_Valid_Schema.yaml
    {"file":"/tmp/Simple_Valid_Schema.yaml","date":"Mon Dec 28 07:38:43 UTC 2020","criteria":"PASS","errors":"[]"}

    vnfadmin@ddc559540515:/tmp$ oclip --product onap-honolulu dictionary-validate --yaml /tmp/Dictionary.yaml
    {"file":"/tmp/Dictionary.yaml","date":"Mon Dec 28 07:38:08 UTC 2020","criteria":"FAILED","errors":"
    [{\"yamlDocumentNumber\":1,\"path\":\"/MetaData/Fields/measResultType\",
    \"message\":\"Value(s) is/are not in array of accepted values.\\n value(s):  integer\\n  accepted value(s):
    [float, uint32, uint64]\"},{\"yamlDocumentNumber\":1,\"path\":\"/MetaData/Fields/\",\"message\":\"Key not found: measChangeType\"},
    {\"yamlDocumentNumber\":2,\"path\":\"/MetaData/Fields/\",\"message\":\"Key not found: measChangeType\"},
    {\"yamlDocumentNumber\":3,\"path\":\"/MetaData/Fields/measAdditionalFields/vendorField1\",
    \"message\":\"Value(s) is/are not in array of accepted values.\\n value(s):  [Z, A]\\n  accepted value(s):  [X, Y, Z]\"}]"}