@hashgraph/nft-utilities - npm Package Compare versions

Comparing version 1.2.1 to 2.0.0

examples/token-metadata-validator/invalid-errors-metadata.js

@@ -20,3 +20,3 @@ /*-
  */
-const { validator, defaultVersion } = require('../..');
+const { Validator, defaultVersion } = require('../..');
 
@@ -41,3 +41,4 @@ function main() {
 
-    const results = validator(metadataInstance, defaultVersion);
+    const validator = new Validator();
+    const results = validator.validate(metadataInstance, defaultVersion);
     console.log(results);
@@ -44,0 +45,0 @@

examples/token-metadata-validator/invalid-warnings-metadata.js

@@ -20,3 +20,3 @@ /*-
  */
-const { validator, defaultVersion } = require('../..');
+const { Validator, defaultVersion } = require('../..');
 
@@ -42,3 +42,4 @@ function main() {
 
-    const results = validator(metadataInstance, defaultVersion);
+    const validator = new Validator();
+    const results = validator.validate(metadataInstance, defaultVersion);
     console.log(results);
@@ -45,0 +46,0 @@

examples/token-metadata-validator/valid-metadata.js

@@ -20,3 +20,3 @@ /*-
  */
-const { validator, defaultVersion } = require('../..');
+const { Validator, defaultVersion } = require('../..');
 
@@ -41,3 +41,4 @@ function main() {
 
-    const results = validator(metadataInstance); // by default: verifies metadata against HIP412@2.0.0
+    const validator = new Validator();
+    const results = validator.validate(metadataInstance); // by default: verifies metadata against HIP412@2.0.0
     console.log(results);
@@ -44,0 +45,0 @@

index.js

@@ -20,3 +20,3 @@ /*-
  */
-const { validator, defaultVersion } = require('./validator');
+const { Validator, defaultSchemaVersion } = require('./validator');
 const { localValidation } = require('./local-validation');
@@ -31,4 +31,4 @@ const {
     // validation
-    validator,
-    defaultVersion,
+    Validator,
+    defaultSchemaVersion,
 
@@ -35,0 +35,0 @@ // local validation

local-validation/index.js

@@ -20,3 +20,3 @@ /*-
  */
-const { validator } = require('../validator/index');
+const { Validator } = require('../validator/index');
 const { readFiles, getJSONFilesForDir } = require('../helpers/files');
@@ -26,5 +26,6 @@
     let validationResults = {};
+    const validator = new Validator();
 
     files.forEach(file => {
-        const result = validator(file.filedata);
+        const result = validator.validate(file.filedata);
         validationResults[file.filename] = result;
@@ -31,0 +32,0 @@ });

package.json

 {
   "name": "@hashgraph/nft-utilities",
-  "version": "1.2.1",
+  "version": "2.0.0",
   "description": "NFT Utilities for Hedera Hashgraph",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

@@ -11,3 +11,3 @@ <div align="center">
 
-1. **Token metadata validation:** Verify your metadata against the [token metadata JSON schema V2](https://github.com/hashgraph/hedera-improvement-proposal/blob/main/HIP/hip-412.md) for NFTs, which returns errors and warnings against the standard.
+1. **Token metadata validation:** Verify your metadata against the [token metadata JSON schema V2](https://github.com/hashgraph/hedera-improvement-proposal/blob/main/HIP/hip-412.md) for NFTs, which returns errors and warnings against the standard. You can also define your own token metadata standard and add it to the package to use this schema for validation.
 2. **Local metadata validator:** Verify a local folder containing multiple JSON metadata files against the standard before publishing the NFT collection on the Hedera network. 
@@ -43,9 +43,9 @@ 3. **Risk score calculation:** Calculate a risk score for an NFT collection from the token information or by passing a token ID of an NFT on the Hedera testnet or mainnet.
 
-Import the package into your project. You can import the `validator` function and the default schema version for token metadata with `defaultVersion`.
+Import the package into your project. You can import the `Validator` class and the default schema version for token metadata with `defaultVersion`.
 
 ```js
-const { validator, defaultVersion } = require('@hashgraph/nft-utilities');
+const { Validator, defaultVersion } = require('@hashgraph/nft-utilities');
 ```
 
-You can use the `validator` like below. 
+You can use the `Validator` like below. 
 1. The first parameter is the JSON object you want to verify against a JSON schema
@@ -63,3 +63,4 @@ 2. The second parameter is the version of the token metadata JSON schema against which you want to validate your metadata instance. The default value is `2.0.0` (V2). In the future, new functionality might be added, releasing new version numbers.
 
-const issues = validator(metadata, version);
+const validator = new Validator();
+const issues = validator.validate(metadata, version);
 ```
@@ -117,2 +118,45 @@
 
+#### Method 1: Use Validator constructor to pass custom schemas
+
+The easiest approach to adding new schemas is using the constructor of the `Validator` class. It accepts an array of JSON objects, each containing a JSON schema and tag for the schema. The tag is used to refer to the schema when validating metadata instances. 
+
+Therefore, each tag needs to be unqiue. The following tags can't be used as they are already occupied:
+
+- `1.0.0` -> Refers to token metadata JSON schema V1 (HIP10)
+- `2.0.0` -> Refers to token metadata JSON schema V2 (HIP412)
+
+You can add your custom schema like this:
+
+```js
+const { Validator } = require('@hashgraph/nft-utilities');
+
+// Define your schema
+const customSchema = {
+    "title": "Token Metadata",
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+        "name": {
+            "type": "string",
+            "description": "Identifies the asset to which this token represents."
+        }
+    },
+    "required": ["name"]
+}
+
+// Create Validator instance with custom schema labeled "custom-v1"
+const validator = new Validator([{ schemaObject: customSchema, tag: "custom-v1" }]);
+
+// Verify metadata against custom schema
+const results = validator.validate(metadataInstance, "custom-v1");
+console.log(results);
+```
+
+**Examples:** See: [/examples/token-metadata-calculation](https://github.com/hashgraph/hedera-nft-utilities/tree/main/examples/token-metadata-calculation/custom-schema-valid-metadata.js)
+
+
+#### Method 2: Rebuilding package
+
+> ⚠️ Warning: **This approach requires you to rebuild the package.**
+
 You can add custom JSON schemas to the `/schemas` folder. 
@@ -135,3 +179,3 @@
 
-Set custom validation rules by importing new validators from the `/validators` folder into the `index.js` file. You can then add them to the `validator()` function. Stick to the `issues` format of errors and warnings (see section "Issues format" for the detailed description).
+Set custom validation rules by importing new validators from the `/validators` folder into the `index.js` file. You can then add them to the `validate()` function. Stick to the `issues` format of errors and warnings (see section "Issues format" for the detailed description).
 
@@ -141,7 +185,7 @@ ```js
 
-const validator = (instance, schemaVersion = defaultVersion) => {
+const validate = (instance, schemaVersion = defaultSchemaVersion) => {
     let errors = [];
     let warnings = [];
 
-    const schema = getSchema(schemaVersion)
+    const schema = this.getSchema(schemaVersion)
 
@@ -195,3 +239,3 @@ // When errors against the schema are found, you don't want to continue verifying the NFT
 
-This package uses the `validator` function explained in the [previous section](#token-metadata-validator).
+This package uses the `Validator` class explained in the [previous section](#token-metadata-validator).
 
@@ -198,0 +242,0 @@ ### Interface

tests/validator/validator.test.js

@@ -20,4 +20,3 @@ /*-
  */
-const { validator } = require('../../validator/index');
-const { defaultVersion } = require('../../validator/schemas');
+const { Validator, defaultSchemaVersion } = require('../../validator/index');
 const validMetadata = require('./data/valid-HIP412.json');
@@ -29,6 +28,7 @@
         // Arrange
+        const validator = new Validator();
         let metadata = JSON.parse(JSON.stringify(validMetadata));
 
         // Act
-        const schemaProblems = validator(metadata, defaultVersion);
+        const schemaProblems = validator.validate(metadata, defaultSchemaVersion);
 
@@ -44,6 +44,7 @@ // Assert
         // Arrange
+        const validator = new Validator();
         let metadata = JSON.parse(JSON.stringify(validMetadata));
 
         // Act
-        const schemaProblems = validator(metadata, "1.0.0");
+        const schemaProblems = validator.validate(metadata, "1.0.0");
 
@@ -57,6 +58,7 @@ // Assert
         // Arrange
+        const validator = new Validator();
         let metadata = JSON.parse(JSON.stringify(validMetadata));
 
         // Act
-        const schemaProblems = validator(metadata);
+        const schemaProblems = validator.validate(metadata);
 
@@ -72,2 +74,3 @@ // Assert
         // Arrange
+        const validator = new Validator();
         let metadataCopy = JSON.parse(JSON.stringify(validMetadata));
@@ -86,3 +89,3 @@ let metadata = {
         // Act
-        const validationResults = validator(metadata, defaultVersion);
+        const validationResults = validator.validate(metadata, defaultSchemaVersion);
 
@@ -98,2 +101,3 @@ // Assert
         // Arrange
+        const validator = new Validator();
         let metadataCopy = JSON.parse(JSON.stringify(validMetadata));
@@ -114,3 +118,3 @@ let metadata = {
         // Act
-        const validationResults = validator(metadata, defaultVersion);
+        const validationResults = validator.validate(metadata, defaultSchemaVersion);
 
@@ -124,2 +128,3 @@ // Assert
         // Arrange
+        const validator = new Validator();
         let metadataCopy = JSON.parse(JSON.stringify(validMetadata));
@@ -140,3 +145,3 @@ let metadata = {
         // Act
-        const validationResults = validator(metadata, defaultVersion);
+        const validationResults = validator.validate(metadata, defaultSchemaVersion);
 
@@ -143,0 +148,0 @@ // Assert

validator/index.js

@@ -20,21 +20,61 @@ /*-
  */
-const { schemaValidator, attributesValidator, localizationValidator, SHA256Validator } = require("./validators");
-const { getSchema, defaultVersion } = require("./schemas");
+const {
+  schemaValidator,
+  attributesValidator,
+  localizationValidator,
+  SHA256Validator,
+} = require("./validators");
 
-/**
- * Validate a metadata object against a schema. This function validates the instance respectively against
- * the schema validator, attributes validator, localization validator, and SHA256 validator. 
- * 
- * If the schema validator (jsonschema) returns errors, it's not possible to run the other validators because properties might be missing.
- * The other validators are executed when the schema validator only returns "additional property" erros which don't affect the execution of other validators.
- * 
- * @param {Object} instance - The JSON object to validate against a schema
- * @param {string} schemaVersion [schemaVersion = defaultVersion = 2.0.0] - The metadata schema version against which we want to validate our {instance}
- * @returns {Array} - Contains no, one, or multiple error objects that describe errors for the validated {instance}
- */
-const validator = (instance, schemaVersion = defaultVersion) => {
+const token_metadata_1_0_0 = require("./schemas/[e-mail]");
+const token_metadata_2_0_0 = require("./schemas/[e-mail]");
+const defaultSchemaVersion = "2.0.0";
+
+class Validator {
+  /**
+   * @param {Array<Object>} schemas
+   * @param {string} schemas.tag - The tag of the schema
+   * @param {Object} schemas.schemaObject - The schema object
+   */
+  constructor(schemas = []) {
+    this.schemaMap = new Map();
+    this.schemaMap.set("1.0.0", token_metadata_1_0_0);
+    this.schemaMap.set("2.0.0", token_metadata_2_0_0);
+
+    schemas.forEach((schema) => {
+      this.schemaMap.set(schema.tag, schema.schemaObject);
+    });
+  }
+
+  /**
+   * Retrieves correct schema for the requested HIP412 metadata schema version.
+   * If the version doesn't exist, it will return the default schema version "2.0.0".
+   *
+   * @param {string} version - The schema version to load.
+   * @return {Object} - Returns a json schema JSON object.
+   */
+  getSchema(version) {
+    const validVersion = this.schemaMap.has(version);
+    if (validVersion) {
+      return this.schemaMap.get(version);
+    }
+
+    return this.schemaMap.get(defaultSchemaVersion);
+  }
+
+  /**
+   * Validate a metadata object against a schema. This function validates the instance respectively against
+   * the schema validator, attributes validator, localization validator, and SHA256 validator.
+   *
+   * If the schema validator (jsonschema) returns errors, it's not possible to run the other validators because properties might be missing.
+   * The other validators are executed when the schema validator only returns "additional property" erros which don't affect the execution of other validators.
+   *
+   * @param {Object} instance - The JSON object to validate against a schema
+   * @param {string} schemaVersion [schemaVersion = defaultSchemaVersion = 2.0.0] - The metadata schema version against which we want to validate our {instance}
+   * @returns {Array} - Contains no, one, or multiple error objects that describe errors for the validated {instance}
+   */
+  validate(instance, schemaVersion = defaultSchemaVersion) {
     let errors = [];
     let warnings = [];
 
-    const schema = getSchema(schemaVersion)
+    const schema = this.getSchema(schemaVersion);
 
@@ -46,8 +86,8 @@ // When errors against the schema are found, you don't want to continue verifying the NFT
     if (schemaProblems.errors.length > 0) {
-        errors.push(...schemaProblems.errors);
+      errors.push(...schemaProblems.errors);
 
-        return {
-            errors,
-            warnings
-        }
+      return {
+        errors,
+        warnings,
+      };
     }
@@ -65,10 +105,11 @@
     return {
-        errors,
-        warnings
+      errors,
+      warnings,
     };
+  }
 }
 
 module.exports = {
-    validator,
-    defaultVersion
+    Validator,
+    defaultSchemaVersion
 };

No alert changes

Improved metrics

Total package byte prevSize

117736

increased by4.87%

Number of package files

49

increased by2.08%

Lines of code

2318

increased by4.98%

Number of lines in readme file

433

increased by11.31%

No dependency changes