Use of non-standard `"format"`

[A5rocks]

In quite a few places (ctrl+f reports 448 times in openapi.json) the specification uses "format": "snowflake". While this is technically valid, the JSON schema specification states:

Save for agreement between parties, schema authors SHALL NOT expect a peer implementation to support such custom format attributes.

(I found this while trying to see if "snowflake" is a valid format.... it isn't.)

Maybe use "pattern" instead? Unless this is intentional, of course.

[mbialecka]

Having specialized format for such a widely used field type should help with code generation or validations, though it requires some customization. Having just "pattern" wouldn't allow for creating custom type alias reliably. We may consider adding pattern, but it would be an addition, not a replacement of format. I'm curious to see some use cases that would benefit from adding pattern.

[A5rocks]

I think more accurately representing the input and output formats is always a benefit.

For what it's worth, with my own personal project for JSON schemas for the API (though focused around the gateway) I used a seperate schema for "snowflake" so that people could easily override it. This complicates e.g. nullable snowflakes a little, but not much. Compare:

{"type": ["null", "string"], "format": "snowflake"}

To this:

{"oneOf": [{"type": "null"}, {"$ref": "#/components/schemas/Snowflake"}]}

[Kiuhbit]

I'm willing to bet that using a non-standard format means that lots of tools won't be able to interpret it properly, which is the whole point of releasing the actual API spec file instead of just human-readable docs.

[dawgcodes]

mhm you are right in any case 🤣

[mbialecka]

updated snowflake type handling

[danny-may]

@mbialecka would the standard int64 format be better for the format of the SnowflakeType type? It has wider support and tools will be able to implement language specific optimisations by treating it as a number rather than a string with a regex pattern.

[mbialecka]

Snowflakes are returned as strings and int64 is not a standard format for strings.

[Kiuhbit]

There is a good reason not to store snowflakes as int64s: many tools represent json numbers as 64 bit floating point numbers which cannot represent all possible 64 bit integer values (for example, the very widely used jq tool is guilty of this). I think the Twitter API returns both a number and a string for this reason.

[A5rocks]

It has wider support and tools will be able to implement language specific optimisations by treating it as a number rather than a string with a regex pattern.

You can probably PR in support for integer-looking strings to the tools you use.