Testing Schema Validation in JSON Formatters

In the world of data exchange, JSON is ubiquitous. Whether you're building APIs, configuring applications, or storing data, chances are you're interacting with JSON. Often, applications need to take raw data andformat it into a specific JSON structure before sending it out or saving it.

While your formatter logic might seem straightforward, ensuring the output JSON strictly adheres to a defined structure (a schema) is crucial for reliability and interoperability. This is wheretesting schema validation becomes essential.

What is Schema Validation?

Think of a schema as a contract for your data. It defines the expected structure, data types, required fields, allowed values, and relationships within a JSON document.

JSON Schema is a popular standard for describing the structure of JSON data. It allows you to specify constraints like:

• What properties an object should have.
• The data type of each property (string, number, boolean, array, object, null).
• Whether a property is required or optional.
• Minimum/maximum values for numbers or strings.
• Patterns (regex) for string values.
• Items allowed in an array.
• Relationships between properties.

Schema validation is the process of checking whether a given JSON document conforms to its defined schema. If it doesn't, the validation process should report specific errors indicating what went wrong.

Why Test Schema Validation?

You might wonder, "If my formatter builds the JSON according to the rules, why do I need to validate it?" Here's why it's critical:

• Preventing Bugs: Formatters can have bugs. A simple logic error might output a number instead of a string, miss a required field, or use the wrong key name.
• Ensuring API Contracts: If your JSON is an API response, the schema is your contract with consumers. Broken contracts lead to broken integrations for others.
• Maintaining Data Integrity: When storing or processing JSON internally, validating against a schema ensures consistency and prevents invalid data from corrupting downstream processes.
• Refactoring Confidence: When you refactor your formatter code, tests that validate the output schema give you confidence that you haven't inadvertently changed the output structure.
• Clear Error Reporting: Validation libraries provide specific error messages, making debugging failed formatting attempts much easier.

Testing this validation step acts as a safety net, catching issues early in the development cycle.

How to Validate and Test Validation

Validation is typically done using a dedicated JSON Schema validation library. These libraries take a JSON Schema definition and a JSON data object and return a boolean indicating validity, plus a list of validation errors if it's invalid.

Popular libraries exist for most programming languages (e.g., AJV for JavaScript/TypeScript, jsonschema for Python, etc.). The core idea is the same:

1. Define your JSON Schema (as a JavaScript object or JSON file).
2. Get the JSON data output from your formatter.
3. Use a validation library to compile the schema.
4. Use the compiled schema validator function to check the data.
5. If validation fails, inspect the errors provided by the library.

Example: Data, Schema, and Validation

Let's consider a simple example:

Sample JSON Data (Expected Output):

{
  "id": "user-123",
  "name": "Alice Smith",
  "age": 30,
  "isActive": true,
  "tags": ["employee", "marketing"]
}

Corresponding JSON Schema:

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 },
    "isActive": { "type": "boolean" },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["id", "name", "age", "isActive"]
}

Conceptual Validation Code (using 'ajv'):

// Assuming 'ajv' is installed and imported
// import Ajv from 'ajv';

const userSchema = {
  type: "object",
  properties: {
    id: { type: "string" },
    name: { type: "string" },
    age: { type: "integer", minimum: 0 },
    isActive: { type: "boolean" },
    tags: {
      type: "array",
      items: { type: "string" }
    }
  },
  required: ["id", "name", "age", "isActive"]
};

// This function represents your formatter
function formatUserData(rawData: any): any {
  // ... your formatting logic here ...
  // This is a placeholder returning valid data
  return {
    id: rawData.userId || null, // Example: rawData might be different
    name: rawData.userName,
    age: rawData.userAge,
    isActive: rawData.userStatus === 'active',
    tags: rawData.userTags ? rawData.userTags.split(',') : []
  };
}

// Assume raw input data
const inputData = {
  userId: "user-123",
  userName: "Alice Smith",
  userAge: 30,
  userStatus: 'active',
  userTags: 'employee,marketing'
};

const formattedData = formatUserData(inputData);

// --- Validation Step ---
// const ajv = new Ajv(); // In a real test, you'd typically create this once
// const validate = ajv.compile(userSchema); // Compile schema

// const isValid = validate(formattedData);

// if (!isValid) {
//   console.error("Validation Errors:", validate.errors);
//   // In a test, you would assert that errors exist or have specific details
// } else {
//   console.log("Data is valid!");
//   // In a test, you would assert that isValid is true
// }

// Note: The actual validation logic would live in your test file,
// not within the formatter itself.

Testing the Validation Process Itself

Your tests should cover two main areas:

1. Testing the Validator Setup: Ensure your schema is correctly defined and the validation library is configured to validate against it. This is often implicitly tested when you test your formatter, but dedicated tests for complex schemas can be useful.
2. Testing the Formatter's Output: This is the primary goal. You pass various inputs to your formatter and then validate its output against the schema.

Types of Tests for Formatter Output:

1. Valid Data Tests

Test cases where the input data should result in a perfectly valid JSON output according to the schema.

// Test case: Standard valid input
test('formatter outputs valid JSON for standard data', () => {
  const input = { userId: "user-123", userName: "Alice", userAge: 30, userStatus: 'active', userTags: 'dev' };
  const output = formatUserData(input); // Call your formatter
  const isValid = validate(output);      // Use your compiled validator

  expect(isValid).toBe(true);
  expect(validate.errors).toBeNull(); // Or expect(validate.errors).toBeUndefined() depending on library
});

// Test case: Valid input with optional fields missing (if applicable)
test('formatter outputs valid JSON when optional fields are missing', () => {
  const input = { userId: "user-456", userName: "Bob", userAge: 25, userStatus: 'inactive' /* no userTags */ };
  const output = formatUserData(input);
  const isValid = validate(output);

  expect(isValid).toBe(true);
  expect(validate.errors).toBeNull();
});

2. Invalid Data Tests

These are crucial. Test cases where the input data should cause the formatter to produce output that violates the schema. The test should assert that validation fails and, ideally, check for specific error details.

• Missing Required Fields: What happens if the input data lacks information needed for a required field in the output?

  // Test case: Missing required field 'name' in output
  test('formatter outputs invalid JSON when input is missing user name', () => {
    const input = { userId: "user-789", userAge: 40, userStatus: 'active' }; // Missing userName
    const output = formatUserData(input); // Assumes formatUserData handles missing input gracefully, maybe returns undefined or null for name
  
    const isValid = validate(output);
  
    expect(isValid).toBe(false);
    // Expecting a specific error related to the 'name' property missing or being null/undefined
    expect(validate.errors).toEqual(
      expect.arrayContaining([
        expect.objectContaining({
          keyword: 'type', // Or 'required', depends on how AJV reports this
          dataPath: '.name',
          message: 'must be string' // Or 'must have required property 'name''
        })
      ])
    );
  });

• Wrong Data Types: Test inputs that should cause the formatter to output a field with the wrong type.

  // Test case: Outputting wrong type for 'age'
  test('formatter outputs invalid JSON with wrong type for age', () => {
    const input = { userId: "user-101", userName: "Charlie", userAge: "thirty", userStatus: 'active' }; // Age is a string
    const output = formatUserData(input); // Assumes formatUserData might pass this string through or handle it poorly
  
    const isValid = validate(output);
  
    expect(isValid).toBe(false);
    expect(validate.errors).toEqual(
      expect.arrayContaining([
        expect.objectContaining({
          keyword: 'type',
          dataPath: '.age',
          message: 'must be integer'
        })
      ])
    );
  });

• Incorrect Format/Constraints: Test number ranges, string patterns, array item types, etc.

  // Test case: Outputting age less than minimum (0)
  test('formatter outputs invalid JSON with age less than minimum', () => {
    const input = { userId: "user-112", userName: "Diana", userAge: -5, userStatus: 'active' }; // Age is negative
    const output = formatUserData(input);
  
    const isValid = validate(output);
  
    expect(isValid).toBe(false);
    expect(validate.errors).toEqual(
      expect.arrayContaining([
        expect.objectContaining({
          keyword: 'minimum',
          dataPath: '.age',
          message: 'must be >= 0'
        })
      ])
    );
  });

• Extra/Unexpected Properties: If your schema uses "additionalProperties": false, test that extra fields in the output cause validation failure.

  // Assume schema had "additionalProperties": false
  // Test case: Formatter adds an unexpected property
  test('formatter outputs invalid JSON with unexpected property', () => {
    // Assume formatUserData accidentally adds { extraField: 'oops' }
    const input = { userId: "user-131", userName: "Eve", userAge: 28, userStatus: 'active' };
    const output = { ...formatUserData(input), extraField: 'oops' }; // Simulate formatter error
  
    const isValid = validate(output);
  
    expect(isValid).toBe(false);
    expect(validate.errors).toEqual(
      expect.arrayContaining([
        expect.objectContaining({
          keyword: 'additionalProperties',
          dataPath: '', // Often empty for additionalProperties
          params: { additionalProperty: 'extraField' },
          message: 'must NOT have additional properties'
        })
      ])
    );
  });

3. Edge Cases

Consider inputs that might lead to edge cases in your formatter's output:

• Empty input data for the formatter.
• Inputs that should result in empty objects or arrays in the output.
• Inputs that should result in null values (if allowed by schema).
• Arrays with empty items or wrong item types (if schema specifies item type).

Structuring Your Tests

Organize your tests logically. A common pattern is to group tests by the formatter function or the schema they validate against.

// Example test file structure (using Jest or similar)
// import { formatUserData } from './userFormatter'; // Your formatter
// import { userSchema } from './userSchema';         // Your schema
// import Ajv from 'ajv';

// const ajv = new Ajv();
// const validateUser = ajv.compile(userSchema);

describe('User Data Formatter Output Validation', () => {

  // Test suite for valid outputs
  describe('Valid Outputs', () => {
    test('should produce valid JSON for complete input', () => {
      const input = { userId: "u1", userName: "Test User", userAge: 25, userStatus: 'active', userTags: 'a,b' };
      const output = formatUserData(input);
      expect(validateUser(output)).toBe(true);
      expect(validateUser.errors).toBeNull();
    });

    test('should produce valid JSON for input with no tags', () => {
      const input = { userId: "u2", userName: "Another User", userAge: 40, userStatus: 'inactive' };
      const output = formatUserData(input);
      expect(validateUser(output)).toBe(true);
      expect(validateUser.errors).toBeNull();
    });

    // Add more valid cases...
  });

  // Test suite for invalid outputs
  describe('Invalid Outputs', () => {
    test('should fail validation when name is missing', () => {
      const input = { userId: "u3", userAge: 35, userStatus: 'active' }; // Missing userName
      const output = formatUserData(input);
      expect(validateUser(output)).toBe(false);
      expect(validateUser.errors).toEqual(
         expect.arrayContaining([ expect.objectContaining({ dataPath: '.name' }) ]) // Check for error on .name
      );
    });

    test('should fail validation when age is wrong type', () => {
      const input = { userId: "u4", userName: "Invalid Age", userAge: "twenty", userStatus: 'active' }; // Wrong type for age
      const output = formatUserData(input);
      expect(validateUser(output)).toBe(false);
      expect(validateUser.errors).toEqual(
        expect.arrayContaining([ expect.objectContaining({ dataPath: '.age', keyword: 'type' }) ]) // Check for type error on .age
      );
    });

    // Add more invalid cases covering different schema violations...
  });

  // Test suite for edge cases
   describe('Edge Cases', () => {
     test('should produce valid JSON for input resulting in empty tags array', () => {
       const input = { userId: "u5", userName: "No Tags", userAge: 22, userStatus: 'active', userTags: '' };
       const output = formatUserData(input);
       expect(validateUser(output)).toBe(true);
       expect(validateUser.errors).toBeNull();
       expect(output.tags).toEqual([]); // Also check the formatter output itself
     });
     // Add more edge cases...
   });

});

Within the invalid output tests, specifically checking the structure of the validation errors (e.g., using expect.arrayContaining and expect.objectContainingwith properties like dataPath, keyword, message) is a robust way to ensure the validation is failing for the <em>correct</em> reason.

Conclusion

Testing schema validation for your JSON formatter's output is a fundamental practice for building robust and reliable systems that handle structured data. By using a schema definition (like JSON Schema) and a validation library, and by writing comprehensive tests covering valid, invalid, and edge cases, you create a strong safety net. This practice minimizes bugs, ensures data integrity, upholds API contracts, and provides confidence during refactoring, ultimately leading to more stable and maintainable code.