Coverage of definitions only referenced via $dynamicref

[ralfhandl]

OpenAPI 3.1 and greater defines a Schema Object which is an extension of JSON Schema 2020-12 in https://github.com/OAI/OpenAPI-Specification/blob/7bf50655066feef4240575b80ab4fcc6b5e1b3b9/src/schemas/validation/schema.yaml#L726-L731

$defs:
  schema:
    $comment: https://spec.openapis.org/oas/v3.2#schema-object
    $dynamicAnchor: meta
    type:
      - object
      - boolean

This definition is dynamically referenced several times using its $dynamicAnchor via $dynamicRef: '#meta' and never statically referenced.

It is reported as "not covered" despite being evaluated when validating instances and collecting schema coverage.

Is this a bug of the schema coverage tool, or a feature?

And if it is a feature of the schema coverage tool, is it a "bug" in our use of JSON Schema?

Side note: that definition is reported as covered if I statically reference it at least once, for example as

  components:
    $comment: https://spec.openapis.org/oas/v3.2#components-object
    type: object
    properties:
      schemas:
        type: object
        additionalProperties:
          $dynamicRef: '#meta'
          $ref: '#/$defs/schema' # just to satisfy schema coverage

This seems to work, with all "pass" test cases still passing, and all "fail" test cases still failing, but I'm no JSON Schema expert and can't judge whether referencing something both statically and dynamically is a problem, or whether "duplicating" the $dynamicAnchor by statically pulling it in via $ref has side effects or just works by accident here.

[jdesrosiers]

It's working the way it's supposed to. There's no way to cover those lines in schema.yaml when you start from schema-base.yaml and the schema is designed to work that way on purpose. schema.yaml#/$defs/schema exists as a default target for $dynamicRef: '#meta'. That default is overridden by the $dynamicAnchor: meta in schema-base.yaml.

The only way the default target is covered is if schema.yaml is used by itself. So, my suggestion is to add an additional one-off test that covers schema.yaml instead of schema-base.yaml.

test("schema.yaml schema test", async () => {
  // Hardcode this simple document instead of putting it in pass/fail directories because
  // documents in those folders get run against schema-base.yaml instead of schema.yaml.
  const oad = {
    // Also need to include required properties
    components: {
      schemas: {
        foo: {}
      }
    }
  };
  await expect(oad).to.matchJsonSchema("./src/schemas/validation/schema.yaml"); // <-- "schema.yaml" instead of "schema-base.yaml"
});