json-rest-api 1.0.7 → 1.0.8

package/plugins/core/lib/{payload-validators.js → querying-writing/payload-validators.js}

@@ -1,4 +1,4 @@
-import { RestApiValidationError, RestApiPayloadError } from '../../../lib/rest-api-errors.js';
+import { RestApiValidationError, RestApiPayloadError } from '../../../../lib/rest-api-errors.js';
 
 /**
  * Validates that include paths don't exceed maximum depth
@@ -7,6 +7,18 @@ import { RestApiValidationError, RestApiPayloadError } from '../../../lib/rest-a
  * @param {number} maxDepth - Maximum allowed depth
  * @returns {boolean} True if valid
  * @throws {RestApiValidationError} If depth is exceeded
+ * 
+ * @example
+ * // Input: Valid include paths
+ * validateIncludeDepth(['author', 'comments.author'], 3);
+ * // Output: true (depths are 1 and 2, both under limit)
+ * 
+ * @example
+ * // Input: Path exceeding depth limit
+ * validateIncludeDepth(['author.company.employees.manager'], 3);
+ * // Throws: RestApiValidationError
+ * // "Include path 'author.company.employees.manager' exceeds maximum depth of 3"
+ * 
  * @private
  */
 function validateIncludeDepth(includes, maxDepth) {
@@ -41,40 +53,51 @@ function validateIncludeDepth(includes, maxDepth) {
 /**
  * Validates a JSON:API resource identifier object
  * 
- * Ensures that a resource identifier follows JSON:API spec with proper type and id.
- * Used internally to validate relationship data and included resources.
- * 
- * @param {Object} identifier - The resource identifier to validate
- * @param {string} context - Context for error messages (e.g., "Relationship 'author'")
- * @param {Object} scopes - The scopes proxy object to check if type exists
+ * @param {Object} identifier - Resource identifier to validate  
+ * @param {string} context - Context for error messages
+ * @param {Object} scopes - Scopes proxy to verify resource types
  * @returns {boolean} True if valid
  * @throws {RestApiPayloadError|RestApiValidationError} If validation fails
  * 
- * @example <caption>Valid resource identifier</caption>
- * // This passes validation:
+ * @example
+ * // Input: Valid identifier
  * validateResourceIdentifier(
  *   { type: 'articles', id: '123' },
  *   "Relationship 'author'",
  *   scopes
  * );
+ * // Output: true
  * 
- * @example <caption>Invalid - missing type</caption>
- * // This throws RestApiPayloadError:
+ * @example  
+ * // Input: Missing type field
  * validateResourceIdentifier(
- *   { id: '123' },  // Missing 'type'
+ *   { id: '123' },
  *   "Relationship 'comments'",
  *   scopes
  * );
- * // Error: "Relationship 'comments': Resource identifier must have a non-empty 'type' string"
+ * // Throws: RestApiPayloadError
+ * // "Relationship 'comments': Resource identifier must have a non-empty 'type' string"
  * 
- * @example <caption>Invalid - unknown resource type</caption>
- * // This throws RestApiValidationError if 'unknown' scope doesn't exist:
+ * @example
+ * // Input: Unknown resource type
  * validateResourceIdentifier(
- *   { type: 'unknown', id: '456' },
+ *   { type: 'unicorns', id: '456' },
  *   "Included resource",
- *   scopes
+ *   scopes  // scopes['unicorns'] doesn't exist
  * );
- * // Error: "Included resource: Unknown resource type 'unknown'. No scope with this name exists."
+ * // Throws: RestApiValidationError
+ * // "Included resource: Unknown resource type 'unicorns'. No scope with this name exists."
+ * 
+ * @description
+ * Used by:
+ * - validateRelationship to check relationship data
+ * - validatePostPayload to validate included resources
+ * - Internal validation of resource references
+ * 
+ * Purpose:
+ * - Ensures JSON:API compliance for resource identifiers
+ * - Validates resource types exist in the system
+ * - Provides clear error context for debugging
  * 
  * @private
  */
@@ -124,26 +147,23 @@ function validateResourceIdentifier(identifier, context, scopes = null) {
 /**
  * Validates a relationship object in JSON:API format
  * 
- * Ensures relationships have proper structure with 'data' property containing
- * either null, a single resource identifier, or an array of resource identifiers.
- * Used to validate relationships in POST, PUT, and PATCH payloads.
- * 
- * @param {Object} relationship - The relationship to validate
- * @param {string} relationshipName - Name of the relationship for error context
- * @param {Object} scopes - The scopes proxy object to check if type exists
+ * @param {Object} relationship - Relationship object to validate
+ * @param {string} relationshipName - Name for error context
+ * @param {Object} scopes - Scopes proxy to verify resource types
  * @returns {boolean} True if valid
  * @throws {RestApiPayloadError} If validation fails
  * 
- * @example <caption>Valid to-one relationship</caption>
- * // Setting an article's author:
+ * @example
+ * // Input: To-one relationship
  * validateRelationship(
  *   { data: { type: 'users', id: '42' } },
  *   'author',
  *   scopes
  * );
+ * // Output: true
  * 
- * @example <caption>Valid to-many relationship</caption>
- * // Setting an article's tags:
+ * @example
+ * // Input: To-many relationship  
  * validateRelationship(
  *   { 
  *     data: [
@@ -154,22 +174,38 @@ function validateResourceIdentifier(identifier, context, scopes = null) {
  *   'tags',
  *   scopes
  * );
+ * // Output: true
  * 
- * @example <caption>Valid null relationship (removing association)</caption>
- * // Removing an article's featured image:
+ * @example
+ * // Input: Null relationship (remove association)
  * validateRelationship(
  *   { data: null },
  *   'featuredImage',
  *   scopes
  * );
+ * // Output: true (null is valid for clearing)
  * 
- * @example <caption>Valid empty to-many relationship</caption>
- * // Clearing all comments:
+ * @example
+ * // Input: Missing data property
  * validateRelationship(
- *   { data: [] },
- *   'comments',
+ *   { type: 'users', id: '1' },  // Wrong structure
+ *   'author',
  *   scopes
  * );
+ * // Throws: RestApiPayloadError
+ * // "Relationship 'author' must have a 'data' property"
+ * 
+ * @description
+ * Used by:
+ * - validatePostPayload for new resource relationships
+ * - validatePutPayload for relationship replacement
+ * - validatePatchPayload for relationship updates
+ * 
+ * Purpose:
+ * - Ensures JSON:API relationship structure
+ * - Validates both to-one and to-many relationships
+ * - Handles null/empty cases for clearing relationships
+ * - Validates each resource identifier in arrays
  * 
  * @private
  */
@@ -216,65 +252,85 @@ function validateRelationship(relationship, relationshipName, scopes = null) {
 /**
  * Validates query parameters for GET requests (single resource retrieval)
  * 
- * Ensures GET requests have required 'id' parameter and validates optional
- * query parameters like 'include' and 'fields' for sparse fieldsets.
- * This is called by the REST API plugin before executing a GET request.
- * 
- * @param {Object} params - The parameters object containing id and queryParams
- * @param {string|number} params.id - The resource ID to fetch
+ * @param {Object} params - Parameters containing id and queryParams
+ * @param {string|number} params.id - Resource ID to fetch
  * @param {Object} [params.queryParams] - Optional query parameters
  * @param {string[]} [params.queryParams.include] - Related resources to include
  * @param {Object} [params.queryParams.fields] - Sparse fieldsets by resource type
+ * @param {number} maxIncludeDepth - Maximum allowed include depth
  * @returns {boolean} True if valid
  * @throws {RestApiValidationError|RestApiPayloadError} If validation fails
  * 
- * @example <caption>Basic GET validation</caption>
- * // Fetch article 123:
+ * @example
+ * // Input: Basic GET request
  * validateGetPayload({
  *   id: '123'
  * });
+ * // Output: true
  * 
- * @example <caption>GET with includes</caption>
- * // Fetch article with author and comments:
+ * @example
+ * // Input: GET with nested includes
  * validateGetPayload({
  *   id: '123',
  *   queryParams: {
  *     include: ['author', 'comments.author']
  *   }
  * });
+ * // Output: true (include depths are 1 and 2)
  * 
- * @example <caption>GET with sparse fieldsets</caption>
- * // Fetch only specific fields:
+ * @example
+ * // Input: GET with sparse fieldsets
  * validateGetPayload({
  *   id: '123',
  *   queryParams: {
  *     include: ['author'],
  *     fields: {
- *       articles: 'title,body',
- *       users: 'name,email'
+ *       articles: 'title,body',      // Only these article fields
+ *       users: 'name,email'          // Only these user fields
  *     }
  *   }
  * });
+ * // Output: true
  * 
- * @example <caption>Invalid - missing ID</caption>
- * // This throws RestApiValidationError:
+ * @example
+ * // Input: Missing ID parameter
  * validateGetPayload({
  *   queryParams: { include: ['author'] }
  * });
- * // Error: "GET request must include an id parameter"
+ * // Throws: RestApiValidationError
+ * // "GET request must include an id parameter"
  * 
- * @example <caption>Invalid - null ID</caption>
- * // This throws RestApiValidationError:
+ * @example
+ * // Input: Invalid field specification
  * validateGetPayload({
- *   id: null
+ *   id: '123',
+ *   queryParams: {
+ *     fields: {
+ *       articles: ['title', 'body']  // Should be string, not array
+ *     }
+ *   }
  * });
- * // Error: "GET request id cannot be null, undefined, or empty"
+ * // Throws: RestApiPayloadError  
+ * // "queryParams.fields['articles'] must be a comma-separated string"
  * 
- * @example <caption>Why this is useful upstream</caption>
- * // The REST API plugin uses this to ensure requests are valid before
- * // passing them to the storage layer (e.g., Knex plugin), preventing
- * // invalid queries from reaching the database and providing consistent
- * // error messages across all storage implementations.
+ * @description
+ * Used by:
+ * - rest-api-plugin.get() method before data fetching
+ * - Validates parameters before passing to storage layer
+ * 
+ * Purpose:
+ * - Ensures required ID parameter is present and valid
+ * - Validates JSON:API query parameter structure
+ * - Prevents invalid queries from reaching database
+ * - Enforces include depth limits for performance
+ * - Provides consistent error messages across storage backends
+ * 
+ * Data flow:
+ * 1. Checks params object structure
+ * 2. Validates required ID parameter
+ * 3. If queryParams exist, validates each type
+ * 4. Validates include paths don't exceed depth limit
+ * 5. Returns true or throws descriptive error
  */
 export function validateGetPayload(params, maxIncludeDepth = 3) {
   if (!params || typeof params !== 'object') {
@@ -358,54 +414,56 @@ export function validateGetPayload(params, maxIncludeDepth = 3) {
 /**
  * Validates query parameters for collection requests (query/list operations)
  * 
- * Ensures collection queries have valid filters, sorting, pagination, includes,
- * and sparse fieldsets. Validates that sort fields are in the allowed list.
- * This is called by the REST API plugin before executing a query request.
- * 
- * @param {Object} params - The parameters object
+ * @param {Object} params - Parameters object
  * @param {Object} [params.queryParams] - Query parameters for the collection
  * @param {string[]} [params.queryParams.include] - Related resources to include
  * @param {Object} [params.queryParams.fields] - Sparse fieldsets by resource type
  * @param {Object} [params.queryParams.filters] - Filter conditions
  * @param {string[]} [params.queryParams.sort] - Sort fields (prefix with - for DESC)
  * @param {Object} [params.queryParams.page] - Pagination parameters
- * @param {string[]} sortableFields - Array of fields that can be sorted
+ * @param {string[]} sortableFields - Fields allowed for sorting
+ * @param {number} maxIncludeDepth - Maximum allowed include depth
  * @returns {boolean} True if valid
  * @throws {RestApiValidationError|RestApiPayloadError} If validation fails
  * 
- * @example <caption>Basic query validation</caption>
- * // Simple query with no parameters:
+ * @example
+ * // Input: Empty query (fetch all)
  * validateQueryPayload({}, ['title', 'createdAt']);
+ * // Output: true
  * 
- * @example <caption>Query with filters and sorting</caption>
- * // Find published articles sorted by date:
+ * @example
+ * // Input: Query with filters and sorting
  * validateQueryPayload({
  *   queryParams: {
  *     filters: {
  *       status: 'published',
- *       'author.name': 'John Doe'  // Cross-table filter
+ *       'author.name': 'John Doe'    // Dot notation for relationships
  *     },
- *     sort: ['-publishedAt', 'title'],  // DESC by date, then ASC by title
+ *     sort: ['-publishedAt', 'title'] // DESC publishedAt, ASC title
  *   }
  * }, ['publishedAt', 'title', 'createdAt']);
+ * // Output: true
  * 
- * @example <caption>Query with pagination</caption>
- * // Page-based pagination:
+ * @example
+ * // Input: Different pagination styles
+ * // Page-based:
  * validateQueryPayload({
  *   queryParams: {
- *     page: { number: 2, size: 20 }
+ *     page: { number: 2, size: 20 }  // Page 2, 20 items per page
  *   }
  * }, []);
+ * // Output: true
  * 
- * // Offset-based pagination:
+ * // Offset-based:
  * validateQueryPayload({
  *   queryParams: {
- *     page: { offset: 40, limit: 20 }
+ *     page: { offset: 40, limit: 20 } // Skip 40, take 20
  *   }
  * }, []);
+ * // Output: true
  * 
- * @example <caption>Complex query with all features</caption>
- * // Full-featured query:
+ * @example
+ * // Input: Complex query with all features
  * validateQueryPayload({
  *   queryParams: {
  *     include: ['author', 'tags', 'comments.author'],
@@ -422,22 +480,36 @@ export function validateGetPayload(params, maxIncludeDepth = 3) {
  *     page: { number: 1, size: 10 }
  *   }
  * }, ['publishedAt', 'title', 'updatedAt']);
+ * // Output: true (all parameters valid)
  * 
- * @example <caption>Invalid - non-sortable field</caption>
- * // This throws RestApiValidationError:
+ * @example
+ * // Input: Invalid sort field
  * validateQueryPayload({
  *   queryParams: {
- *     sort: ['secretField']  // Not in sortableFields
+ *     sort: ['password']  // Not in sortableFields
  *   }
  * }, ['title', 'createdAt']);
- * // Error: "Field 'secretField' is not sortable. Sortable fields are: title, createdAt"
- * 
- * @example <caption>Why this is useful upstream</caption>
- * // The REST API plugin uses this to:
- * // 1. Prevent SQL injection by validating filter keys
- * // 2. Ensure consistent pagination across storage backends
- * // 3. Prevent sorting on non-indexed fields that could slow queries
- * // 4. Provide clear error messages before hitting the database
+ * // Throws: RestApiValidationError
+ * // "Field 'password' is not sortable. Sortable fields are: title, createdAt"
+ * 
+ * @description
+ * Used by:
+ * - rest-api-plugin.query() method before data fetching
+ * - Validates collection request parameters
+ * 
+ * Purpose:
+ * - Validates all JSON:API query parameters for collections
+ * - Prevents SQL injection via filter key validation
+ * - Enforces sortable field restrictions for performance
+ * - Ensures consistent pagination across storage backends
+ * - Validates include depth limits
+ * 
+ * Data flow:
+ * 1. Validates params object structure
+ * 2. For each query parameter type, validates format
+ * 3. Checks sort fields against allowed list
+ * 4. Validates pagination parameters are numbers/strings
+ * 5. Returns true or throws descriptive error
  */
 export function validateQueryPayload(params, sortableFields = [], maxIncludeDepth = 3) {
   if (!params || typeof params !== 'object') {
@@ -583,24 +655,19 @@ export function validateQueryPayload(params, sortableFields = [], maxIncludeDept
 /**
  * Validates a JSON:API document for POST requests (resource creation)
  * 
- * Ensures POST payloads follow JSON:API spec with proper data structure,
- * validates relationships reference existing resources, and checks that
- * included resources have required IDs. This is the main validation gateway
- * for creating new resources through the REST API.
- * 
- * @param {Object} inputRecord - The JSON:API document to validate
- * @param {Object} inputRecord.data - The primary resource to create
+ * @param {Object} inputRecord - JSON:API document to validate
+ * @param {Object} inputRecord.data - Primary resource to create
  * @param {string} inputRecord.data.type - Resource type (must match a scope)
  * @param {string|number} [inputRecord.data.id] - Optional client-generated ID
  * @param {Object} [inputRecord.data.attributes] - Resource attributes
  * @param {Object} [inputRecord.data.relationships] - Resource relationships
  * @param {Object[]} [inputRecord.included] - Related resources for compound documents
- * @param {Object} scopes - The scopes proxy object to check if type exists
+ * @param {Object} scopes - Scopes proxy to verify resource types exist
  * @returns {boolean} True if valid
  * @throws {RestApiValidationError|RestApiPayloadError} If validation fails
  * 
- * @example <caption>Basic POST validation</caption>
- * // Create a simple article:
+ * @example
+ * // Input: Simple resource creation
  * validatePostPayload({
  *   data: {
  *     type: 'articles',
@@ -610,9 +677,10 @@ export function validateQueryPayload(params, sortableFields = [], maxIncludeDept
  *     }
  *   }
  * }, scopes);
+ * // Output: true
  * 
- * @example <caption>POST with relationships</caption>
- * // Create article with author and tags:
+ * @example
+ * // Input: Create with relationships
  * validatePostPayload({
  *   data: {
  *     type: 'articles',
@@ -621,10 +689,10 @@ export function validateQueryPayload(params, sortableFields = [], maxIncludeDept
  *     },
  *     relationships: {
  *       author: {
- *         data: { type: 'users', id: '42' }
+ *         data: { type: 'users', id: '42' }      // To-one
  *       },
  *       tags: {
- *         data: [
+ *         data: [                                 // To-many
  *           { type: 'tags', id: '1' },
  *           { type: 'tags', id: '2' }
  *         ]
@@ -632,21 +700,23 @@ export function validateQueryPayload(params, sortableFields = [], maxIncludeDept
  *     }
  *   }
  * }, scopes);
+ * // Output: true (validates each relationship)
  * 
- * @example <caption>POST with client-generated ID</caption>
- * // Some APIs allow client-generated IDs:
+ * @example
+ * // Input: Client-generated ID
  * validatePostPayload({
  *   data: {
  *     type: 'articles',
- *     id: 'article-2023-11-15-hello-world',  // Client-provided ID
+ *     id: 'article-2023-11-15',     // Client provides ID
  *     attributes: {
  *       title: 'Hello World'
  *     }
  *   }
  * }, scopes);
+ * // Output: true (ID is optional for POST)
  * 
- * @example <caption>POST with included resources (compound document)</caption>
- * // Create article with embedded author data for client convenience:
+ * @example
+ * // Input: Compound document with included
  * validatePostPayload({
  *   data: {
  *     type: 'articles',
@@ -657,10 +727,10 @@ export function validateQueryPayload(params, sortableFields = [], maxIncludeDept
  *       }
  *     }
  *   },
- *   included: [
+ *   included: [            // Related resource data
  *     {
  *       type: 'users',
- *       id: '42',
+ *       id: '42',          // Must have ID
  *       attributes: {
  *         name: 'John Doe',
  *         email: 'john@example.com'
@@ -668,33 +738,37 @@ export function validateQueryPayload(params, sortableFields = [], maxIncludeDept
  *     }
  *   ]
  * }, scopes);
+ * // Output: true (included resources validated)
  * 
- * @example <caption>Invalid - missing type</caption>
- * // This throws RestApiPayloadError:
+ * @example
+ * // Input: Missing required type
  * validatePostPayload({
  *   data: {
  *     attributes: { title: 'Missing Type' }
  *   }
  * }, scopes);
- * // Error: 'POST request "data" must have a non-empty "type" string'
+ * // Throws: RestApiPayloadError
+ * // 'POST request "data" must have a non-empty "type" string'
  * 
- * @example <caption>Invalid - unknown resource type</caption>
- * // This throws RestApiValidationError:
- * validatePostPayload({
- *   data: {
- *     type: 'unicorns',  // Not a registered scope
- *     attributes: { name: 'Sparkles' }
- *   }
- * }, scopes);
- * // Error: 'POST request "data.type" 'unicorns' is not a valid resource type'
- * 
- * @example <caption>Why this is useful upstream</caption>
- * // The REST API plugin uses this to:
- * // 1. Ensure data integrity before hitting the database
- * // 2. Validate relationships exist before creating foreign key references
- * // 3. Provide consistent API behavior across different storage backends
- * // 4. Enable compound document creation while maintaining data consistency
- * // 5. Catch errors early with meaningful messages for API consumers
+ * @description
+ * Used by:
+ * - rest-api-plugin.post() method before creating resources
+ * - Validates complete document structure
+ * 
+ * Purpose:
+ * - Ensures JSON:API compliance for resource creation
+ * - Validates resource types exist in system
+ * - Checks relationship references are valid
+ * - Validates included resources have required fields
+ * - Enables compound document creation patterns
+ * 
+ * Data flow:
+ * 1. Validates document has required 'data' property
+ * 2. Checks primary resource type exists in scopes
+ * 3. Validates attributes object if present
+ * 4. Validates each relationship if present
+ * 5. Validates included resources array if present
+ * 6. Returns true or throws descriptive error
  */
 export function validatePostPayload(inputRecord, scopes = null) {
   if (!inputRecord || typeof inputRecord !== 'object') {
@@ -832,27 +906,22 @@ export function validatePostPayload(inputRecord, scopes = null) {
 /**
  * Validates a JSON:API document for PUT requests (full resource replacement)
  * 
- * Ensures PUT payloads follow JSON:API spec for complete resource replacement.
- * Unlike PATCH, PUT requires the complete resource representation and doesn't
- * allow 'included' arrays (as PUT shouldn't create new related resources).
- * The ID is required and must match the URL parameter.
- * 
- * @param {Object} inputRecord - The JSON:API document to validate
- * @param {Object} inputRecord.data - The complete resource representation
+ * @param {Object} inputRecord - JSON:API document to validate
+ * @param {Object} inputRecord.data - Complete resource representation
  * @param {string} inputRecord.data.type - Resource type (must match existing)
  * @param {string|number} inputRecord.data.id - Resource ID (required)
  * @param {Object} [inputRecord.data.attributes] - Complete attributes
  * @param {Object} [inputRecord.data.relationships] - Complete relationships
- * @param {Object} scopes - The scopes proxy object to check if type exists
+ * @param {Object} scopes - Scopes proxy to verify resource types exist
  * @returns {boolean} True if valid
  * @throws {RestApiValidationError|RestApiPayloadError} If validation fails
  * 
- * @example <caption>Basic PUT validation</caption>
- * // Replace entire article:
+ * @example
+ * // Input: Complete resource replacement
  * validatePutPayload({
  *   data: {
  *     type: 'articles',
- *     id: '123',
+ *     id: '123',                   // Required for PUT
  *     attributes: {
  *       title: 'Updated Title',
  *       body: 'Completely new body text',
@@ -860,9 +929,10 @@ export function validatePostPayload(inputRecord, scopes = null) {
  *     }
  *   }
  * }, scopes);
+ * // Output: true
  * 
- * @example <caption>PUT with relationship replacement</caption>
- * // Replace article with new author and tags:
+ * @example
+ * // Input: Replace with new relationships
  * validatePutPayload({
  *   data: {
  *     type: 'articles',
@@ -873,53 +943,68 @@ export function validatePostPayload(inputRecord, scopes = null) {
  *     },
  *     relationships: {
  *       author: {
- *         data: { type: 'users', id: '99' }  // Changed author
+ *         data: { type: 'users', id: '99' }    // New author
  *       },
  *       tags: {
- *         data: [  // Completely new set of tags
+ *         data: [                              // Replace all tags
  *           { type: 'tags', id: '5' },
  *           { type: 'tags', id: '6' },
  *           { type: 'tags', id: '7' }
  *         ]
  *       },
  *       featuredImage: {
- *         data: null  // Remove featured image
+ *         data: null                           // Remove relationship
  *       }
  *     }
  *   }
  * }, scopes);
+ * // Output: true (complete replacement)
  * 
- * @example <caption>Invalid - missing ID</caption>
- * // This throws RestApiPayloadError:
+ * @example
+ * // Input: Missing required ID
  * validatePutPayload({
  *   data: {
  *     type: 'articles',
  *     attributes: { title: 'No ID' }
  *   }
  * }, scopes);
- * // Error: 'PUT request "data" must have an "id" property'
+ * // Throws: RestApiPayloadError
+ * // 'PUT request "data" must have an "id" property'
  * 
- * @example <caption>Invalid - includes not allowed</caption>
- * // This throws RestApiPayloadError:
+ * @example
+ * // Input: Includes not allowed
  * validatePutPayload({
  *   data: {
  *     type: 'articles',
  *     id: '123',
  *     attributes: { title: 'Updated' }
  *   },
- *   included: [  // Not allowed in PUT
- *     { type: 'users', id: '1', attributes: { name: 'John' } }
+ *   included: [                        // Not allowed!
+ *     { type: 'users', id: '1' }
  *   ]
  * }, scopes);
- * // Error: 'PUT requests cannot include an "included" array'
- * 
- * @example <caption>Why this is useful upstream</caption>
- * // The REST API plugin uses PUT validation to:
- * // 1. Ensure idempotent operations (same PUT = same result)
- * // 2. Prevent accidental partial updates (use PATCH for that)
- * // 3. Maintain clear semantics: PUT = replace, PATCH = modify
- * // 4. Prevent side effects like creating related resources
- * // 5. Ensure the ID in payload matches the URL parameter
+ * // Throws: RestApiPayloadError
+ * // 'PUT requests cannot include an "included" array for creating new resources'
+ * 
+ * @description
+ * Used by:
+ * - rest-api-plugin.put() method for full replacement
+ * - Enforces PUT semantics vs PATCH
+ * 
+ * Purpose:
+ * - Ensures complete resource replacement semantics
+ * - Requires ID to match URL parameter
+ * - Prevents included resources (no side effects)
+ * - Maintains idempotency of PUT operations
+ * - Differentiates from PATCH partial updates
+ * 
+ * Data flow:
+ * 1. Validates document structure with data property
+ * 2. Ensures no included array present
+ * 3. Validates resource type exists in scopes
+ * 4. Requires ID property (unlike POST)
+ * 5. Validates attributes and relationships if present
+ * 6. Returns true or throws descriptive error
  */
 export function validatePutPayload(inputRecord, scopes = null) {
   if (!inputRecord || typeof inputRecord !== 'object') {
@@ -1022,36 +1107,32 @@ export function validatePutPayload(inputRecord, scopes = null) {
 /**
  * Validates a JSON:API document for PATCH requests (partial resource updates)
  * 
- * Ensures PATCH payloads follow JSON:API spec for partial updates. Unlike PUT,
- * PATCH allows sending only the fields/relationships that need updating.
- * Requires at least one of 'attributes' or 'relationships' to be present.
- * Like PUT, doesn't allow 'included' arrays.
- * 
- * @param {Object} inputRecord - The JSON:API document to validate
- * @param {Object} inputRecord.data - The partial resource representation
+ * @param {Object} inputRecord - JSON:API document to validate
+ * @param {Object} inputRecord.data - Partial resource representation
  * @param {string} inputRecord.data.type - Resource type (must match existing)
  * @param {string|number} inputRecord.data.id - Resource ID (required)
  * @param {Object} [inputRecord.data.attributes] - Attributes to update
  * @param {Object} [inputRecord.data.relationships] - Relationships to update
- * @param {Object} scopes - The scopes proxy object to check if type exists
+ * @param {Object} scopes - Scopes proxy to verify resource types exist
  * @returns {boolean} True if valid
  * @throws {RestApiValidationError|RestApiPayloadError} If validation fails
  * 
- * @example <caption>PATCH single attribute</caption>
- * // Just update the title:
+ * @example
+ * // Input: Update single field
  * validatePatchPayload({
  *   data: {
  *     type: 'articles',
  *     id: '123',
  *     attributes: {
- *       title: 'New Title Only'
- *       // Other attributes remain unchanged
+ *       title: 'New Title Only'     // Only title changes
+ *       // body, status, etc. remain unchanged
  *     }
  *   }
  * }, scopes);
+ * // Output: true
  * 
- * @example <caption>PATCH multiple attributes</caption>
- * // Update status and timestamp:
+ * @example
+ * // Input: Update multiple fields
  * validatePatchPayload({
  *   data: {
  *     type: 'articles',
@@ -1059,79 +1140,78 @@ export function validatePutPayload(inputRecord, scopes = null) {
  *     attributes: {
  *       status: 'published',
  *       publishedAt: '2023-11-15T10:00:00Z'
- *       // title, body, etc. remain unchanged
+ *       // Other fields untouched
  *     }
  *   }
  * }, scopes);
+ * // Output: true (partial update)
  * 
- * @example <caption>PATCH relationships only</caption>
- * // Just change the author:
+ * @example
+ * // Input: Update relationships only
  * validatePatchPayload({
  *   data: {
  *     type: 'articles',
  *     id: '123',
  *     relationships: {
  *       author: {
- *         data: { type: 'users', id: '456' }
+ *         data: { type: 'users', id: '456' }  // Change author
  *       }
- *       // tags, comments, etc. remain unchanged
+ *       // Other relationships unchanged
  *     }
  *   }
  * }, scopes);
+ * // Output: true
  * 
- * @example <caption>PATCH to clear relationships</caption>
- * // Remove featured image, clear all tags:
+ * @example
+ * // Input: Clear relationships
  * validatePatchPayload({
  *   data: {
  *     type: 'articles',
  *     id: '123',
  *     relationships: {
  *       featuredImage: {
- *         data: null  // Remove to-one relationship
+ *         data: null                // Remove to-one
  *       },
  *       tags: {
- *         data: []  // Clear to-many relationship
- *       }
- *     }
- *   }
- * }, scopes);
- * 
- * @example <caption>PATCH both attributes and relationships</caption>
- * // Complex update:
- * validatePatchPayload({
- *   data: {
- *     type: 'articles',
- *     id: '123',
- *     attributes: {
- *       status: 'archived',
- *       archivedAt: '2023-11-15T15:30:00Z'
- *     },
- *     relationships: {
- *       archivedBy: {
- *         data: { type: 'users', id: '789' }
+ *         data: []                  // Clear to-many
  *       }
  *     }
  *   }
  * }, scopes);
+ * // Output: true (clearing is valid)
  * 
- * @example <caption>Invalid - no changes specified</caption>
- * // This throws RestApiValidationError:
+ * @example
+ * // Input: No changes specified
  * validatePatchPayload({
  *   data: {
  *     type: 'articles',
  *     id: '123'
- *     // No attributes or relationships!
+ *     // Missing both attributes and relationships!
  *   }
  * }, scopes);
- * // Error: 'PATCH request "data" must have at least one of "attributes" or "relationships"'
- * 
- * @example <caption>Why this is useful upstream</caption>
- * // The REST API plugin uses PATCH validation to:
- * // 1. Enable efficient partial updates (only send what changes)
- * // 2. Reduce bandwidth for large resources
- * // 3. Prevent race conditions (don't overwrite fields you didn't intend to)
- * // 4. Support field-level permissions (some fields might be read-only)
- * // 5. Maintain clear semantics vs PUT (PATCH = modify, PUT = replace)
+ * // Throws: RestApiValidationError
+ * // 'PATCH request "data" must have at least one of "attributes" or "relationships"'
+ * 
+ * @description
+ * Used by:
+ * - rest-api-plugin.patch() method for partial updates
+ * - Enforces PATCH semantics vs PUT
+ * 
+ * Purpose:
+ * - Enables efficient partial updates (send only changes)
+ * - Requires at least one change (attributes or relationships)
+ * - Prevents included resources (no side effects)
+ * - Reduces bandwidth for large resources
+ * - Prevents race conditions in concurrent updates
+ * 
+ * Data flow:
+ * 1. Validates document structure with data property
+ * 2. Ensures no included array present
+ * 3. Validates resource type exists in scopes
+ * 4. Requires ID property for targeting
+ * 5. Requires at least attributes or relationships
+ * 6. Validates each if present
+ * 7. Returns true or throws descriptive error
  */
 export function validatePatchPayload(inputRecord, scopes = null) {
   if (!inputRecord || typeof inputRecord !== 'object') {