Validation fails for schemas when used in mixed API context

[naz]

Issue Summary

Data validation cashes schema definition from single API which leads to incorrect validation results. In other words, valid data for v3 API is getting validated against v2 schema.

To Reproduce

1. Validate post resource data against v2 schema

await jsonSchema.validate({
    data: {
        posts: [{updated_at: '2020-10-02', title: 'whatever'}]
    },
    schema: `posts-edit`,
    version: 'v2'
});

2. Validate posts which is only valid in v3 API (add email_subject field)

await jsonSchema.validate({
    data: {
        posts: [{updated_at: '2020-10-02', email_subject: 'only available in canary}]
    },
    schema: `posts-edit`,
    version: 'canary'
});

3. Validation error happens even though email_subject is a valid field for canary/v3 schemas.

Expected behavior is - validation should always match schema definition and not throw errors for valid data.

The cause for a bug is schema caching which done on validator/ajv level.

Technical details:

• Ghost Version: 3.35
• Node Version: 12
• Browser/OS: Ubuntu/FF(latest)
• Database: MySQL 5.7

[naz]

There were couple approaches considered as a fix:

1. Having separate admin-api-validator instance per API - this would ensure schemas are never mixed in the cache.
2. Use additional prefix/postfix when identifying $id in schema

1st approach pros/cons

pros:

• no need to modify schemas
• no maintenance for prefix/postfix when new version is released

cons:

• package API needs to change to create a separate instance of ajv validator
• need to change Ghost core to use new API
• adds burden on the client user to "remember" to have a separate instance per API, and not being able to retreive/validate schemas on the same validator instance (unfriendly dev-experience imo)

2nd approach pros/cons

pros:

• no changes to API or clients
• keeps full functionality and single interface to access schemas/validations form any API version

cons:

• need to maintain API prefix/postfix in the schema when creating new schema version folder

Given that the con from 2nd approach only happens 1 time a year (during new version release) and is pretty straight forward search/replace will go down this path. Also, there's possibility to automate this with a script if it's ever painful! IMO, keeping friendly, no "hidden tricks" package api and less changes in Ghost core far outweighs small maintenance burden.

[naz]

Considerations around prefix or postfix naming change

There's not much difference in either approach. The only reason going with postfix notation $id: "{resource}.{version}" e.g.: "$id": "labels.canary" is to avoid regressions in existing use-case where error message is formed here.

[naz]

For reference "$id" property naming conventions for JSON Schema - https://json-schema.org/understanding-json-schema/structuring.html#the-id-property. There is no specific convention enforced except:

The $id property should never be the empty string or an empty fragment (#), since that doesn’t really make sense.

And it's primary goal is:

The $id property is a URI-reference that serves two purposes:

• It declares a unique identifier for the schema.
• It declares a base URI against which $ref URI-references are resolved.