Custom String format

[imposimato]

Hi there! I noticed that examples using custom string format are being interpreted as errors

Is this a know issue?

"type": "Validation", "message": "unknown format \"country-code-2\" is used in schema at path \"#/properties/data/items/properties/location\"",

[codekie]

Currently, the only supported formats are:

    validator.addFormat('int32', { type: 'number', validate: FormatValidator.int32 });
    validator.addFormat('int64', { type: 'string', validate: FormatValidator.int64 });
    validator.addFormat('float', { type: 'number', validate: FormatValidator.float });
    validator.addFormat('double', { type: 'number', validate: FormatValidator.double });
    validator.addFormat('byte', { type: 'string', validate: FormatValidator.byte });

While the list of format-validators may be extended, it's unlikely that country-code validators will be part of it. When the OpenapiExamplesValidator-API will be officially released, there may be a method to add custom validators.

Does this answer your question?

[imposimato]

Yeah, it does answer my question! Thanks! However, checking the openapi docs https://swagger.io/docs/specification/data-models/data-types/#string The string can have any format, therefore I don't see why it is throwing this as error. I'll see if I can tweak this locally and maybe push a PR. Thanks again for your time!

[codekie]

Thank you, for pointing this out!

The underlying library used for the validation is ajv. I dug a little deeper and found this: https://github.com/ajv-validator/ajv/issues/466

Apparently, the reason for not ignoring unknown formats, is the following (which does make sense for a schema-validator):

The problem with simply ignoring anything is that you would not catch typos and you never know what is ignored. That’s the reason why default is not to ignore. Permissiveness of JSON Schema makes it very difficult to maintain schemas - can you imagine a programming language that ignores all statements and that it doesn’t know about? Well, it’s JSON Schema.

Unfortunately the option unknownFormats won't exist in future version of ajv anymore, so I won't use that. But I could add a command line option to add formats to ignore (eg. something like --ignore-format country-code-2).

[imposimato]

Hey! Thanks for getting back!

That would help a lot, but instead of an option like this why not a config file or param to add to package.json with options, something like an array of types to ignore in case of string? Currently we are using many custom string formats and I believe many users might be using as well.

Thanks!

[codekie]

I see your point. But instead of having a separate file just for the formats to ignore, I'd rather implement a configuration file (eg. something like .oevrc) which would contain the whole configuration for the validator. But that's a rather big deal and would take some time to implement.

The first step though, would be to add a variadic option (see commander) --ignore-formats (mind the --, if it's the last option before the filepath), anyways, because I wouldn't want any options in the configuration file that aren't as well available as command line parameter.

As a workaround, passing along a file with unsupported formats (newline-separated) then could be done with some shell-magic:

cat ignore-formats.txt | xargs -0 -R -1 -I % -t openapi-examples-validator --ignore-formats % -- openapi-with-unknown-formats.json

The first step I probably can provide soon, the configuration file will take a while as it's not on the immediate roadmap.

[imposimato]

That's brilliant!! Thanks for that man, appreciate! I'll keep an eye here! Have a good weekend!

[codekie]

The new version has been released