json-rest-api 1.0.22 → 1.0.23

package/plugins/core/rest-api-plugin-hooks/register-scope-routes.js

@@ -60,42 +60,48 @@ export default async function registerScopeRoutes ({ context, api, vars, log })
   await api.addRoute({
     method: 'GET',
     path: scopePath,
-    handler: createRouteHandler(scopeName, 'query')
+    handler: createRouteHandler(scopeName, 'query'),
+    routeMeta: { kind: 'resource', scopeName, operation: 'query' }
   })
 
   // GET /api/{scope}/{id} - Get single resource
   await api.addRoute({
     method: 'GET',
     path: `${scopePath}/:id`,
-    handler: createRouteHandler(scopeName, 'get')
+    handler: createRouteHandler(scopeName, 'get'),
+    routeMeta: { kind: 'resource', scopeName, operation: 'get' }
   })
 
   // POST /api/{scope} - Create resource
   await api.addRoute({
     method: 'POST',
     path: scopePath,
-    handler: createRouteHandler(scopeName, 'post')
+    handler: createRouteHandler(scopeName, 'post'),
+    routeMeta: { kind: 'resource', scopeName, operation: 'post' }
   })
 
   // PUT /api/{scope}/{id} - Replace resource
   await api.addRoute({
     method: 'PUT',
     path: `${scopePath}/:id`,
-    handler: createRouteHandler(scopeName, 'put')
+    handler: createRouteHandler(scopeName, 'put'),
+    routeMeta: { kind: 'resource', scopeName, operation: 'put' }
   })
 
   // PATCH /api/{scope}/{id} - Update resource
   await api.addRoute({
     method: 'PATCH',
     path: `${scopePath}/:id`,
-    handler: createRouteHandler(scopeName, 'patch')
+    handler: createRouteHandler(scopeName, 'patch'),
+    routeMeta: { kind: 'resource', scopeName, operation: 'patch' }
   })
 
   // DELETE /api/{scope}/{id} - Delete resource
   await api.addRoute({
     method: 'DELETE',
     path: `${scopePath}/:id`,
-    handler: createRouteHandler(scopeName, 'delete')
+    handler: createRouteHandler(scopeName, 'delete'),
+    routeMeta: { kind: 'resource', scopeName, operation: 'delete' }
   })
 
   log.info(`Routes registered for scope '${scopeName}'`)

package/plugins/core/rest-api-plugin-methods/apply-query-filters.js

@@ -0,0 +1,41 @@
+export default async function applyQueryFiltersMethod ({ context, params = {}, runHooks }) {
+  const { query, filters, storageAdapter, ...knexQuery } = params
+
+  if (!query) {
+    return query
+  }
+
+  const previousKnexQuery = context.knexQuery
+  const previousStorageAdapter = context.storageAdapter
+
+  context.knexQuery = {
+    query,
+    filters,
+    storageAdapter,
+    adapter: storageAdapter,
+    ...knexQuery
+  }
+
+  if (storageAdapter) {
+    context.storageAdapter = storageAdapter
+  }
+
+  try {
+    await runHooks('knexQueryFiltering')
+    return {
+      query: context.knexQuery?.query || query
+    }
+  } finally {
+    if (previousKnexQuery === undefined) {
+      delete context.knexQuery
+    } else {
+      context.knexQuery = previousKnexQuery
+    }
+
+    if (previousStorageAdapter === undefined) {
+      delete context.storageAdapter
+    } else {
+      context.storageAdapter = previousStorageAdapter
+    }
+  }
+}

package/plugins/core/rest-api-plugin-methods/common.js

@@ -1,9 +1,10 @@
 import {
-  RestApiValidationError,
-  RestApiPayloadError
+  RestApiResourceError,
+  RestApiValidationError
 } from '../../../lib/rest-api-errors.js'
 import { transformSimplifiedToJsonApi } from '../lib/querying-writing/simplified-helpers.js'
 import { createEnhancedLogger } from '../../../lib/enhanced-logger.js'
+import { unwrapQueryBuilderState } from '../lib/querying/query-builder-utils.js'
 
 /**
  * Gets an enhanced logger instance with full error details and stack traces
@@ -140,56 +141,6 @@ export async function setupCommonRequest ({ params, context, vars, scopes, scope
       { inputRecord: context.inputRecord },
       { context: { scopeName, schemaStructure, schemaRelationships } }
     )
-  } else {
-    // Strict mode: validate no belongsTo fields in attributes
-    if (context.inputRecord?.data?.attributes) {
-      for (const [key, fieldDef] of Object.entries(schemaStructure)) {
-        if (fieldDef.belongsTo && key in context.inputRecord.data.attributes) {
-          throw new RestApiValidationError(
-            `Field '${key}' is a foreign key and must be set via relationships, not attributes`,
-            { fields: [`data.attributes.${key}`] }
-          )
-        }
-      }
-    }
-  }
-
-  if (context.inputRecord.data.type !== scopeName) {
-    throw new RestApiValidationError(
-      `Resource type mismatch. Expected '${scopeName}' but got '${context.inputRecord.data.type}'`,
-      {
-        fields: ['data.type'],
-        violations: [{
-          field: 'data.type',
-          rule: 'resource_type_match',
-          message: `Resource type must be '${scopeName}'`
-        }]
-      }
-    )
-  }
-
-  // Remove included validation since JSON:API doesn't support it
-  if (context.inputRecord.included) {
-    throw new RestApiPayloadError(
-      context.method + ' requests cannot include an "included" array. JSON:API does not support creating multiple resources in a single request.',
-      { path: 'included', expected: 'undefined', received: 'array' }
-    )
-  }
-
-  // If both URL path ID and request body ID are provided, they must match
-  // Convert both to strings for comparison since databases may return numeric IDs
-  if (context.id && context.inputRecord.data.id && String(context.id) !== String(context.inputRecord.data.id)) {
-    throw new RestApiValidationError(
-      `ID mismatch. URL path ID '${context.id}' does not match request body ID '${context.inputRecord.data.id}'`,
-      {
-        fields: ['data.id'],
-        violations: [{
-          field: 'data.id',
-          rule: 'id_consistency',
-          message: 'Request body ID must match URL path ID when both are provided'
-        }]
-      }
-    )
   }
 
   // Return key schema-related objects for direct use in the main methods
@@ -261,6 +212,61 @@ export const getMethodHookSuffix = (method) => {
   return method.charAt(0).toUpperCase() + method.slice(1)
 }
 
+export const validateCompleteReplacePayload = ({
+  context,
+  belongsToUpdates
+}) => {
+  const schemaInfo = context.schemaInfo || {}
+  const schemaStructure = schemaInfo.schemaStructure || {}
+  const idProperty = schemaInfo.idProperty || 'id'
+  const originalInputAttributes = context.originalInputAttributes || context.inputRecord?.data?.attributes || {}
+  const missingFields = []
+
+  for (const [fieldName, fieldDef] of Object.entries(schemaStructure)) {
+    if (!fieldDef) continue
+    if (fieldName === idProperty) continue
+    if (fieldDef.computed === true || fieldDef.virtual === true) continue
+    if (fieldDef.type === undefined) continue
+
+    if (fieldDef.belongsTo && fieldDef.as) {
+      if (Object.hasOwn(belongsToUpdates, fieldName)) continue
+
+      const existingRelationshipData = context.minimalRecord?.relationships?.[fieldDef.as]?.data
+      if (existingRelationshipData?.id !== undefined && existingRelationshipData?.id !== null) {
+        missingFields.push({
+          field: `data.relationships.${fieldDef.as}.data.id`,
+          message: `PUT requests must explicitly include relationship '${fieldDef.as}' when it already has a value`
+        })
+      }
+      continue
+    }
+
+    if (Object.hasOwn(originalInputAttributes, fieldName)) continue
+
+    const existingValue = context.minimalRecord?.attributes?.[fieldName]
+    if (existingValue !== undefined && existingValue !== null) {
+      missingFields.push({
+        field: `data.attributes.${fieldName}`,
+        message: `PUT requests must explicitly include attribute '${fieldName}' when it already has a value`
+      })
+    }
+  }
+
+  if (missingFields.length > 0) {
+    throw new RestApiValidationError(
+      'PUT request omits persisted fields that already have stored values',
+      {
+        fields: missingFields.map(({ field }) => field),
+        violations: missingFields.map(({ field, message }) => ({
+          field,
+          rule: 'complete_replacement',
+          message
+        }))
+      }
+    )
+  }
+}
+
 /**
  * Validates resource attributes before write operations
  *
@@ -285,9 +291,8 @@ export const validateResourceAttributesBeforeWrite = async ({
   await runHooks('beforeSchemaValidate')
   await runHooks(`beforeSchemaValidate${methodSpecificHookSuffix}`)
 
-  // Store original input attributes before validation adds defaults (primarily for POST)
-  // Only if it's not already set and the current method is POST
-  if (!context.originalInputAttributes && context.method === 'post') {
+  // Store original input attributes before validation adds defaults or casts.
+  if (!context.originalInputAttributes) {
     context.originalInputAttributes = { ...(context.inputRecord.data.attributes || {}) }
   }
 
@@ -361,9 +366,13 @@ export const validateResourceAttributesBeforeWrite = async ({
       return acc
     }, {})
 
-  const validationOptions = isPartialValidation ? { onlyObjectValues: true } : {}
+  const validationMethod = isPartialValidation
+    ? 'patch'
+    : context.method === 'put'
+      ? 'replace'
+      : 'create'
 
-  const { validatedObject, errors } = await schema.validate(attributesForValidation, validationOptions)
+  const { validatedObject, errors } = await schema[validationMethod](attributesForValidation)
 
   if (Object.keys(errors).length > 0) {
     // --- START OF MODIFICATION ---
@@ -416,11 +425,10 @@ export const validateResourceAttributesBeforeWrite = async ({
  * @param {object} context - The context object containing authentication info
  * @param {object} inputRecord - The input record containing relationships to validate
  * @param {object} helpers - Data helpers including dataGetMinimal
- * @param {function} runHooks - Function to run hooks
  * @param {object} api - API instance to access resources
  * @throws {Error} If user doesn't have access to any related resource
  */
-export const validateRelationshipAccess = async (context, inputRecord, helpers, runHooks, api) => {
+export const validateRelationshipAccess = async (context, inputRecord, helpers, api) => {
   if (!inputRecord?.data?.relationships) return
 
   for (const [relName, relData] of Object.entries(inputRecord.data.relationships)) {
@@ -442,19 +450,47 @@ export const validateRelationshipAccess = async (context, inputRecord, helpers,
         id: item.id,
         schemaInfo: relatedScope.vars.schemaInfo,
         scopeName: item.type,
+        queryParams: {},
         method: 'get', // We're checking read permission
         isUpdate: false
       }
 
+      const targetScope = api.resources?.[item.type]
+      const applyQueryFilters = targetScope?.applyQueryFilters
+        ? async ({ query, filters, tableName, db, scopeName, storageAdapter, isAnyApi }) => {
+          const queryState = await targetScope.applyQueryFilters({
+            query,
+            filters,
+            schemaInfo: getContext.schemaInfo,
+            scopeName,
+            tableName,
+            db,
+            isAnyApi,
+            storageAdapter
+          }, getContext)
+
+          return {
+            query: unwrapQueryBuilderState(queryState, query)
+          }
+        }
+        : undefined
+
       // Get the minimal record
       const record = await helpers.dataGetMinimal({
         scopeName: item.type,
         context: getContext,
-        runHooks
+        applyQueryFilters
       })
 
       if (!record) {
-        throw new Error(`Cannot create relationship to non-existent ${item.type} with id ${item.id}`)
+        throw new RestApiResourceError(
+          `Cannot create relationship to non-existent ${item.type} with id ${item.id}`,
+          {
+            subtype: 'not_found',
+            resourceType: item.type,
+            resourceId: item.id
+          }
+        )
       }
 
       // Check permissions using the related scope's checkPermissions
@@ -493,29 +529,31 @@ export const applyFieldSetters = async (attributes, schemaInfo, context, api, he
   const transformedAttributes = { ...attributes }
 
   for (const fieldName of sortedSetterFields) {
-    // Only process fields that exist in the attributes
-    if (fieldName in transformedAttributes) {
-      const setterInfo = fieldSetters[fieldName]
-      try {
-        const setterContext = {
-          attributes: transformedAttributes, // Current state with previous setters applied
-          fieldName,
-          originalValue: attributes[fieldName],
-          originalAttributes: attributes,
-          scopeName: context.scopeName,
-          method: context.method,
-          api,
-          helpers,
-          auth: context.auth
-        }
-        transformedAttributes[fieldName] = await setterInfo.setter(
-          transformedAttributes[fieldName],
-          setterContext
-        )
-      } catch (error) {
-        console.warn(`Setter for field '${fieldName}' failed:`, error)
-        // Keep original value if setter fails
+    const setterInfo = fieldSetters[fieldName]
+    const fieldPresent = fieldName in transformedAttributes
+    const hasDependencies = Array.isArray(setterInfo.runSetterAfter) && setterInfo.runSetterAfter.length > 0
+
+    if (!fieldPresent && !hasDependencies) continue
+
+    try {
+      const setterContext = {
+        attributes: transformedAttributes, // Current state with previous setters applied
+        fieldName,
+        originalValue: attributes[fieldName],
+        originalAttributes: attributes,
+        scopeName: context.scopeName,
+        method: context.method,
+        api,
+        helpers,
+        auth: context.auth
       }
+      transformedAttributes[fieldName] = await setterInfo.setter(
+        transformedAttributes[fieldName],
+        setterContext
+      )
+    } catch (error) {
+      console.warn(`Setter for field '${fieldName}' failed:`, error)
+      // Keep original value if setter fails
     }
   }
 

package/plugins/core/rest-api-plugin-methods/enrich-attributes.js

@@ -33,6 +33,7 @@ export default async function enrichAttributesMethod ({ context, params, runHook
   const computedFields = scopes[scopeName]?.vars?.schemaInfo?.computed || {}
   const fieldGetters = scopes[scopeName]?.vars?.schemaInfo?.fieldGetters || {}
   const sortedGetterFields = scopes[scopeName]?.vars?.schemaInfo?.sortedGetterFields || []
+  const queryFields = scopes[scopeName]?.vars?.queryFields || {}
 
   // Make a copy of attributes for transformation
   const transformedAttributes = { ...attributes }
@@ -72,7 +73,11 @@ export default async function enrichAttributesMethod ({ context, params, runHook
   // Filter hidden fields from attributes based on visibility rules
   // This removes hidden:true fields and normallyHidden:true fields (unless requested)
   const requestedFields = parentContext?.queryParams?.fields?.[scopeName]
-  const filteredAttributes = filterHiddenFields(transformedAttributes, { structure: schemaStructure }, requestedFields)
+  const filteredAttributes = filterHiddenFields(
+    transformedAttributes,
+    { structure: { ...schemaStructure, ...queryFields } },
+    requestedFields
+  )
 
   // Handle virtual fields - they need to be added from parent context if available
   // Virtual fields come from input and need to be preserved in responses

package/plugins/core/rest-api-plugin-methods/get.js

@@ -1,8 +1,8 @@
 import { RestApiResourceError } from '../../../lib/rest-api-errors.js'
-import { validateGetPayload } from '../lib/querying-writing/payload-validators.js'
 import { normalizeRecordAttributes } from '../lib/querying-writing/database-value-normalizers.js'
 import { getRequestedComputedFields } from '../lib/querying-writing/knex-field-helpers.js'
 import { transformJsonApiToSimplified } from '../lib/querying-writing/simplified-helpers.js'
+import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
 import { cascadeConfig } from './common.js'
 
 /**
@@ -41,11 +41,11 @@ export default async function getMethod ({
 
   // Assign common context properties
   context.schemaInfo = scopes[scopeName].vars.schemaInfo
-  context.queryParams = params.queryParams || {}
-
-  // These only make sense as parameter per query
-  context.queryParams.fields = cascadeConfig('fields', [context.queryParams], {})
-  context.queryParams.include = cascadeConfig('include', [context.queryParams], [])
+  const rawQueryParams = params.queryParams || {}
+  context.queryParams = {
+    fields: cascadeConfig('fields', [rawQueryParams], {}),
+    include: cascadeConfig('include', [rawQueryParams], [])
+  }
 
   context.transaction = params.transaction
   context.db = context.transaction || api.knex.instance
@@ -56,14 +56,23 @@ export default async function getMethod ({
   const schemaStructure = context.schemaInfo.schemaInstance.structure
   const schemaRelationships = context.schemaInfo.schemaRelationships
 
-  context.id = params.id
-
-  // Validate GET request to ensure required parameters are present and properly formatted.
-  // This checks that 'id' parameter exists and is not empty (you can't GET without an ID),
-  // validates 'include' contains valid relationship names (not arbitrary fields), and ensures
-  // 'fields' for sparse fieldsets follow the format fields[type]=comma,separated,list.
-  // Example: validates id: '123' exists, include: ['author', 'tags'] are real relationships.
-  validateGetPayload({ id: context.id, queryParams: context.queryParams }, vars.includeDepthLimit)
+  const requestContracts = getRequestContracts({
+    scopeName,
+    schemaInfo: context.schemaInfo,
+    includeDepthLimit: vars.includeDepthLimit,
+    sortableFields: vars.sortableFields
+  })
+  const validatedRequest = validateRequestContractOrThrow(
+    requestContracts.get,
+    {
+      id: params.id,
+      queryParams: context.queryParams
+    },
+    'GET request parameters are invalid'
+  )
+
+  context.id = validatedRequest.id
+  context.queryParams = validatedRequest.queryParams || {}
 
   // Fetch minimal record for authorization checks
   const minimalRecord = await helpers.dataGetMinimal({

package/plugins/core/rest-api-plugin-methods/patch.js

@@ -1,8 +1,8 @@
-import { RestApiResourceError } from '../../../lib/rest-api-errors.js'
-import { validatePatchPayload } from '../lib/querying-writing/payload-validators.js'
+import { RestApiResourceError, RestApiValidationError } from '../../../lib/rest-api-errors.js'
 import { processRelationships } from '../lib/writing/relationship-processor.js'
 import { updateManyToManyRelationship } from '../lib/writing/many-to-many-manipulations.js'
 import { ERROR_SUBTYPES } from '../lib/querying-writing/knex-constants.js'
+import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
 import {
   setupCommonRequest,
   validateResourceAttributesBeforeWrite,
@@ -49,23 +49,39 @@ export default async function patchMethod ({
       api,
       helpers
     })
-    context.id = context.inputRecord.data.id
-
     // Run early hooks for pre-processing (e.g., file handling)
     await runHooks('beforeProcessing')
     await runHooks('beforeProcessingPatch')
 
-    // Validate PATCH payload to ensure the partial update actually contains changes.
-    // PATCH requests must include either attributes to update or relationships to modify -
-    // an empty PATCH is invalid. This prevents accidental no-op requests and ensures clients
-    // are explicit about what they want to change. Unlike PUT, PATCH preserves all fields
-    // not mentioned in the request.
-    // Example: data must have either attributes: {title: 'New'} or relationships: {author: {...}}
-    validatePatchPayload(context.inputRecord, scopes)
+    const requestContracts = getRequestContracts({
+      scopeName,
+      schemaInfo: context.schemaInfo,
+      includeDepthLimit: vars.includeDepthLimit,
+      sortableFields: vars.sortableFields
+    })
+    context.inputRecord = validateRequestContractOrThrow(
+      requestContracts.patch,
+      context.inputRecord,
+      'PATCH request body is invalid'
+    )
+    if (params.id && String(params.id) !== String(context.inputRecord.data.id)) {
+      throw new RestApiValidationError(
+        `ID mismatch. URL path ID '${params.id}' does not match request body ID '${context.inputRecord.data.id}'`,
+        {
+          fields: ['data.id'],
+          violations: [{
+            field: 'data.id',
+            rule: 'id_consistency',
+            message: 'Request body ID must match URL path ID when both are provided'
+          }]
+        }
+      )
+    }
+    context.id = params.id || context.inputRecord.data.id
 
     // Validate that user has read access to all related resources
     // This ensures users can only create relationships to resources they can access
-    await validateRelationshipAccess(context, context.inputRecord, helpers, runHooks, api)
+    await validateRelationshipAccess(context, context.inputRecord, helpers, api)
 
     // Extract foreign keys from JSON:API relationships and prepare many-to-many operations
     // Example: relationships.author -> author_id: '123' for storage

package/plugins/core/rest-api-plugin-methods/post.js

@@ -1,5 +1,5 @@
-import { validatePostPayload } from '../lib/querying-writing/payload-validators.js'
 import { processRelationships } from '../lib/writing/relationship-processor.js'
+import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
 import { createPivotRecords } from '../lib/writing/many-to-many-manipulations.js'
 import {
   setupCommonRequest,
@@ -50,16 +50,21 @@ export default async function postMethod ({
     await runHooks('beforeProcessing')
     await runHooks('beforeProcessingPost')
 
-    // Validate POST payload to ensure it follows JSON:API format and references valid resources.
-    // This checks the payload has required 'data' object with 'type' and 'attributes', validates
-    // that data.type matches a real resource type (preventing creation of non-existent resources),
-    // and ensures any relationships reference valid resource types with proper ID format.
-    // Example: data.type: 'articles' must be a registered scope, relationships.author must reference 'users'.
-    validatePostPayload(context.inputRecord, scopes)
+    const requestContracts = getRequestContracts({
+      scopeName,
+      schemaInfo: context.schemaInfo,
+      includeDepthLimit: vars.includeDepthLimit,
+      sortableFields: vars.sortableFields
+    })
+    context.inputRecord = validateRequestContractOrThrow(
+      requestContracts.post,
+      context.inputRecord,
+      'POST request body is invalid'
+    )
 
     // Validate that user has read access to all related resources
     // This ensures users can only create relationships to resources they can access
-    await validateRelationshipAccess(context, context.inputRecord, helpers, runHooks, api)
+    await validateRelationshipAccess(context, context.inputRecord, helpers, api)
 
     // Extract foreign keys from JSON:API relationships and prepare many-to-many operations
     // Example: relationships.author -> author_id: '123' for storage

package/plugins/core/rest-api-plugin-methods/put.js

@@ -1,10 +1,11 @@
-import { RestApiResourceError } from '../../../lib/rest-api-errors.js'
-import { validatePutPayload } from '../lib/querying-writing/payload-validators.js'
+import { RestApiResourceError, RestApiValidationError } from '../../../lib/rest-api-errors.js'
 import { processRelationships } from '../lib/writing/relationship-processor.js'
 import { updateManyToManyRelationship, createPivotRecords } from '../lib/writing/many-to-many-manipulations.js'
 import { ERROR_SUBTYPES } from '../lib/querying-writing/knex-constants.js'
+import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
 import {
   setupCommonRequest,
+  validateCompleteReplacePayload,
   validateResourceAttributesBeforeWrite,
   validateRelationshipAccess,
   applyFieldSetters,
@@ -17,7 +18,9 @@ import {
  * PUT
  * Updates an existing top-level resource by completely replacing it.
  * This method supports updating both attributes and relationships (1:1 and n:n).
- * PUT is a complete replacement - any relationships not provided will be removed/nulled.
+ * Existing persisted values cannot be silently dropped: if a stored attribute or belongsTo
+ * relationship already has a value, PUT must include it explicitly. Relationship collections
+ * still follow replacement semantics when a relationships object is provided.
  * This method does NOT support creating new related resources via an `included` array.
  */
 export default async function putMethod ({
@@ -48,23 +51,39 @@ export default async function putMethod ({
       api,
       helpers
     })
-    context.id = context.inputRecord.data.id
-
     // Run early hooks for pre-processing (e.g., file handling)
     await runHooks('beforeProcessing')
     await runHooks('beforeProcessingPut')
 
-    // Validate PUT payload to ensure it's a complete resource replacement operation.
-    // PUT requires the full resource representation including ID (unlike POST which generates ID).
-    // It validates that data.id matches the URL parameter, prevents 'included' array (which is
-    // read-only), and ensures the payload represents a complete replacement. Any fields not
-    // provided will be removed or reset to defaults - this is the key difference from PATCH.
-    // Example: PUT to /articles/123 must have data.id: '123' and all required fields.
-    validatePutPayload(context.inputRecord, scopes)
+    const requestContracts = getRequestContracts({
+      scopeName,
+      schemaInfo: context.schemaInfo,
+      includeDepthLimit: vars.includeDepthLimit,
+      sortableFields: vars.sortableFields
+    })
+    context.inputRecord = validateRequestContractOrThrow(
+      requestContracts.put,
+      context.inputRecord,
+      'PUT request body is invalid'
+    )
+    if (params.id && String(params.id) !== String(context.inputRecord.data.id)) {
+      throw new RestApiValidationError(
+        `ID mismatch. URL path ID '${params.id}' does not match request body ID '${context.inputRecord.data.id}'`,
+        {
+          fields: ['data.id'],
+          violations: [{
+            field: 'data.id',
+            rule: 'id_consistency',
+            message: 'Request body ID must match URL path ID when both are provided'
+          }]
+        }
+      )
+    }
+    context.id = params.id || context.inputRecord.data.id
 
     // Validate that user has read access to all related resources
     // This ensures users can only create relationships to resources they can access
-    await validateRelationshipAccess(context, context.inputRecord, helpers, runHooks, api)
+    await validateRelationshipAccess(context, context.inputRecord, helpers, api)
 
     // Extract foreign keys from JSON:API relationships and prepare many-to-many operations
     // Example: relationships.author -> author_id: '123' for storage
@@ -74,13 +93,6 @@ export default async function putMethod ({
       { context }
     )
 
-    await validateResourceAttributesBeforeWrite({
-      context,
-      schema,
-      belongsToUpdates,
-      runHooks
-    })
-
     // Check existence first
     context.exists = await helpers.dataExists({
       scopeName,
@@ -108,8 +120,20 @@ export default async function putMethod ({
       context.minimalRecord = minimalRecord
     }
 
+    validateCompleteReplacePayload({
+      context,
+      belongsToUpdates
+    })
+
+    await validateResourceAttributesBeforeWrite({
+      context,
+      schema,
+      belongsToUpdates,
+      runHooks
+    })
+
     // For PUT, we also need to handle relationships that are NOT provided
-    // (they should be set to null/empty as PUT is a complete replacement)
+    // (they should be set to null/empty when a relationships object is provided)
     const allRelationships = {}
 
     // Collect all defined relationships for this resource