add S.raw

[aboutlo]

🚀 Allow injecting a raw JSON directly in fluent-schema

Motivation

A few users asked:

• add custom implementation related to AJV or other JSON Schema validation tools.
• inherited schema from a JSON schema and not our wrapper

ref. #51 #16 #47

Examples

S.object()
  .prop('foo', S.integer())
  .prop('myKeyword', S.raw({true})

S.definition(S.raw({ foo: 'bar'}))

S.object().prop('foo').extend(S.raw('{"bar": { "type": "string"}}'))

In order to implement that we need to implement a parser to build the fluent-schema internal data structure based on the raw JSON.

https://github.com/fastify/fluent-schema/blob/master/src/ObjectSchema.js#L13

 {
  type: 'object',
  definitions: [],
  properties: [],
  required: [],
}

[firasdib]

We currently use fastify with fluent schema which works well, but we've hit a snag with the openapi spec that we try to generate from the json schema, when it comes to null values. If we want to return say a string or null, we have to do something along the lines of S.anyOf([S.string(), S.null()]) which generates the following openapi spec:

anyOf:
   - type: 'null'
   - type: string

This is unfortunately invalid. Instead, we should be setting the type to string, with the nullable option to true (see https://swagger.io/docs/specification/data-models/data-types/).

My understanding is that this is a clash between the JSON schema specification and the openapi specification.

Do you think using S.raw() could bridge this gap, or is this something we won't be able to get around?

[aboutlo]

Rather than use S.anyOf([S.string(), S.null()])
We could have:

S.object()
  .prop('foo', S.raw({type: string, nullable:true}))

But then if you are using AJV to validate you will face other issues: ajv-validator/ajv#486

As you said, currently, there are discrepancies between Swagger and JSON Schema draft 7.
AFAIU the JSON Schema 2019-09 could fix your issue but the environment is changing: https://phil.tech/2019/09/07/update-openapi-json-schema/

I'm interested in your use cases. I would like to write in fluent-schema and having my endpoints documented with Swagger UI. Is that your goal?

[firasdib]

According to the AJV docs they should have support for nullable.

Yes, I have the same goal as you.