Support JSON-schema assertion in configurable rules

[RomanHotsiy]

Is your feature request related to a problem? Please describe.

Some people maintain JSON schemas to validate some parts of OpenAPI. We don't have a way to use them.

Describe the solution you'd like

I would like to add support for json schema assertion for our configurable rules. It may look like this:

rule/info-metadata-check:
  subject:
    type: Info
    property: x-metadata
  message: Metadata should match the schema.
  assertions:
    json-schema:
      $ref: ./metadata-schema.json

Describe alternatives you've considered

Right now it is possible to achieve using custom assertions/rules via plugin: https://redocly.com/docs/cli/rules/configurable-rules#custom-function-example

Additional context

Reported in Write the Docs slack: https://writethedocs.slack.com/archives/C4EPE8332/p1738793608940479

[tatomyr]

@RomanHotsiy from the context of the attached conversation I understand it's more about linting standalone JSON schemas themselves rather than linting OAS using JSON schemas, isn't it?

[hawkeyexl]

@tatomyr Yes, exactly. (Hi, I'm the original reporter in that thread.) I want to lint my standalone schemas that aren't associated with any API definitions. I can do this today in Spectral with their custom rules, but I can't in Redocly.

[tatomyr]

@hawkeyexl we first need to determine whether a document is a JSON schema. Additionally, identifying which draft it follows would be helpful. Would it be sufficient to assume a document is a JSON schema if it contains a $schema field with a link to the draft, what do you think?

[hawkeyexl]

I think that's reasonable. That's how VSCode's JSON Schema support works, too.

On Fri, Feb 7, 2025, 12:11 PM Andrew Tatomyr @.***> wrote:

@hawkeyexl https://github.com/hawkeyexl we first need to determine whether a document is a JSON schema. Additionally, identifying which draft it follows would be helpful. Would it be sufficient to assume a document is a JSON schema if it contains a $schema field with a link to the draft, what do you think?

— Reply to this email directly, view it on GitHub https://github.com/Redocly/redocly-cli/issues/1886#issuecomment-2644032026, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABHX2FZT35THFGDVWIBI6AT2OUHOZAVCNFSM6AAAAABWSUM5LSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMNBUGAZTEMBSGY . You are receiving this because you were mentioned.Message ID: @.***>

[tatomyr]

Good. @RomanHotsiy will you update the feature request, or would you prefer me to open a separate issue?

[jeremyfiel]

be very careful with following anything VSC does with JSON Schema.. they are not the most compliant participant in the JSON Schema ecosystem, particularly around the $id and $schema keywords

[jeremyfiel]

This feature is nice in theory, but redocly needs an entry point which is one of openapi, arazzo, overlay, or asyncapi files. It doesn't enter into any JSON Schema definition directly.

Is this feature request going to add that behavior?

@RomanHotsiy regarding the assertion, $schema is not required by the JSON Schema spec, so some sort of default must be applied to a schema without the $schema declaration and some consideration should be given to the OAS/Async/Overlay/Arazzo entry point.

draft-04 (related to OAS 3.0.x)

It is RECOMMENDED that schema authors include this keyword in their schemas.

---

draft-07 (related to Async)

No explicit recommendation

---

draft-2020-12 (Overlay/Arazzo/OAS 3.1.x)

The "$schema" keyword SHOULD be used in the document root schema object, and MAY be used in the root schema objects of embedded schema resources. It MUST NOT appear in non-resource root schema objects. If absent from the document root schema, the resulting behavior is implementation-defined.