From 595a9a90b71d95f9acdd207d2eff874a1420c7bc Mon Sep 17 00:00:00 2001 From: chris48s <chris48s@users.noreply.github.com> Date: Sat, 23 Dec 2023 00:20:10 +0000 Subject: [PATCH] link to mterczynski.pl/joi-schema-generator in validation docs (#9700) --- doc/input-validation.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/input-validation.md b/doc/input-validation.md index c2fbac2e60..04ec47a62f 100644 --- a/doc/input-validation.md +++ b/doc/input-validation.md @@ -24,6 +24,8 @@ When we receive input data from an upstream API, we perform input validation to: - We don't need to validate characteristics we don't rely on. For example, if we're just going to render a version on a badge with the same exact value from the API response and do not need to sort or transform the value, then it doesn't matter what format the version number is in. We can use a very relaxed schema to validate in this case, e.g. `Joi.string().required()` +- http://mterczynski.pl/joi-schema-generator/ is a tool that can be used to reverse engineer a schema from an API response. This can be a great starting point to tweak from. If using this as a starting point, remember to remove fields we don't rely on to render a badge. + - If theory (docs) and practice (real-world API responses) conflict, real-world outputs take precedence over documented behaviour. e.g: if the docs say version is a semver but we learn that there are real-world packages where the version number is `0.3b` or `1.2.1.27` then we should accept those values in preference to enforcing the documented API behaviour. - Shields is descriptive rather than prescriptive. We reflect the established norms of the communities we serve. -- GitLab