diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/sections/apis/SDK.rst | 8 | ||||
| -rw-r--r-- | docs/sections/sdk/apis.rst | 102 | ||||
| -rw-r--r-- | docs/sections/sdk/architecture.rst | 6 |
3 files changed, 114 insertions, 2 deletions
diff --git a/docs/sections/apis/SDK.rst b/docs/sections/apis/SDK.rst index 64879228..c76348e4 100644 --- a/docs/sections/apis/SDK.rst +++ b/docs/sections/apis/SDK.rst @@ -23,7 +23,7 @@ Current version .. code-block:: xml <properties> - <sdk.version>1.4.1</sdk.version> + <sdk.version>1.4.2</sdk.version> </properties> @@ -76,5 +76,11 @@ SDK Maven dependencies (modules) <scope>runtime</scope> </dependency> + <dependency> + <groupId>org.onap.dcaegen2.services.sdk</groupId> + <artifactId>dcaegen2-services-sdk-services-external-schema-manager</artifactId> + <version>${sdk.version}</version> + </dependency> + <!-- more to go --> </dependencies> diff --git a/docs/sections/sdk/apis.rst b/docs/sections/sdk/apis.rst index d68aa3fb..a4937f73 100644 --- a/docs/sections/sdk/apis.rst +++ b/docs/sections/sdk/apis.rst @@ -4,6 +4,7 @@ Available APIs ============== + .. toctree:: :depth: 3 @@ -186,3 +187,104 @@ Sample usage: .doOnSuccess(() -> logger.info("All events has been sent")) .doOnError(ex -> logger.warn("Failed to send one or more events", ex)) .subscribe(); + +external-schema-manager - JSON Validator with schema mapping +------------------------------------------------------------ +This library can be used to validate any JSON content incoming as JsonNode. What differs it from other validation +libraries is mapping of externally located schemas to local schema files. + +Validated JSON must have one field that will refer to an external schema, which will be mapped to local file and then +validation of any chosen part of JSON is executed using local schema. + +Mapping file is cached on validator creation, so it's not read every time validation is performed. +Schemas' content couldn't be cached due to external library restrictions (OpenAPI4j). + +Example JSON: + +.. code-block:: json + + { + "schemaReference": "https://forge.3gpp.org/rep/sa5/data-models/blob/REL-16/OpenAPI/faultMnS.yaml", + "data": + { + "exampleData: "SAMPLE_VALUE" + } + } + +Interface: + +There are two methods, that are interface of this sub-project. + +Validator builder: + +.. code-block:: java + + new StndDefinedValidator.ValidatorBuilder() + .mappingFilePath(mappingFilePath) + .schemasPath(schemasPath) + .schemaRefPath(schemaRefPath) + .stndDefinedDataPath(stndDefinedDataPath) + .build(); + + +Validator usage: + +.. code-block:: java + + stndDefinedValidator.validate(event); + +There are 4 string parameters of the builder: + +.. csv-table:: **String parameters of the builder** + :header: "Name", "Description", "Example", "Note" + :widths: 10, 20, 20, 20 + + "mappingFilePath", "This should be a local filesystem path to file with mappings of public URLs to local URLs. Format of the schema mapping file is a JSON file with list of mappings", "etc/externalRepo/schema-map.json", " " + "schemasPath", "Schemas path is a directory under which external-schema-manager will search for local schemas", "./etc/externalRepo/ and first mapping from example mappingFile is taken, validator will look for schema under the path: ./etc/externalRepo/3gpp/rep/sa5/data-models/blob/REL-16/OpenAPI/faultMnS.yaml", " " + "schemaRefPath", "This is an internal path from validated JSON. It should define which field will be taken as public schema reference, which is later mapped", "/event/stndDefinedFields/schemaReference", "In SDK version 1.4.2 this path doesn't use JSON path notation (with . signs). It might change in further versions" + "stndDefinedDataPath", "This is path to stndDefined data in JSON. This fields will be validated during stndDefined validation.", "/event/stndDefinedFields/data", "In SDK version 1.4.2 this path doesn't use JSON path notation (with . signs). It might change in further versions." + + +Format of the schema mapping file is a JSON file with list of mappings, as shown in the example below. + +.. code-block:: json + + [ + { + "publicURL": "https://forge.3gpp.org/rep/sa5/data-models/blob/REL-16/OpenAPI/faultMnS.yaml", + "localURL": "3gpp/rep/sa5/data-models/blob/REL-16/OpenAPI/faultMnS.yaml" + }, + { + "publicURL": "https://forge.3gpp.org/rep/sa5/data-models/blob/REL-16/OpenAPI/heartbeatNtf.yaml", + "localURL": "3gpp/rep/sa5/data-models/blob/REL-16/OpenAPI/heartbeatNtf.yaml" + }, + { + "publicURL": "https://forge.3gpp.org/rep/sa5/data-models/blob/REL-16/OpenAPI/PerDataFileReportMnS.yaml", + "localURL": "3gpp/rep/sa5/data-models/blob/REL-16/OpenAPI/PerDataFileReportMnS.yaml" + }, + { + "publicURL": "https://forge.3gpp.org/rep/sa5/data-models/blob/master/OpenAPI/provMnS.yaml", + "localURL": "3gpp/rep/sa5/data-models/blob/REL-16/OpenAPI/provMnS.yaml" + } + ] + +**Possible scenarios when using external-schema-manger:** + +When the schema-map file, the schema and the sent event are correct, then the validation is successful and the log +shows "Validation of stndDefinedDomain has been successful". + +Errors in the schema-map - none of the mappings are cached: + +- When no schema-map file exists, "Unable to read mapping file. Mapping file path: {}" is logged. +- When a schema-map file exists, but has an incorrect format, a warning is logged: "Schema mapping file has incorrect format. Mapping file path: {}" + +Errors in one of the mappings in schema-map - this mapping is not cached, a warning is logged "Mapping for publicURL ({}) will not be cached to validator.": + +- When the local url in the schema-map file references a file that does not exist, the warning "Local schema resource missing. Schema file with path {} has not been found." +- When the schema file is empty, the information "Schema file is empty. Schema path: {}" is logged +- When a schema file has an incorrect format (not a yaml), the following information is logged: Schema has incorrect YAML structure. Schema path: {} " + +Errors in schemaRefPath returns errors: + +- If in the schemaRef path in the event we provide an url that refers to an existing schema, but the part after # refers to a non-existent part of it, then an error is thrown: IncorrectInternalFileReferenceException ("Schema reference refer to existing file, but internal reference (after #) is incorrect.") " +- When in the schemaRef path in the event, we provide a url that refers to a non-existent mapping from public to localURL, a NoLocalReferenceException is thrown, which logs to the console: "Couldn't find mapping for public url. PublicURL: {}"
\ No newline at end of file diff --git a/docs/sections/sdk/architecture.rst b/docs/sections/sdk/architecture.rst index ab0fa2b8..f99fccb0 100644 --- a/docs/sections/sdk/architecture.rst +++ b/docs/sections/sdk/architecture.rst @@ -81,8 +81,12 @@ ConfigBindingService Client Crypt Password ++++++++++++++ - Library to generate and match cryptography password using BCrypt algorithm + Library to generate and match cryptography password using BCrypt algorithm. High Volume VES Collector Client Producer +++++++++++++++++++++++++++++++++++++++++ A reference Java implementation of High Volume VES Collector client. This library is used in xNF simulator which helps us test HV VES Collector in CSIT tests. You may use it as a reference when implementing your code in non-JVM language or directly when using Java/Kotlin/etc. + +External Schema Manager ++++++++++++++++++++++++++++++++++++++++++ + Library to validate JSON with mapping of external schemas to local schema files. |