Merge pull request #72 from shashank1010/change/improve-extendDraft-documentation

change: add an example to overwrite a formatter

Author: sagold

README.md

@@ -1057,6 +1057,68 @@ const myDraft = extendDraft(draft2020, {
 });
 ```
 
+
+### Overwrite a format validator
+The built-in format validators may not always align with your specific requirements. For instance, you might need to validate the output of an `<input type="time" />`, which produces values in formats like `HH:MM` or `HH:MM:SS`. In such cases, you can customize or overwrite the format validators to suit your needs using `extendDraft`
+<details>
+<summary>Example of overwriting a format validator</summary>
+
+```ts
+import { extendDraft, draft2020 } from "json-schema-library";
+
+/**
+ * A Regexp that extends http://tools.ietf.org/html/rfc3339#section-5.6 spec.
+ * The specification requires seconds and timezones to be a valid date format.
+ * 
+ * matchTimeSecondsAndTimeOptional matches:
+ * - HH:MM:SSz
+ * - HH:MM:SS(+/-)HH:MM
+ * - HH:MM:SS
+ * - HH:MMz
+ * - HH:MM(+/-)HH:MM
+ * - HH:MM
+ */
+const matchTimeSecondsAndTimeOptional = 
+    /^(?<time>(?:([0-1]\d|2[0-3]):[0-5]\d(:(?<second>[0-5]\d|60))?))(?:\.\d+)?(?<offset>(?:z|[+-]([0-1]\d|2[0-3])(?::?[0-5]\d)?)?)$/i;
+    
+
+const customTimeFormatDraft = extendDraft(draft2020, {
+  formats: {
+    // This example extends the default time formatter which validates against RFC3339
+    time: ({ node, pointer, data }) => {
+        const { schema } = node;
+        if (typeof data !== "string" || data === "") {
+            return undefined;
+        }
+
+        // Use the Custom Regex to validate the date and time.
+        const matches = data.match(matchTimeSecondsAndTimeOptional);
+        if (!matches) {
+            return node.createError("format-date-time-error", { value: data, pointer, schema });
+        }
+
+        // leap second
+        if (matches.groups.second === "60") {
+          // Omitted the code here for brevity.
+        }
+
+        return undefined;
+    },
+
+  },
+});
+
+const { errors, valid } = compileSchema({
+    type: "string",
+    format: "time",
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+}, { drafts: [customTimeFormatDraft]}).validate("15:31:12");
+
+console.assert(valid, errors.at(0)?.message);
+```
+
+</details>
+
 ### Keyword
 
 **Keywords** hold the main logic for JSON Schema functionality. Each `Keyword` corresponds to a JSON Schema keyword like `properties`, `prefixItems`, `oneOf`, etc and offers implementations to `parse`, `validate`, `resolve` and `reduce`. Note that support for each implementation is optional, dependending on the feature requirements. The main properties of a `Keyword`: