Custom Keyword Errors

[mgrist]

Info

Node.js v22.12.0
JSON Schema Draft 2019-09
json-schema 1.11.0
Used for Validation of Amazon SP-API Product Data
Code to reproduce this can be found at this Gist.

Details

validator.ts

import maxUniqueItemsKeyword from "./keywords/maxUniqueItemsKeyword";
import minUniqueItemsKeyword from "./keywords/minUniqueItemsKeyword";
import { readFileSync } from "fs";
import {
  registerSchema,
  validate,
  OutputFormat,
} from "@hyperjump/json-schema/draft-2019-09";
import {
  addKeyword,
  defineVocabulary,
  loadDialect,
} from "@hyperjump/json-schema/experimental";

const customVocabularyId =
  "https://schemas.amazon.com/selling-partners/definitions/product-types/vocabulary/v1";
const schemaId =
  "https://schemas.amazon.com/selling-partners/definitions/product-types/schema/v1/COAT";
const metaSchemaId =
  "https://schemas.amazon.com/selling-partners/definitions/product-types/meta-schema/v1";

const schemaPath = "./schema.json";
const metaSchemaPath = "./meta_schema.json";
const payloadPath = "./variant_payload.json";

const outputFormat: OutputFormat = "BASIC";

addKeyword(maxUniqueItemsKeyword);

addKeyword(minUniqueItemsKeyword);

defineVocabulary(customVocabularyId, {
  maxUniqueItems: maxUniqueItemsKeyword.id,
  minUniqueItems: minUniqueItemsKeyword.id,
});

loadDialect(
    metaSchemaId,
  {
    "https://json-schema.org/draft/2019-09/vocab/core": true,
    "https://json-schema.org/draft/2019-09/vocab/applicator": true,
    "https://json-schema.org/draft/2019-09/vocab/validation": true,
    "https://json-schema.org/draft/2019-09/vocab/meta-data": true,
    "https://json-schema.org/draft/2019-09/vocab/format": true,
    "https://json-schema.org/draft/2019-09/vocab/content": true,
    [customVocabularyId]: true,
  },
  true
);

// Add meta schema
const metaSchemaJSON = JSON.parse(readFileSync(metaSchemaPath, "utf8"));
registerSchema(metaSchemaJSON, metaSchemaId);

// Add product type schema
const schemaTypeJSON = JSON.parse(readFileSync(schemaPath, "utf8"));
registerSchema(schemaTypeJSON, schemaId, metaSchemaId);

const payloadFile = readFileSync(payloadPath, "utf-8");
const payload = JSON.parse(payloadFile);

validate(schemaId, payload as any, outputFormat).then((result) =>
  console.log(result)
);

maxUniqueItemsKeyword.ts

import {
  SchemaDocument,
  AST,
  Anchors,
} from "@hyperjump/json-schema/experimental";
import { JsonNode, value } from "@hyperjump/json-schema/instance/experimental";
import { Browser as BrowserType, value as browserValue } from "@hyperjump/browser";

const id =
  "https://schemas.amazon.com/selling-partners/definitions/product-types/keyword/maxUniqueItems";

const compile = async (
  schema: BrowserType<SchemaDocument>,
  ast: AST,
  parentSchema: BrowserType<SchemaDocument>
) => {
  const maxUniqueItems = await browserValue(schema);
  // Extract selectors from parentSchema if available
  let selectors: any[] = [];
  try {
    const selectorsSchema = (await browserValue(parentSchema)) as any;
    selectors = selectorsSchema.selectors;
  } catch (e) {
    console.error(e);
  }

  return { maxUniqueItems, selectors };
};

const interpret = (
  compiledKeywordValue: any,
  instance: JsonNode,
  ast: AST,
  dynamicAnchors: Anchors,
  quiet: boolean,
  schemaLocation: string
) => {
  const { maxUniqueItems, selectors } = compiledKeywordValue;

  // Check if instance is an array
  if (instance.type !== "array") {
    console.log("returned true");
    return true; // Not applicable to non-arrays
  }

  // Process each item in the array
  let uniqueItems = [];
  for (const item of value(instance) as any[]) {
    let selectorCombination: { [key: string]: any } = {};

    // Extract selector values if selectors are defined
    if (Array.isArray(selectors) && selectors.length > 0) {
      for (const selector of selectors) {
        if (item[selector] !== undefined) {
          selectorCombination[selector] = item[selector];
        }
      }
    } else {
      // If no selectors are defined, use the entire item
      selectorCombination = { ...item };
    }

    uniqueItems.push(JSON.stringify(selectorCombination));
  }

  // Count occurrences of each unique combination
  const countMap = new Map();
  for (const item of uniqueItems) {
    countMap.set(item, (countMap.get(item) || 0) + 1);
  }

  // Check if any combination exceeds maxUniqueItems
  for (const [_, count] of countMap) {
    if (count > (maxUniqueItems as number)) {
      instance.valid = false;
      return false;
    }
  }

  return true;
};

const maxUniqueItemsKeyword = { id, compile, interpret };

export default maxUniqueItemsKeyword;

Question

I've created this custom keyword, maxUniqueItems, which indicates the maximum number of items with the same combination of selector properties. I'm testing this with this test payload that exceeds the maxUniqueItems:

"list_price": [
    {
      "value": 100.0,
      "currency": "USD"
    },
    {
      "value": 100.0,
      "currency": "USD"
    }
  ]

When validating, it fails as I expect it to. However, the error messages are not descriptive at all. This is the result from the validation:

{
  "valid": false,
  "errors": [
    {
      "keyword": "https://json-schema.org/keyword/properties",
      "absoluteKeywordLocation": "https://schemas.amazon.com/selling-partners/definitions/product-types/schema/v1/COAT#/properties",
      "instanceLocation": "#",
      "valid": false
    }
  ]
}

How can I make the error more descriptive? The keyword and the absoluteKeywordLocation properties are vague and give little context. It would be great if it showed a more descriptive keyword location, keyword, and instance location so I could determine what and where the error is. For example, this error clearly tells me it's the maxUniqueItems keyword causing an error, and it's stemming from the "list_price" property:

{
  "valid": false,
  "errors": [
    {
      "keyword": "https://schemas.amazon.com/selling-partners/definitions/product-types/keyword/maxUniqueItems",
      "absoluteKeywordLocation": "https://schemas.amazon.com/selling-partners/definitions/product-types/schema/v1/COAT#/properties/list_price/maxUniqueItems",
      "instanceLocation": "#",
      "valid": false
    }
  ]
}

[mgrist]

To make this even weirder, the validation works on some properties but not others. It doesn't give the error details when I tried with the list_price property. However, when I attempted with the model_name property, and I received a better error that told me the keyword and location of the error:

{
  valid: false,
  errors: [
    {
      keyword: 'https://schemas.amazon.com/selling-partners/definitions/product-types/keyword/maxUniqueItems',
      absoluteKeywordLocation: 'https://schemas.amazon.com/selling-partners/definitions/product-types/schema/v1/COAT#/properties/model_name/maxUniqueItems',
      instanceLocation: '#/model_name',
      valid: false
    },
    {
      keyword: 'https://json-schema.org/keyword/properties',
      absoluteKeywordLocation: 'https://schemas.amazon.com/selling-partners/definitions/product-types/schema/v1/COAT#/properties',
      instanceLocation: '#',
      valid: false
    }
  ]
}

[jdesrosiers]

I'll try to take a closer look tomorrow, but one thing I noticed immediately is that the meta-schema is missing "$recursiveAnchor": true. That could explain at least some of the problems you're seeing.

[jdesrosiers]

This is a bug. It should never report a properties error without saying what failed in the properties.

I was able to work out a minimal reproduction.

{
  "properties": {
    "list_price": {
      "maxUniqueItems": 1
    }
  },
  "allOf": [
    {
      "properties": {
        "list_price": {}
      }
    }
  ]
}

For some reason, the "list_price" in the allOf is causing the maxUniqueItems error to be suppressed.

The good news is that you can just move those constraints into /properties/list_price to work around the problem.

[jdesrosiers]

Unfortunately, I don't think it's going to be an easy fix and I won't be able to put any serious time into it for the next three months. In v1.9, I rewrote output handling to be more efficient. I'm sure that's when the bug was introduced. From what I've looked at so far, I suspect that there might not be a way to fix this problem with the new algorithm and I'm going to have to rethink the approach. As a temporary measure you can pin to v1.8 before the new algorithm was introduced. That should work, it'll just be a bit less efficient.

[mgrist]

No worries! At least it can validate correctly and tell me my payload is incorrect. I will test out v1.8 and see if that works. Efficiency isn't a concern for my app right now, so that will be okay. Thanks for taking the time to check this out.

[jdesrosiers]

I came up with a solution, but I'm not ready to release it just yet. If you want early access, you can find it in the output branch. I'm confident the output functionality is solid, but changing the output algorithm meant refactoring the annotation functionality. That part's not quite ready, but that shouldn't be a problem for your needs. Also, I had to make some minor changes to the API for defining keywords, but it only applies to applicators and I don't think you're implementing any of those.

It shouldn't take much to finish the remaining work, but I'm out of time for now and not sure when I'll be able get it over the finish line, so I wanted to give you an update.

[jdesrosiers]

The fix is now published as v1.12.0.

[mgrist]

You are the GOAT. Thank you!!!