Incompleteness in string formats documentation, potentially misleading

Question

Hello guys,I recently stumbled upon an incompleteness in Swagger OpenAPI docs that's potentially dangerous.Please refer to String Formats section here:&nbsp;https://swagger.io/docs/specification/v3_0/data-models/data-types/#stringsThe documentation states the following: `OpenAPI defines the following built-in string formats: date, date-time, password, byte, binary`. The way it's written suggests that as far as the standard goes, this list is complete and there is no obligation to respect any other format.However, that's not exactly true. We can look at https://spec.openapis.org/registry/format/ to see that there are more formats, strictly defined by the spec.Moreover, that section "Considerations" from the above document states: 'If tools choose to implement any format present in this registry, they SHOULD implement the format following the provided behavior.' - That sounds pretty&nbsp;BINDING to me. There are frameworks that auto-generate code with field types and validations based on that ruleset, provided the format is indicated for strings, e.g. https://github.com/kora-projects/kora - and they are doing the right thing as prescribed by the standard, based on the above document.Ont the other hand, there are companies that seemingly don't know about the string format ruleset, and include data incompatible with their own spec in their hiring process challenges&nbsp;E.g. employment code challenge from a certain startup:&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; purchaseTime:&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; description: The time of the purchase printed on the receipt. 24-hour time expected.&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; type: string&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; format: time &nbsp;&lt;-------&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; example: "13:01" &lt;-------https://github.com/fetch-rewards/receipt-processor-challenge/blob/main/api.yml#L82-L84Data example.https://github.com/fetch-rewards/receipt-processor-challenge/blob/main/examples/morning-receipt.json#L4&nbsp;I bet you anything that they don't have a clue about that because they read the first document, and missed the second (educated guess), but it's hard to blame them because it's just as I did initially.The result - no job for me. As I said I don't blame them, because your docs is ridiculous. So I decided I need to communicate this issue to you.Fix your docs please, my suggestion would be:Copy this link: https://spec.openapis.org/registry/format/And paste it in String Formats section here: https://swagger.io/docs/specification/v3_0/data-models/data-types/#stringsThank you in advance!

codekrolik2 · Answer

The string format in question: https://spec.openapis.org/registry/format/time.html

Forum Discussion

Recent Discussions

Related Content