Add appraisal API request and response schema fixtures

[Lacastar2000]

Closes #74

Title

test: add appraisal API request/response schema fixtures and validation coverage

Summary

This PR strengthens the appraisal API integration boundary by introducing fixture-based schema validation tests for both requests and responses.

Representative fixtures are added to ensure valid payloads remain stable for integrators while malformed payloads are rejected with consistent, predictable validation errors. This provides a lightweight regression suite for future API changes without affecting scoring behavior or external dependencies.

Motivation

The appraisal API serves as an integration point for external clients. Changes to request or response schemas can inadvertently break downstream consumers if not caught early.

This change introduces version-controlled fixtures and validation tests to:

• Prevent accidental schema regressions.
• Provide stable examples for integrators.
• Ensure malformed payloads fail with clear, actionable errors.
• Preserve existing appraisal semantics.

Scope

Test Fixtures

Added representative fixtures covering:

Requests

• Valid appraisal request
• Missing required fields
• Incorrect field types
• Oversized text input
• Invalid score values (where applicable)

Responses

• Valid appraisal response
• Missing required fields
• Incorrect field types
• Invalid score values
• Malformed response structure

Fixtures are intentionally compact to keep the test suite fast and maintainable.

Validation Tests

Extended the existing appraisal API validation layer with tests that verify:

• Valid requests are accepted.
• Valid responses conform to the expected schema.
• Missing required fields produce stable validation errors.
• Incorrect data types are rejected.
• Oversized text inputs fail validation.
• Invalid score values are rejected according to current validation rules.
• Error responses remain consistent for client applications.

Documentation

Added example request and response fixtures to the project documentation (or package README) to provide reference payloads for API consumers.

Guardrails

This implementation intentionally does not:

• Call external AI or model providers during testing.
• Modify appraisal scoring logic or semantics.
• Relax existing validation rules to accept unsafe input.
• Introduce large or difficult-to-maintain fixture files.

Tests

Executed:

npm run test

Added coverage for:

• Valid request fixture
• Valid response fixture
• Missing required fields
• Invalid field types
• Oversized text validation
• Invalid score validation
• Stable validation error responses
• Existing appraisal service regression tests

Acceptance Criteria

• Request schema covered by fixture-based tests.
• Response schema covered by fixture-based tests.
• Valid fixtures continue to pass validation.
• Invalid payloads return stable validation errors.
• Documentation includes representative payload examples.
• Existing service tests continue to pass.

Notes

This change focuses on improving API compatibility and regression protection. It does not alter appraisal logic, scoring behavior, or external integrations. Future schema changes should update the fixture set and associated validation tests to ensure backward compatibility or intentional validation failures with clear error messaging.

[drips-wave]

@Lacastar2000 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits