Problematic support of multiple schema versions when using JsonSchemaCredential

[antonio-ivanovski]

While implementing support for JsonSchemaCredential I have stumbled on implementation issue that I have not foreseen at the beginning. Namely it is the JSON Schema versions supports for the jsonSchema property.

Let me explain.
From the spec, the JsonSchemaCredential document requires the credentialSchema property to be exactly:

{
  "id": "https://www.w3.org/ns/credentials/json-schema/v2.json",
  "type": "JsonSchema",
  "digestSRI": "sha384-S57yQDg1MTzF56Oi9DbSQ14u7jBy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCrW"
}

Fetching "https://www.w3.org/ns/credentials/json-schema/v2.json" gives the following schema for jsonSchema:

"jsonSchema": {
  "anyOf": [
    {
      "$ref": "https://json-schema.org/draft/2020-12/schema"
    },
    {
      "$ref": "https://json-schema.org/draft/2019-09/schema"
    },
    {
      "$ref": "http://json-schema.org/draft-07/schema"
    }
  ]
}

As you can see, the schema itself is referencing all the recommended JSON Schema versions by spec (draft-7, 2019-09, 2020-12).

I am using Ajv as the most standard JSON Schema library for JS, and for the support of 2020-12 version it has a note (https://ajv.js.org/json-schema.html#draft-2020-12) that it is not compatible with older schemas. When using this and when the schema is being compiled, it is failing to load the 2019-09 and draft-07 schemas over and over again entering into endless loop. This is because this schemas as not being expected and not considered meta schemas.

I am still not able to find workaround for this issue for using Ajv. I am considering switching to hyperjump-io/json-schema as it seems to support this.

Before doing switch or another hacky workaround, it is very suspicious to me that the Ajv team that has focused so much on JSON Schema would make such limiting design decision when not being required. My concern is that such schemas may be considered invalid.

Can you please clarify the support of all these schema versions?
Maybe it makes sense to make the jsonSchema field be just an object schema and let the implementations try to compile the contents it.

[decentralgabe]

Can you please clarify the support of all these schema versions?

Only 2020-12 is required per the spec, the rest are optional. When you are using any specific schema you must choose one, hence the anyOf construct.

The constraint is that we need a way to require that one of these three drafts of json schema are in use. If you have a suggestion to guarantee this programmatically in an alternative manner, I'm open to it. Perhaps we can present three different URLs to enable each option separately.

Alternatively the language can be weakened to be RECOMMENDED to use https://www.w3.org/ns/credentials/json-schema/v2.json though that would not be optimal.

[antonio-ivanovski]

Only 2020-12 is required per the spec, the rest are optional. When you are using any specific schema you must choose one, hence the anyOf construct.

This is the issue itself. For the json schema parser to verify that the particular schema is of particular version, it will need to load that particular version of the meta schema and verify using that version. This leads to issue because schema validator for 2020-12 needs to support legacy schemas and be backwards compatible with 2019-09 and draft-07. Currently this is not the case for Ajv the de facto JSON Schema validation library that every project will use.

I don't think the intended purpose of meta schemas (2020-12, 2019-09, draft-07, others) is for them to be used as values for properties other then the root $schema.

The constraint is that we need a way to require that one of these three drafts of json schema are in use. If you have a suggestion to guarantee this programmatically in an alternative manner, I'm open to it. Perhaps we can present three different URLs to enable each option separately.

This requirement is in the spec itself, and while at first glance it seems nice for the credentialSchema feature to work in recursion and validate the schema itself, it ends up being anti-pattern in itself. The developer will get the contents of the jsonSchema and try to validate with it. If it is not one of the supported/required JSON schema versions, it will fail.

Proposals

1. Replace the complex requirement for jsonSchema with simple requirements that the value shall be an object and it to be required.
2. Remove the support for legacy JSON Schema versions (2019-09 and draft-07). If there is constant mentions and suggestions that legacy version can be used, their deprecation and removal will be much more painful once this feature is widely used.
3. Maybe introduce the JSON Schema version inside the credentialSchema. This can either be additional property "jsonSchemaVersion": "2020-12" or part of the "type": "JsonSchema-2020-12". Think this brings two benefits to the table, first being the ability to verify the contents of JsonSchemaCredential with particular JSON Schema version. Second being that it lets the developers know what schema is expected from downloading the contents of the id url.

[decentralgabe]

@antonio-ivanovski I'm supportive of these changes (1 and 2), I'm not certain about 3--the version should be self evident if 1 and 2 are done. Are you able to make a PR? Unfortunately, my bandwidth is limited at the moment.