By dafeder on
Change record status: 
Published (View all published change records)
Project: 
DKAN
Introduced in branch: 
4.x
Introduced in version: 
4.1.0
Description: 

DKAN has been long overdue for an update to one of its major underlying tools for working with JSON: Opis JSON Schema Library. For many years we have been on v1, which:

  • is no longer maintained
  • is causing more and more deprecation errors with new versions of PHP
  • is incompatible with the increasingly-popular mpc/sdk package (a dependency of the MCP Server module)
  • does not support JSON Schema draft 2022-12, which is the basis for DCAT-US 3.0

(DKAN does not ship with any DCAT-US 3.0 features yet, but we plan to soon and you may wish to implement parts of the new schema yourself.)

The default schemas that ship with DKAN, however, are based on JSON Schema draft 4. Draft 4 was not even supported in Opis v1, but we could "get away" with more draft 4 conventions and only minimally changed the DCAT-US 1.1 schemas from their original versions. With Opis v2 we have to be a bit more strict, and if you have overridden your downstream schemas with custom versions, you may need to update these as well to conform to the new validator.

You should see a warning when you run database updates for 4.1.0 if your schemas do not validate. You will also see an error on the Drupal status page until they are corrected.

The migration steps for any custom downstream schemas:

  1. Any sub-schemas declared as draft-04 must be updated to 06 or else remove the schema declaration. In DKAN's default schemas, for instance, this would apply to the "publisher" sub-schema within dataset.json.
  2. Bump "$schema" declaration to "http://json-schema.org/draft-07/schema#", or remove schema declaration
  3. Rename "schema" → "$schema"
  4. Rename "id" → "$id" (renamed at the draft-04 → draft-06 boundary)
  5. Use absolute URIs for "$id" values (v2 rejects relative URIs at the schema root)
  6. If using "exclusiveMinimum" / "exclusiveMaximum" as boolean modifiers, switch to numeric values (draft-06+ semantics)

Note that you may not see any errors thrown if you do not explicitly declare a JSON Schema draft in your schema's root. If you see no errors after upgrading, you may safely ignore -- though migrating to Draft 07 or higher eventually is recommended.

For more information, see the original pull request on GitHub (DKAN not yet using Drupal.org issues or MR workflow)

Impacts: 
Site builders, administrators, editors
Module developers