diff options
Diffstat (limited to 'docs/files/dictionary-validation.rst')
-rw-r--r-- | docs/files/dictionary-validation.rst | 230 |
1 files changed, 230 insertions, 0 deletions
diff --git a/docs/files/dictionary-validation.rst b/docs/files/dictionary-validation.rst new file mode 100644 index 0000000..6cfd67e --- /dev/null +++ b/docs/files/dictionary-validation.rst @@ -0,0 +1,230 @@ +.. 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 +:: + java -jar validation-dictionary-1.2.16-standalone.jar <path to dictionary_file.yaml> + +Examples +-------- + +1. Successful validation +:: + ❯ 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 +:: + ❯ 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 +:: + ❯ 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: + +Command +:: + oclip --product onap-honolulu dictionary-validate --yaml <path-to-yaml-file> + +For example +:: + 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]\"}]"} |