docs: Extend TypeBox documentation

[Jnig]

Hi,

the following PR closes #3421 and adds additional documentation how to use TypeBox with fastify v4.

Checklist

• documentation is changed or added
• commit message and code follows the Developer's Certification of Origin
  and the Code of conduct

[RafaelGSS]

would be great to inform in which cases specifying the keywords is needed.

[Jnig]

Wow that was quick :) I've added the following informations:

TypeBox uses the properties kind and modifier internally. Those are not strictly valid JSON schema and will throw an AJV error. To remove the error it's either necessary to omit the properties by using Type.strict() or use the AJV options for adding custom keywords.

[Jnig]

cc @sinclairzx81 :)

[sinclairzx81]

Type.strict() should be capitalized as Type.Strict()

[sinclairzx81]

Possibly rephrase

Those are not strictly valid JSON schema and will throw an AJV error

as

These properties are not strictly valid JSON schema which will cause AJV to throw an invalid schema error

[Jnig]

Thanks! Comments are incorporated now :)

[sinclairzx81]

@Jnig Looks good to me. Nice work :)

[RafaelGSS]

@sinclairzx81 I'm assuming that those changes are also necessary if the user would like to work with typebox (even without type-providers) on v4, is that right?

I'm wondering if we can do something to make it built-in in order to avoid the needs of the user to set up it by themselves.

[sinclairzx81]

@RafaelGSS Hi. The requirement to specify the kind and modifier keywords is specific to AJV version 7 onwards which mandates strict keyword checking by default. Note, this is unrelated to the Type Provider implementation which is tied to TypeScript types only.

There's only two options I can think of to make this automatic for users:

1. Automatically configure the AJV compiler in Fastify for the kind and modifier keywords.
2. Automatically serialize / deserialize schemas prior to passing over to the AJV compiler.

Option 1 is not really workable as it would require Fastify to have knowledge of an external libraries internals. But Option 2 could be worth exploring.

The Type.Strict() function in TypeBox essentially does a JSON.parse(JSON.stringify(schema)) to strip out these properties. The kind and modifier properties are defined as Symbol values specifically to permit this logic, with this largely in response to AJV 7's decision to mandate strict checks.

In the context of Fastify, internally implementing this serialize / deserialize pass to clean schemas prior to AJV compilation may prove workable given that schema compilation only happens once at start up. Such a step would permit users an escape hatch to include additional metadata on their schemas, (with the rule being that the metadata MUST NOT be serializable to JSON). I wouldn't expect the serialize/deserialize step to be much of an added cost over the existing AJV compilation pass (tho it would be worth measuring for larger schemas).

Hope this helps!

[RafaelGSS]

Let's explicitly define the version of ajv which those settings are needed.

[Jnig]

@sinclairzx81 I'm assuming that those changes are also necessary if the user would like to work with typebox (even without type-providers) on v4, is that right?

I'm wondering if we can do something to make it built-in in order to avoid the needs of the user to set up it by themselves.

Having a solution which works without additional configuration would be perfect. Than it would be the same as for fastify 3.

[RafaelGSS]

LGTM.

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.