json-rest-api 1.0.28 → 1.0.29

package/docs/API.md

@@ -2549,6 +2549,8 @@ The library uses standard JSON:API error format:
 
 ### Custom Error Handling
 
+Typed API errors thrown by getters, setters, computed fields, file detectors, or upload adapters retain their original code and details. For example, throwing `new RestApiResourceError('Upload forbidden', { subtype: 'forbidden' })` from an upload adapter produces a 403 response and still runs temporary-file cleanup.
+
 ```javascript
 // In hooks
 api.resource('articles').hook('beforeDataPost', async (context) => {

package/docs/GUIDE/GUIDE_2_7_Pagination_And_Ordering.md

@@ -96,6 +96,8 @@ await api.resources.post_tags.createKnexTable();
 
 **Basic Pagination**
 
+When `sortableFields` is omitted or empty, visible stored schema fields and relationship aliases can be sorted. Query fields marked `sortable: true` are added to that set. Unknown fields and ordinary computed fields are rejected with 422. If a sort field is repeated, its first occurrence determines the direction.
+
 The API supports two types of pagination:
 
 1. **Offset-based pagination** using `page[number]` and `page[size]` parameters
@@ -671,6 +673,13 @@ Next multiField page: {
 
 **Cursor Pagination Notes:**
 - Cursors are simple strings containing the sort field values (format: `field:value,field2:value2`)
+- Sparse fieldsets may omit sort fields from the response; the Knex query still fetches those values internally to construct a complete cursor.
+- A cursor missing any active sort field is rejected with a validation error. Keep the same sort order when following a cursor.
+- Cursor values are validated against the sort field types. Invalid dates, numbers, or duplicate cursor fields produce HTTP 422.
+- `page[size]` and `page[number]` must be positive integers. Choose one of `page[number]`, `page[after]`, or `page[before]`; these cannot be combined.
+- Null sort values appear last in either sort direction. Generated cursors distinguish null from the literal string `"null"`; treat cursor strings as opaque values.
+- `page[before]` returns the adjacent preceding records in the requested sort order. Use a cursor for the first record of the current page to step back. When a backward response has more preceding records, its `links.next` and `meta.pagination.cursor.next` continue in the `before` direction.
+- Requested page sizes above `queryMaxLimit` are capped consistently for returned records, pagination metadata, and links.
 - The API automatically generates appropriate WHERE clauses based on sort direction
 - Cursor pagination is more efficient for large datasets as it doesn't need to count all records
 - Works seamlessly with any sort field, not just timestamps

package/docs/GUIDE/GUIDE_3_Field_Transformations.md

@@ -132,7 +132,7 @@ await api.addResource('users', {
 });
 ```
 
-If a setter throws or rejects, the write fails with a validation error and the transaction rolls back instead of storing the untransformed value.
+If a setter throws or rejects, the write fails and the transaction rolls back. Typed API errors retain their code and details; other setter failures become validation errors. Getters and computed fields also propagate typed API errors, including `RestApiTemporalDataError`, so invalid output cannot be silently accepted.
 
 ### Getters - Transform After Retrieval
 

package/docs/GUIDE/GUIDE_Y_Appendices.md

@@ -86,6 +86,20 @@ JavaScript `Date` objects, SQL datetime strings, Unix timestamps, locale text, a
 **Storage Format:**
 Schema validation preserves valid JSON temporal strings exactly. The built-in storage adapters convert `date` and `dateTime` strings to database-native `Date` values at the database boundary, while `time` remains a string. A custom field-level `storage.serialize` function receives the validated string and owns any custom database conversion.
 
+The built-in `dateTime` conversion supports millisecond precision. A value such
+as `2026-09-01T10:20:30.123456Z` fails with HTTP 422 before the write, because
+converting it to `Date` would lose information. Trailing zeroes beyond three
+digits are accepted (`.123000Z` represents exactly `.123Z`). To retain finer
+precision in table-backed storage, use a custom `storage.serialize` function
+and a database column and driver that preserve it. The same serializer is used
+for filters and cursor comparisons, with `operation: 'filter'` and `context: null`.
+
+Response normalization preserves fractional digits returned as strings by
+storage, up to the field's declared precision, including during conversion of
+timezone offsets to UTC. It also converts valid epoch strings and `bigint`
+values from database drivers to JSON numbers, rejecting invalid or out-of-range
+epoch data.
+
 ## Output Normalization
 
 ### Database to API Response
@@ -115,8 +129,9 @@ All date/time values are normalized when returned from the API:
 3. **UTC Assumption**: MySQL DATETIME values (which lack timezone info) are assumed to be UTC
 
 Normalization runs once after the database read and again at the final response
-boundary. The final pass covers getters, computed fields, and finishing hooks
-that produce native `Date` values. A malformed non-null temporal value is not
+boundary. The final pass covers getters, computed fields, query projections,
+and finishing hooks that produce native `Date` values, including nested
+relationships in simplified write responses. A malformed non-null temporal value is not
 reported as `null`; it fails with `REST_API_TEMPORAL_DATA_INVALID` and HTTP 500
 so stored-data or enrichment defects remain visible.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-rest-api",
-  "version": "1.0.28",
+  "version": "1.0.29",
   "main": "index.js",
   "type": "module",
   "scripts": {

package/plugins/core/file-handling-plugin.js

@@ -33,6 +33,7 @@
  */
 
 import { RestApiValidationError } from '../../lib/rest-api-errors.js'
+import { isRestApiError } from '../../lib/error-context.js'
 
 export const FileHandlingPlugin = {
   name: 'file-handling',
@@ -165,6 +166,7 @@ export const FileHandlingPlugin = {
             break
           }
         } catch (error) {
+          if (isRestApiError(error)) throw error
           log.warn(`Detector '${detector.name}' failed:`, error)
         }
       }
@@ -269,6 +271,7 @@ export const FileHandlingPlugin = {
             })
             log.debug(`Uploaded file for field '${fieldConfig.field}' to: ${storedUrl}`)
           } catch (error) {
+            if (isRestApiError(error)) throw error
             throw new RestApiValidationError(
               `Failed to upload file for field '${fieldConfig.field}': ${error.message}`,
               {

package/plugins/core/lib/querying/knex-pagination-helpers.js

@@ -158,7 +158,7 @@ export const generatePaginationLinks = (urlPrefix, scopeName, queryParams, pagin
 
   if (pageCount !== undefined) {
     links.first = buildJsonApiLink(baseUrl, queryParams, { number: 1, size: pageSize })
-    links.last = buildJsonApiLink(baseUrl, queryParams, { number: pageCount, size: pageSize })
+    links.last = buildJsonApiLink(baseUrl, queryParams, { number: Math.max(1, pageCount), size: pageSize })
 
     if (page > 1) {
       links.prev = buildJsonApiLink(baseUrl, queryParams, { number: page - 1, size: pageSize })
@@ -234,13 +234,17 @@ export const generatePaginationLinks = (urlPrefix, scopeName, queryParams, pagin
  * 4. Cursor used in 'next' link for fetching subsequent pages
  * 5. Enables efficient "WHERE (field1, field2) > (val1, val2)" queries
  */
-export const createCursor = (record, sortFields = ['id'], { schemaInfo = null } = {}) => {
+export const createCursor = (record, sortFields = ['id'], { schemaInfo = null, definitions = {} } = {}) => {
   const parts = []
   sortFields.forEach(field => {
     let value = schemaInfo
       ? getFieldValue(record, schemaInfo, field)
       : record[field]
-    const definition = schemaInfo?.schemaStructure?.[field]
+    const definition = definitions[field] || schemaInfo?.schemaStructure?.[field]
+    if (value === null) {
+      parts.push(`${field}:~null`)
+      return
+    }
     if (['date', 'dateTime', 'time'].includes(definition?.type) && value != null) {
       value = normalizeDateValue(value, definition.type, {
         temporalPrecision: definition.temporalPrecision,
@@ -251,7 +255,7 @@ export const createCursor = (record, sortFields = ['id'], { schemaInfo = null }
     }
     if (value !== undefined) {
       const stringValue = value instanceof Date ? value.toISOString() : String(value)
-      parts.push(`${field}:${encodeURIComponent(stringValue)}`)
+      parts.push(`${field}:${encodeURIComponent(stringValue).replace(/^~/, '%7E')}`)
     }
   })
   return parts.join(',')
@@ -311,7 +315,7 @@ export const createCursor = (record, sortFields = ['id'], { schemaInfo = null }
  */
 export const parseCursor = (cursor) => {
   try {
-    const data = {}
+    const data = Object.create(null)
     if (!cursor || cursor.trim() === '') {
       throw new Error('Empty cursor')
     }
@@ -331,7 +335,8 @@ export const parseCursor = (cursor) => {
         throw new Error('Invalid cursor format: empty field name')
       }
 
-      data[field] = decodeURIComponent(encodedValue)
+      if (Object.hasOwn(data, field)) throw new Error(`Duplicate cursor field '${field}'`)
+      data[field] = encodedValue === '~null' ? null : decodeURIComponent(encodedValue)
     }
 
     return data
@@ -423,7 +428,7 @@ export const generateCursorPaginationLinks = (
   pageSize,
   hasMore,
   sortFields = ['id'],
-  { schemaInfo = null } = {}
+  { schemaInfo = null, definitions = {} } = {}
 ) => {
   // Allow empty urlPrefix to generate relative links
   if (!records.length) return null
@@ -442,9 +447,10 @@ export const generateCursorPaginationLinks = (
   links.first = buildJsonApiLink(baseUrl, queryParams, { size: pageSize })
 
   if (hasMore && records.length > 0) {
-    const lastRecord = records[records.length - 1]
-    const nextCursor = createCursor(lastRecord, sortFields, { schemaInfo })
-    links.next = buildJsonApiLink(baseUrl, queryParams, { size: pageSize, after: nextCursor })
+    const direction = queryParams.page?.before ? 'before' : 'after'
+    const boundary = direction === 'before' ? records[0] : records[records.length - 1]
+    const nextCursor = createCursor(boundary, sortFields, { schemaInfo, definitions })
+    links.next = buildJsonApiLink(baseUrl, queryParams, { size: pageSize, [direction]: nextCursor })
   }
 
   return links
@@ -507,16 +513,16 @@ export const generateCursorPaginationLinks = (
  * 3. Added to response.meta.pagination
  * 4. Clients can use cursor directly or use the next link
  */
-export const buildCursorMeta = (records, pageSize, hasMore, sortFields = ['id'], { schemaInfo = null } = {}) => {
+export const buildCursorMeta = (records, pageSize, hasMore, sortFields = ['id'], { schemaInfo = null, definitions = {}, before = false } = {}) => {
   const meta = {
     pageSize,
     hasMore
   }
 
   if (hasMore && records.length > 0) {
-    const lastRecord = records[records.length - 1]
+    const lastRecord = before ? records[0] : records[records.length - 1]
     meta.cursor = {
-      next: createCursor(lastRecord, sortFields, { schemaInfo })
+      next: createCursor(lastRecord, sortFields, { schemaInfo, definitions })
     }
   }
 

package/plugins/core/lib/querying/query-field-sort-helpers.js

@@ -1,9 +1,55 @@
 import { normalizeStableSort, parseSortEntry } from './sort-helpers.js'
+import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
+import { createSchema } from 'json-rest-schema'
+import { normalizeValueForDatabaseStorage } from '../querying-writing/database-value-normalizers.js'
+
+export const validateCursorValues = (descriptors, cursorValues, parameter) => {
+  const validated = Object.create(null)
+  for (const { field, definition = {}, isRelationship } of descriptors) {
+    if (!Object.hasOwn(cursorValues, field)) continue
+    const value = cursorValues[field]
+    // Public resource IDs may be opaque strings, even when the storage schema
+    // uses the numeric id type for ordinary attributes.
+    const type = field === 'id' || isRelationship || definition?.type === 'id'
+      ? 'string'
+      : definition?.type
+    if (!type) {
+      validated[field] = value
+      continue
+    }
+    const contract = createSchema({
+      value: {
+        type,
+        noTrim: true,
+        nullable: field !== 'id',
+        ...(definition?.temporalPrecision !== undefined
+          ? { temporalPrecision: definition.temporalPrecision }
+          : {})
+      }
+    })
+    const { validatedObject, errors } = contract.patch({ value })
+    if (Object.keys(errors).length > 0 || (field === 'id' && !String(value ?? '').trim())) {
+      const path = `page.${parameter}`
+      throw new RestApiValidationError(`Invalid cursor value for sort field '${field}'.`, {
+        fields: [path],
+        violations: [{ field: path, rule: 'invalid_cursor_value', message: `Invalid ${type} value for '${field}'.` }]
+      })
+    }
+    validated[field] = validatedObject.value
+  }
+  return validated
+}
 
 export const getEffectiveSortableFields = (vars = {}) => {
-  const baseSortableFields = Array.isArray(vars.sortableFields)
+  const schema = vars.schemaInfo?.schemaStructure || {}
+  const baseSortableFields = Array.isArray(vars.sortableFields) && vars.sortableFields.length > 0
     ? vars.sortableFields
-    : []
+    : ['id', ...Object.keys(schema).filter((field) => {
+        const definition = schema[field]
+        return !definition.hidden && !definition.virtual && !definition.computed && !definition.belongsToPolymorphic
+      }), ...Object.entries(vars.schemaInfo?.searchSchemaStructure || {})
+        .filter(([, definition]) => definition.isRelationship && schema[definition.actualField]?.hidden !== true)
+        .map(([field]) => field)]
   const queryFieldSortableFields = Object.entries(vars.queryFields || {})
     .filter(([, fieldDef]) => fieldDef?.sortable === true)
     .map(([fieldName]) => fieldName)
@@ -29,15 +75,37 @@ export const buildEffectiveSortList = (sort, { defaultSort, idField = 'id' } = {
   return normalizeStableSort(sortList.length > 0 ? sortList : [idField], { idField })
 }
 
-export const applyQueryFieldOrder = (query, queryFieldRuntime, direction) => {
+export const applyQueryFieldOrder = (query, queryFieldRuntime, direction, nulls = 'last') => {
+  query.orderByRaw(`(${queryFieldRuntime.sql}) IS NULL ${nulls === 'last' ? 'ASC' : 'DESC'}`, queryFieldRuntime.bindings)
   query.orderByRaw(`(${queryFieldRuntime.sql}) ${direction}`, queryFieldRuntime.bindings)
 }
 
 export const applyQueryFieldPredicate = (builder, queryFieldRuntime, operator, value) => {
-  builder.whereRaw(`(${queryFieldRuntime.sql}) ${operator} ?`, [...queryFieldRuntime.bindings, value])
+  const definition = queryFieldRuntime.definition || {}
+  const normalizedValue = normalizeValueForDatabaseStorage(value, definition.type, {
+    temporalPrecision: definition.temporalPrecision
+  })
+  builder.whereRaw(`(${queryFieldRuntime.sql}) ${operator} ?`, [...queryFieldRuntime.bindings, normalizedValue])
 }
 
-export const applySortDescriptorPredicate = (builder, descriptor, operator, value, applyPlainPredicate) => {
+export const applySortDescriptorPredicate = (builder, descriptor, operator, value, applyPlainPredicate, includeNull = false) => {
+  if (includeNull) {
+    return builder.where(function () {
+      applySortDescriptorPredicate(this, descriptor, operator, value, applyPlainPredicate)
+      if (descriptor.queryFieldRuntime) {
+        this.orWhereRaw(`(${descriptor.queryFieldRuntime.sql}) IS NULL`, descriptor.queryFieldRuntime.bindings)
+      } else {
+        this.orWhereNull(descriptor.column)
+      }
+    })
+  }
+  if (value === null) {
+    const isNotNull = operator === 'IS NOT NULL'
+    if (descriptor.queryFieldRuntime) {
+      return builder.whereRaw(`(${descriptor.queryFieldRuntime.sql}) IS ${isNotNull ? 'NOT ' : ''}NULL`, descriptor.queryFieldRuntime.bindings)
+    }
+    return isNotNull ? builder.whereNotNull(descriptor.column) : builder.whereNull(descriptor.column)
+  }
   if (descriptor?.queryFieldRuntime) {
     return applyQueryFieldPredicate(builder, descriptor.queryFieldRuntime, operator, value)
   }
@@ -62,19 +130,27 @@ export const buildCursorPredicateChains = (
 
     if (cursorValue === undefined) {
       onMissingValue?.(descriptor.field)
-      return
+      throw new RestApiValidationError(`Cursor is missing a value for sort field '${descriptor.field}'.`, {
+        fields: [descriptor.field],
+        violations: [{
+          field: descriptor.field,
+          rule: 'missing_cursor_value',
+          message: 'Cursor must include every sort field.'
+        }]
+      })
     }
 
+    const operator = operatorSelector(descriptor.direction)
+    const forward = operator === (descriptor.direction.toUpperCase() === 'DESC' ? '<' : '>')
+    // Nulls sort last. There are no values after null at this sort position,
+    // but later tie breakers can still advance within the null group.
+    if (cursorValue === null && forward) return
+
     const chain = []
     for (let i = 0; i < index; i += 1) {
       const previousDescriptor = descriptors[i]
       const previousValue = cursorValues?.[previousDescriptor.field]
 
-      if (previousValue === undefined) {
-        onMissingValue?.(previousDescriptor.field)
-        return
-      }
-
       chain.push({
         descriptor: previousDescriptor,
         operator: '=',
@@ -84,8 +160,9 @@ export const buildCursorPredicateChains = (
 
     chain.push({
       descriptor,
-      operator: operatorSelector(descriptor.direction),
-      value: cursorValue
+      operator: cursorValue === null ? 'IS NOT NULL' : operator,
+      value: cursorValue,
+      includeNull: cursorValue !== null && forward
     })
 
     predicateChains.push(chain)
@@ -116,13 +193,14 @@ export const applyCursorPredicate = (
   query.where(function () {
     predicateChains.forEach((chain) => {
       this.orWhere(function () {
-        chain.forEach(({ descriptor, operator, value }) => {
+        chain.forEach(({ descriptor, operator, value, includeNull }) => {
           applySortDescriptorPredicate(
             this,
             descriptor,
             operator,
             value,
-            applyPlainPredicate
+            applyPlainPredicate,
+            includeNull
           )
         })
       })

package/plugins/core/lib/querying/sort-helpers.js

@@ -1,6 +1,13 @@
 export function normalizeStableSort (sort = [], { idField = 'id' } = {}) {
+  const seenFields = new Set()
   const sortList = Array.isArray(sort)
-    ? sort.filter((entry) => typeof entry === 'string' && entry.trim())
+    ? sort.filter((entry) => {
+      if (typeof entry !== 'string' || !entry.trim()) return false
+      const field = entry.startsWith('-') ? entry.slice(1) : entry
+      if (seenFields.has(field)) return false
+      seenFields.add(field)
+      return true
+    })
     : []
 
   if (sortList.length === 0) {

package/plugins/core/lib/querying-writing/database-value-normalizers.js

@@ -1,5 +1,5 @@
 import { createSchema } from 'json-rest-schema'
-import { RestApiTemporalDataError } from '../../../../lib/rest-api-errors.js'
+import { RestApiTemporalDataError, RestApiValidationError } from '../../../../lib/rest-api-errors.js'
 
 const DATE_VALUE_PATTERN = /^\d{4}-\d{2}-\d{2}$/
 const RFC3339_DATETIME_PATTERN = /^(\d{4}-\d{2}-\d{2})T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/
@@ -71,12 +71,12 @@ const parseEpochDatabaseValue = (value) => {
 
 const parseKnownDatabaseDate = (value, { fieldName, resourceType, type, source }) => {
   if (value instanceof Date) {
-    if (!Number.isNaN(value.getTime())) return value
+    if (!Number.isNaN(value.getTime())) return value.toISOString()
     throwTemporalDataError({ fieldName, resourceType, type, source })
   }
 
   const epochDate = parseEpochDatabaseValue(value)
-  if (epochDate) return epochDate
+  if (epochDate) return epochDate.toISOString()
 
   if (typeof value !== 'string') {
     throwTemporalDataError({ fieldName, resourceType, type, source })
@@ -106,7 +106,11 @@ const parseKnownDatabaseDate = (value, { fieldName, resourceType, type, source }
   if (Number.isNaN(parsed.getTime())) {
     throwTemporalDataError({ fieldName, resourceType, type, source })
   }
-  return parsed
+  // Date handles the offset, but cannot retain digits beyond milliseconds.
+  const fraction = /\.(\d+)(?:Z|[+-]\d{2}:\d{2})$/.exec(dateTimeValue)?.[1]
+  return fraction
+    ? parsed.toISOString().replace(/\.\d{3}Z$/, `.${fraction}Z`)
+    : parsed.toISOString()
 }
 
 /**
@@ -146,8 +150,7 @@ export function normalizeDateValue (value, type, {
     })
   }
 
-  const dateValue = parseKnownDatabaseDate(value, { fieldName, resourceType, type, source })
-  const isoValue = dateValue.toISOString()
+  const isoValue = parseKnownDatabaseDate(value, { fieldName, resourceType, type, source })
   const normalized = type === 'date'
     ? isoValue.slice(0, 10)
     : limitFractionalSecondPrecision(isoValue, temporalPrecision)
@@ -202,6 +205,20 @@ export function normalizeValueForDatabaseStorage (value, type, {
     resourceType,
     source
   })
+  const fraction = type === 'dateTime'
+    ? /\.(\d+)(?:Z|[+-]\d{2}:\d{2})$/.exec(validatedValue)?.[1]
+    : null
+  if (fraction && /[1-9]/.test(fraction.slice(3))) {
+    const field = fieldName ? `data.attributes.${fieldName}` : 'value'
+    throw new RestApiValidationError('Built-in dateTime storage supports millisecond precision.', {
+      fields: [field],
+      violations: [{
+        field,
+        rule: 'storage_precision',
+        message: 'Submillisecond values require a custom storage serializer.'
+      }]
+    })
+  }
   const databaseValue = new Date(
     type === 'date' ? `${validatedValue}T00:00:00Z` : validatedValue
   )
@@ -323,6 +340,12 @@ export function normalizeAttributes (attributes, schemaStructure, {
         resourceType,
         source
       })
+    } else if (['epochMilliseconds', 'epochSeconds'].includes(fieldDef.type) && value != null) {
+      normalized[fieldName] = validateTemporalJsonValue(
+        typeof value === 'bigint' ? String(value) : value,
+        fieldDef.type,
+        { fieldName, resourceType, source }
+      )
     }
   }
 
@@ -420,11 +443,19 @@ export function normalizeAttributes (attributes, schemaStructure, {
  * 4. Processes included array the same way
  * 5. Returns complete response with normalized values
  */
-export function normalizeRecordAttributes (record, scopes, { source = 'database' } = {}) {
+export function normalizeRecordAttributes (record, scopes, {
+  source = 'database',
+  simplified = false,
+  resourceType
+} = {}) {
   if (!record || !scopes) {
     return record
   }
 
+  if (simplified) {
+    return normalizeSimplifiedRecord(record, resourceType, scopes, { source })
+  }
+
   const normalizeEntry = (entry) => {
     const schemaInfo = scopes[entry?.type]?.vars?.schemaInfo
     if (!schemaInfo || !entry?.attributes) return
@@ -433,7 +464,8 @@ export function normalizeRecordAttributes (record, scopes, { source = 'database'
       entry.attributes,
       {
         ...(schemaInfo.schemaStructure || {}),
-        ...(schemaInfo.computed || {})
+        ...(schemaInfo.computed || {}),
+        ...(scopes[entry.type]?.vars?.queryFields || {})
       },
       {
         resourceType: entry.type,
@@ -464,3 +496,37 @@ export function normalizeRecordAttributes (record, scopes, { source = 'database'
 
   return record
 }
+
+function normalizeSimplifiedRecord (record, resourceType, scopes, options, visited = new WeakMap()) {
+  if (!record || typeof record !== 'object') return record
+  if (visited.has(record)) return visited.get(record)
+  const schemaInfo = scopes[resourceType]?.vars?.schemaInfo
+  if (!schemaInfo) return record
+
+  const schema = { ...schemaInfo.schemaStructure, ...schemaInfo.computed, ...scopes[resourceType]?.vars?.queryFields }
+  const normalized = normalizeAttributes(record, schema, { ...options, resourceType })
+  visited.set(record, normalized)
+  const relationships = { ...schemaInfo.schemaRelationships }
+  for (const definition of Object.values(schema)) {
+    if (definition.as && (definition.belongsTo || definition.belongsToPolymorphic)) {
+      relationships[definition.as] = definition
+    }
+  }
+  for (const [name, definition] of Object.entries(relationships)) {
+    const normalizeRelated = (entry) => normalizeSimplifiedRecord(
+      entry,
+      definition.belongsToPolymorphic
+        ? entry?._type
+        : definition.belongsTo || definition.target || name,
+      scopes,
+      options,
+      visited
+    )
+    if (Object.hasOwn(normalized, name)) {
+      normalized[name] = Array.isArray(normalized[name])
+        ? normalized[name].map(normalizeRelated)
+        : normalizeRelated(normalized[name])
+    }
+  }
+  return normalized
+}

package/plugins/core/lib/querying-writing/knex-field-helpers.js

@@ -3,6 +3,15 @@ import { createSelectTranslator } from '../storage/storage-adapter.js'
 import { buildQueryFieldRuntimes } from './query-field-helpers.js'
 import { RestApiFieldsetError } from '../../../../lib/rest-api-errors.js'
 
+export const validateRequestedFieldsets = async (context, scopes) => {
+  for (const scopeName of Object.keys(context.queryParams?.fields || {})) {
+    if (!scopes[scopeName]?.vars?.schemaInfo) continue
+    await buildFieldSelection(scopes[scopeName], {
+      context: { scopeName, queryParams: { fields: context.queryParams.fields } }
+    })
+  }
+}
+
 /**
  * Checks if a field exists only in code, not in the database
  *
@@ -212,7 +221,7 @@ export const buildFieldSelection = async (scope, deps) => {
       if (nonDatabaseFields.has(field)) return
 
       const fieldDef = schemaStructure[field]
-      if (!fieldDef) {
+      if (!Object.hasOwn(schemaStructure, field) || !fieldDef) {
         throw new RestApiFieldsetError({
           field,
           resourceType: scopeName
@@ -325,6 +334,11 @@ export const buildFieldSelection = async (scope, deps) => {
 
     if (queryFieldNames.has(normalizedField)) {
       queryFieldsToSelect.add(normalizedField)
+    } else if (schemaStructure[normalizedField] &&
+               schemaStructure[normalizedField].hidden !== true &&
+               !nonDatabaseFields.has(normalizedField)) {
+      // Cursor generation needs sort values even when the response omits them.
+      fieldsToSelect.add(normalizedField)
     }
   }
 

package/plugins/core/lib/querying-writing/request-contracts.js

@@ -76,12 +76,12 @@ function buildFieldMapJsonSchemaFragment () {
 
 function buildKnownPageSchema () {
   return createSchema({
-    number: { type: 'number' },
-    size: { type: 'number' },
-    limit: { type: 'number' },
-    offset: { type: 'number' },
-    after: { type: 'string' },
-    before: { type: 'string' },
+    number: { type: 'integer', min: 1 },
+    size: { type: 'integer', min: 1 },
+    limit: { type: 'integer', min: 1 },
+    offset: { type: 'integer', min: 0 },
+    after: { type: 'string', min: 1 },
+    before: { type: 'string', min: 1 },
     cursor: { type: 'string' }
   })
 }
@@ -313,6 +313,16 @@ function installRequestContractSupport () {
       const firstError = pickFirstError(errors)
       context.throwParamError(firstError?.code || 'INVALID_PAGE', firstError?.message || 'Invalid page parameters.')
     }
+    for (const direction of ['after', 'before']) {
+      if (Object.hasOwn(knownPageParams, direction) && !validatedObject[direction]?.trim()) {
+        context.throwParamError('INVALID_PAGE', `page[${direction}] must contain a cursor.`)
+      }
+    }
+
+    if ((validatedObject.after !== undefined && validatedObject.before !== undefined) ||
+        (validatedObject.number !== undefined && (validatedObject.after !== undefined || validatedObject.before !== undefined))) {
+      context.throwParamError('INVALID_PAGE', 'Use either page[number], page[after], or page[before].')
+    }
 
     return {
       ...context.value,

package/plugins/core/lib/storage/storage-adapter.js

@@ -1,6 +1,7 @@
 import {
   getFieldValue as getLegacyFieldValue,
   getIdColumn,
+  getStorageInfo,
   getStorageColumn,
   translateAttributesForStorage,
 } from './storage-mapping.js'
@@ -177,7 +178,20 @@ const createLegacyAdapter = ({ knex, schemaInfo }) => {
   const getFieldValue = (record, fieldName) => getLegacyFieldValue(record, schemaInfo, fieldName)
   const translateFilterValue = (field, value) => {
     const searchField = schemaInfo.searchSchemaStructure?.[field]
-    const schemaField = schemaInfo.schemaStructure?.[field]
+    const fieldName = searchField?.actualField || field
+    const schemaField = schemaInfo.schemaStructure?.[fieldName]
+    const fieldStorage = getStorageInfo(schemaInfo).fields[fieldName]
+    if (fieldStorage?.serialize) {
+      const serialize = (entry) => fieldStorage.serialize(entry, {
+        fieldName,
+        columnName: fieldStorage.column,
+        definition: fieldStorage.definition,
+        schemaInfo,
+        context: null,
+        operation: 'filter'
+      })
+      return Array.isArray(value) ? value.map(serialize) : serialize(value)
+    }
     const definition = searchField || schemaField || {}
     const isRelationship = Boolean(
       searchField?.isRelationship ||