Custom string formats (#1186)

* Accept custom string formats via `additionalFormats` prop

Follow AJV extension pattern established for meta schemas and passthrough to AJV's addFormat method

* Wire additionalFormats prop

* additionalFormats → customFormats

* Fix and test custom format prop updates

* Update docs/validation.md

Co-Authored-By: pushred <[email protected]>

Author: pushred

docs/validation.md

@@ -47,6 +47,30 @@ render((
 >   received as second argument.
 > - The `validate()` function is called **after** the JSON schema validation.
 
+### Custom string formats
+
+[Pre-defined semantic formats](https://json-schema.org/latest/json-schema-validation.html#rfc.section.7) are limited. react-jsonschema-form adds two formats, `color` and `data-url`, to support certain [alternative widgets](form-customization.md#alternative-widgets). You can add formats of your own through the `customFormats` prop to your `Form` component:
+
+```jsx
+const schema = {
+  phoneNumber: {
+    type: 'string',
+    format: 'format-us'
+  }
+};
+
+const customFormats = {
+  'phone-us': /\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$/
+};
+
+render((
+  <Form schema={schema} 
+        customFormats={customFormats}/>
+), document.getElementById("app"));
+```
+
+Format values can be anything AJV’s [`addFormat` method](https://github.com/epoberezkin/ajv#addformatstring-name-stringregexpfunctionobject-format---ajv) accepts.
+
 ### Custom schema validation
 
 To have your schemas validated against any other meta schema than draft-07 (the current version of [JSON Schema](http://json-schema.org/)), make sure your schema has a `$schema` attribute that enables the validator to use the correct meta schema. For example:

src/components/Form.js

@@ -58,9 +58,10 @@ export default class Form extends Component {
     const { definitions } = schema;
     const formData = getDefaultFormState(schema, props.formData, definitions);
     const retrievedSchema = retrieveSchema(schema, definitions, formData);
+    const customFormats = props.customFormats;
     const additionalMetaSchemas = props.additionalMetaSchemas;
     const { errors, errorSchema } = mustValidate
-      ? this.validate(formData, schema, additionalMetaSchemas)
+      ? this.validate(formData, schema, additionalMetaSchemas, customFormats)
       : {
           errors: state.errors || [],
           errorSchema: state.errorSchema || {},
@@ -91,7 +92,8 @@ export default class Form extends Component {
   validate(
     formData,
     schema = this.props.schema,
-    additionalMetaSchemas = this.props.additionalMetaSchemas
+    additionalMetaSchemas = this.props.additionalMetaSchemas,
+    customFormats = this.props.customFormats
   ) {
     const { validate, transformErrors } = this.props;
     const { definitions } = this.getRegistry();
@@ -101,7 +103,8 @@ export default class Form extends Component {
       resolvedSchema,
       validate,
       transformErrors,
-      additionalMetaSchemas
+      additionalMetaSchemas,
+      customFormats
     );
   }
 
@@ -301,6 +304,7 @@ if (process.env.NODE_ENV !== "production") {
     transformErrors: PropTypes.func,
     safeRenderCompletion: PropTypes.bool,
     formContext: PropTypes.object,
+    customFormats: PropTypes.object,
     additionalMetaSchemas: PropTypes.arrayOf(PropTypes.object),
   };
 }

src/validate.js

@@ -3,6 +3,7 @@ import Ajv from "ajv";
 let ajv = createAjvInstance();
 import { deepEquals } from "./utils";
 
+let formerCustomFormats = null;
 let formerMetaSchema = null;
 
 import { isObject, mergeObjects } from "./utils";
@@ -167,19 +168,35 @@ export default function validateFormData(
   schema,
   customValidate,
   transformErrors,
-  additionalMetaSchemas = []
+  additionalMetaSchemas = [],
+  customFormats = {}
 ) {
+  const newMetaSchemas = !deepEquals(formerMetaSchema, additionalMetaSchemas);
+  const newFormats = !deepEquals(formerCustomFormats, customFormats);
+
+  if (newMetaSchemas || newFormats) {
+    ajv = createAjvInstance();
+  }
+
   // add more schemas to validate against
   if (
     additionalMetaSchemas &&
-    !deepEquals(formerMetaSchema, additionalMetaSchemas) &&
+    newMetaSchemas &&
     Array.isArray(additionalMetaSchemas)
   ) {
-    ajv = createAjvInstance();
     ajv.addMetaSchema(additionalMetaSchemas);
     formerMetaSchema = additionalMetaSchemas;
   }
 
+  // add more custom formats to validate against
+  if (customFormats && newFormats && isObject(customFormats)) {
+    Object.keys(customFormats).forEach(formatName => {
+      ajv.addFormat(formatName, customFormats[formatName]);
+    });
+
+    formerCustomFormats = customFormats;
+  }
+
   let validationError = null;
   try {
     ajv.validate(schema, formData);
@@ -198,7 +215,13 @@ export default function validateFormData(
     typeof validationError.message === "string" &&
     validationError.message.includes("no schema with key or ref ");
 
-  if (noProperMetaSchema) {
+  const unknownFormat =
+    validationError &&
+    validationError.message &&
+    typeof validationError.message === "string" &&
+    validationError.message.includes("unknown format");
+
+  if (noProperMetaSchema || unknownFormat) {
     errors = [
       ...errors,
       {
@@ -212,7 +235,7 @@ export default function validateFormData(
 
   let errorSchema = toErrorSchema(errors);
 
-  if (noProperMetaSchema) {
+  if (noProperMetaSchema || unknownFormat) {
     errorSchema = {
       ...errorSchema,
       ...{

test/Form_test.js

@@ -1979,6 +1979,53 @@ describe("Form", () => {
     });
   });
 
+  describe("Custom format updates", () => {
+    it("Should update custom formats when customFormats is changed", () => {
+      const formProps = {
+        liveValidate: true,
+        formData: {
+          areaCode: 123,
+        },
+        schema: {
+          type: "object",
+          properties: {
+            areaCode: {
+              type: "number",
+              format: "area-code",
+            },
+          },
+        },
+        uiSchema: {
+          areaCode: {
+            "ui:widget": "area-code",
+          },
+        },
+        widgets: {
+          "area-code": () => <div id="custom" />,
+        },
+      };
+
+      const { comp } = createFormComponent(formProps);
+
+      expect(comp.state.errorSchema).eql({
+        $schema: {
+          __errors: [
+            'unknown format "area-code" is used in schema at path "#/properties/areaCode"',
+          ],
+        },
+      });
+
+      setProps(comp, {
+        ...formProps,
+        customFormats: {
+          "area-code": /\d{3}/,
+        },
+      });
+
+      expect(comp.state.errorSchema).eql({});
+    });
+  });
+
   describe("Meta schema updates", () => {
     it("Should update allowed meta schemas when additionalMetaSchemas is changed", () => {
       const formProps = {

test/validate_test.js

@@ -163,6 +163,69 @@ describe("Validation", () => {
       });
     });
 
+    describe("validating using custom string formats", () => {
+      const schema = {
+        type: "object",
+        properties: {
+          phone: {
+            type: "string",
+            format: "phone-us",
+          },
+        },
+      };
+
+      it("should return a validation error if unknown string format is used", () => {
+        const result = validateFormData({ phone: "800.555.2368" }, schema);
+        const errMessage =
+          'unknown format "phone-us" is used in schema at path "#/properties/phone"';
+
+        expect(result.errors[0].stack).include(errMessage);
+        expect(result.errorSchema).to.eql({
+          $schema: { __errors: [errMessage] },
+        });
+      });
+
+      it("should return a validation error about formData", () => {
+        const result = validateFormData(
+          { phone: "800.555.2368" },
+          schema,
+          null,
+          null,
+          null,
+          { "phone-us": /\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$/ }
+        );
+
+        expect(result.errors).to.have.lengthOf(1);
+        expect(result.errors[0].stack).to.equal(
+          '.phone should match format "phone-us"'
+        );
+      });
+
+      it("prop updates with new custom formats are accepted", () => {
+        const result = validateFormData(
+          { phone: "abc" },
+          {
+            type: "object",
+            properties: {
+              phone: {
+                type: "string",
+                format: "area-code",
+              },
+            },
+          },
+          null,
+          null,
+          null,
+          { "area-code": /\d{3}/ }
+        );
+
+        expect(result.errors).to.have.lengthOf(1);
+        expect(result.errors[0].stack).to.equal(
+          '.phone should match format "area-code"'
+        );
+      });
+    });
+
     describe("Custom validate function", () => {
       let errors, errorSchema;