Query component schema carries document-level JSON Schema metadata from the specification

[kudima03]

Summary

PureQLQueryDocumentTransformer strips definitions and $schema from the specification root before emitting it as the Query component, but leaves $id and PureQL's version in place. Both end up in the generated OpenAPI document, where they do not belong on a component schema.

Reproduction

Feed the transformer the published specification and serialize the document:

string spec = File.ReadAllText("PureQL-Specification.json"); // 0.1.0-preview.0.5.0
OpenApiDocument document = new OpenApiDocument();
await new PureQLQueryDocumentTransformer(spec)
    .TransformAsync(document, null!, CancellationToken.None);
string json = await document.SerializeAsJsonAsync(OpenApiSpecVersion.OpenApi3_1);

Actual output

"Query": {
  "$id": "https://github.com/kudima03/PureQL-Specification/releases/download/0.1.0-preview.0.5.0/PureQL-Specification.json",
  "title": "PureQL specification",
  "required": ["from", "select"],
  "type": "object",
  "properties": { "...": "..." },
  "unrecognizedKeywords": {
    "version": "0.1.0-preview.0.5.0"
  }
}

Impact

$id — under JSON Schema 2020-12 (which OpenAPI 3.1 component schemas follow) $id establishes a new base URI for the subschema. Every pointer the transformer rewrote to #/components/schemas/... inside Query therefore resolves against the specification's release URL rather than the OpenAPI document, i.e. to https://github.com/.../PureQL-Specification.json#/components/schemas/booleanReturning, where no such component exists. Lenient renderers such as Scalar ignore the base and still display the schema; strict validators fail to resolve the references.

version — not a JSON Schema keyword, so Microsoft.OpenApi does not recognise it and re-emits it wrapped in an unrecognizedKeywords object. The published document ends up with a key that appears in neither the specification nor OpenAPI.

Notes

Apart from these two keys the transformation is faithful: all 162 definitions of 0.1.0-preview.0.5.0 are emitted, no $ref is left dangling, and constraint keywords (format, minimum, minLength, minItems, default, const, enum) survive the Microsoft.OpenApi round-trip intact. The existing test suite exercises only a hand-written excerpt whose root has no $id or version, which is why neither key is currently observed.

Affects the transformer as of 2f84856.