@jskit-ai/crud-core 0.1.179 → 0.1.181

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/crud-core",
-  "version": "0.1.179",
+  "version": "0.1.181",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -23,9 +23,9 @@
     "./server/routeContracts": "./src/server/routeContracts.js"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime": "0.1.168",
-    "@jskit-ai/json-rest-api-core": "0.1.112",
-    "@jskit-ai/resource-crud-core": "0.1.110",
+    "@jskit-ai/database-runtime": "0.1.170",
+    "@jskit-ai/json-rest-api-core": "0.1.114",
+    "@jskit-ai/resource-crud-core": "0.1.112",
     "json-rest-schema": "^1.0.17"
   },
   "description": "Shared server-side CRUD service, repository, route, and query helpers.",
@@ -45,7 +45,7 @@
     }
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.1.166",
-    "@jskit-ai/kernel": "0.1.168"
+    "@jskit-ai/http-runtime": "0.1.168",
+    "@jskit-ai/kernel": "0.1.170"
   }
 }

package/patterns/json-api-resource-package/example/packages/books/package.json

@@ -8,8 +8,8 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.1.179",
-    "@jskit-ai/resource-crud-core": "0.1.110"
+    "@jskit-ai/crud-core": "0.1.181",
+    "@jskit-ai/resource-crud-core": "0.1.112"
   },
   "jskit": {
     "kind": "runtime",

package/src/server/jsonApiModule/actions.js

@@ -3,6 +3,7 @@ import {
   createSchema,
   recordIdParamsValidator
 } from "@jskit-ai/kernel/shared/validators";
+import { normalizeJsonApiFieldsets } from "@jskit-ai/kernel/shared/support/jsonApiFieldsets";
 import { createEntityChangedActionEvent } from "@jskit-ai/kernel/server/actions";
 import {
   decodeJsonApiResourceResponse,
@@ -10,8 +11,13 @@ import {
   unwrapJsonApiResult
 } from "@jskit-ai/http-runtime/shared";
 import { resolveCrudRecordChangedEvent } from "@jskit-ai/resource-crud-core/shared/crudNamespaceSupport";
-import { resolveJsonApiRelationshipEntries } from "../routeContracts.js";
 import {
+  resolveJsonApiFieldsetContract,
+  resolveJsonApiRelationshipEntries,
+  resolveSchemaFieldDefinitions
+} from "../jsonApiResourceContract.js";
+import {
+  createJsonApiFieldsetsQueryValidator,
   createStandardCrudListQueryValidators,
   createStandardCrudViewQueryValidators
 } from "../listQueryValidators.js";
@@ -49,11 +55,6 @@ function resolveAssistantResultValue(result) {
   };
 }
 
-function resolveSchemaFieldDefinitions(definition = null) {
-  const definitions = definition?.schema?.getFieldDefinitions?.();
-  return isRecord(definitions) ? definitions : {};
-}
-
 function createProjectionRecordSchema(recordSchema, {
   lookupContainerKey = "",
   relationshipEntries = []
@@ -166,6 +167,102 @@ function createCrudAssistantTransport(resource, operation, relationshipEntries,
   });
 }
 
+function projectCrudAssistantRecordFields(record, selectedFields = null, {
+  preserveKeys = []
+} = {}) {
+  if (!isRecord(record) || !Array.isArray(selectedFields)) {
+    return record;
+  }
+
+  const allowedKeys = new Set(["id", ...preserveKeys, ...selectedFields]);
+  return Object.fromEntries(
+    Object.entries(record).filter(([key]) => allowedKeys.has(key))
+  );
+}
+
+function projectCrudAssistantLookupValue(value, selectedFields = null) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => projectCrudAssistantRecordFields(entry, selectedFields));
+  }
+  return projectCrudAssistantRecordFields(value, selectedFields);
+}
+
+function projectCrudAssistantReadRecord(record, {
+  lookupContainerKey = "",
+  primaryFields = null,
+  relatedFieldsByLookupKey = new Map()
+} = {}) {
+  if (!isRecord(record)) {
+    return record;
+  }
+
+  const primaryProjection = projectCrudAssistantRecordFields(record, primaryFields, {
+    preserveKeys: lookupContainerKey && isRecord(record[lookupContainerKey])
+      ? [lookupContainerKey]
+      : []
+  });
+  const projectedRecord = primaryProjection === record ? { ...record } : primaryProjection;
+  if (!lookupContainerKey || !isRecord(projectedRecord[lookupContainerKey])) {
+    return projectedRecord;
+  }
+
+  projectedRecord[lookupContainerKey] = Object.fromEntries(
+    Object.entries(projectedRecord[lookupContainerKey]).map(([lookupKey, value]) => {
+      return [
+        lookupKey,
+        projectCrudAssistantLookupValue(value, relatedFieldsByLookupKey.get(lookupKey))
+      ];
+    })
+  );
+  return projectedRecord;
+}
+
+function createCrudAssistantResultProjection(input = {}, resource = {}, relationshipEntries = []) {
+  const primaryType = String(resource?.namespace || "").trim();
+  const fieldsets = normalizeJsonApiFieldsets(input?.fields, {
+    primaryType
+  });
+  if (Object.keys(fieldsets).length < 1) {
+    return null;
+  }
+
+  const relatedFieldsByLookupKey = new Map();
+  for (const entry of relationshipEntries) {
+    const selectedFields = fieldsets[entry.relationshipType];
+    if (!Array.isArray(selectedFields)) {
+      continue;
+    }
+    relatedFieldsByLookupKey.set(entry.relationshipName, selectedFields);
+    relatedFieldsByLookupKey.set(entry.attributeKey, selectedFields);
+  }
+
+  return {
+    primaryFields: fieldsets[primaryType],
+    relatedFieldsByLookupKey
+  };
+}
+
+function projectCrudAssistantReadResult(result, projection = null, {
+  lookupContainerKey = ""
+} = {}) {
+  if (!projection) {
+    return result;
+  }
+
+  const projectionOptions = {
+    ...projection,
+    lookupContainerKey
+  };
+  if (isRecord(result) && Array.isArray(result.items)) {
+    return {
+      ...result,
+      items: result.items.map((entry) => projectCrudAssistantReadRecord(entry, projectionOptions))
+    };
+  }
+
+  return projectCrudAssistantReadRecord(result, projectionOptions);
+}
+
 function transformCrudAssistantResult(operation, result, {
   input = {},
   resource,
@@ -184,39 +281,84 @@ function transformCrudAssistantResult(operation, result, {
   }
 
   const resolved = resolveAssistantResultValue(result);
+  const projection = operation === "list" || operation === "view"
+    ? createCrudAssistantResultProjection(input, resource, relationshipEntries)
+    : null;
+  const projectReadResult = (value) => projectCrudAssistantReadResult(value, projection, {
+    lookupContainerKey
+  });
   if (operation === "list") {
     if (resolved.document.kind === "collection") {
       const decoded = decodeJsonApiResourceResponse(
         resolved.value,
         createCrudAssistantTransport(resource, operation, relationshipEntries, lookupContainerKey)
       );
-      return {
+      return projectReadResult({
         items: decoded.items,
         nextCursor: normalizeOptionalCursor(decoded.nextCursor)
-      };
+      });
     }
     if (Array.isArray(resolved.value)) {
-      return {
+      return projectReadResult({
         items: resolved.value,
         nextCursor: null
-      };
+      });
     }
     if (isRecord(resolved.value) && Array.isArray(resolved.value.items)) {
-      return {
+      return projectReadResult({
         items: resolved.value.items,
         nextCursor: normalizeOptionalCursor(resolved.value.nextCursor)
-      };
+      });
     }
     return resolved.value;
   }
 
   if (resolved.document.kind === "resource") {
-    return decodeJsonApiResourceResponse(
+    return projectReadResult(decodeJsonApiResourceResponse(
       resolved.value,
       createCrudAssistantTransport(resource, operation, relationshipEntries, lookupContainerKey)
-    );
+    ));
   }
-  return resolved.value;
+  return projectReadResult(resolved.value);
+}
+
+function createCrudAssistantReadDescription({
+  fieldsetContract,
+  lookupContainerKey = "",
+  namespace = "",
+  operation = "list"
+} = {}) {
+  const relationshipEntries = fieldsetContract.relationshipEntries;
+  const firstRelationship = relationshipEntries[0] || null;
+  const includeExample = relationshipEntries.length > 0
+    ? relationshipEntries.slice(0, 2).map((entry) => entry.relationshipName).join(",")
+    : "pet,service";
+  const fieldsExample = firstRelationship
+    ? ` fields can be {\"${namespace}\":[\"${firstRelationship.attributeKey}\"],` +
+      `\"${firstRelationship.relationshipType}\":[\"${firstRelationship.labelKey || "id"}\"]}.`
+    : ` fields can be {\"${namespace}\":[\"id\"]}.`;
+  const aliasGuidance = fieldsetContract.aliasMappings
+    .map((entry) => `use \"${entry.resourceType}\" instead of \"${entry.alias}\"`)
+    .join("; ");
+  const fieldsetKeyGuidance = fieldsetContract.resourceTypes.length > 0
+    ? ` fields keys must be JSON:API resource types: ${fieldsetContract.resourceTypes.map((entry) => `\"${entry}\"`).join(", ")}.` +
+      (aliasGuidance ? ` Relationship aliases are invalid fieldset keys; ${aliasGuidance}.` : "")
+    : "";
+  const primaryFieldGuidance = fieldsetContract.primaryFields.length > 0
+    ? ` Valid \"${namespace}\" fields: ${fieldsetContract.primaryFields.map((entry) => `\"${entry}\"`).join(", ")}.`
+    : "";
+  const relationshipGuidance = relationshipEntries.length > 0
+    ? ` Include relationships: ${relationshipEntries.map((entry) => {
+        const lookupPath = lookupContainerKey
+          ? ` -> ${operation === "list" ? "items[]." : ""}${lookupContainerKey}.${entry.relationshipName}`
+          : "";
+        return `\"${entry.relationshipName}\" -> resource type \"${entry.relationshipType}\"${lookupPath}`;
+      }).join("; ")}.`
+    : "";
+
+  const subject = operation === "list" ? `List ${namespace} records.` : `View a ${namespace} record.`;
+  return `${subject} include must be a comma-separated string such as \"${includeExample}\";` +
+    `${fieldsExample}${fieldsetKeyGuidance}${primaryFieldGuidance}${relationshipGuidance}`;
 }
 
 function createCrudAssistantExtension(resource, namespace, operation) {
@@ -236,24 +378,18 @@ function createCrudAssistantExtension(resource, namespace, operation) {
     relationshipEntries,
     lookupContainerKey
   );
-  const firstRelationship = relationshipEntries[0] || null;
-  const fieldsExample = firstRelationship
-    ? ` fields can be {\"${namespace}\":[\"${firstRelationship.attributeKey}\"],` +
-      `\"${firstRelationship.relationshipType}\":[\"${firstRelationship.labelKey || "id"}\"]}.`
-    : ` fields can be {\"${namespace}\":[\"id\"]}.`;
-  const lookupExample = firstRelationship && lookupContainerKey
-    ? ` Included fields are returned under ${operation === "list" ? "items[]." : ""}${lookupContainerKey}.` +
-      `${firstRelationship.relationshipName}.${firstRelationship.labelKey || "<selectedField>"}.`
-    : "";
-  const actionLabel = operation === "list"
-    ? `List ${namespace} records. include must be a comma-separated string such as \"pet,service\";${fieldsExample}${lookupExample}`
-    : operation === "view"
-      ? `View a ${namespace} record. include must be a comma-separated string such as \"pet,service\";${fieldsExample}${lookupExample}`
-      : operation === "create"
-        ? `Create a ${namespace} record.`
-        : operation === "update"
-          ? `Update a ${namespace} record.`
-          : `Delete a ${namespace} record.`;
+  const actionLabel = operation === "list" || operation === "view"
+    ? createCrudAssistantReadDescription({
+        fieldsetContract: resolveJsonApiFieldsetContract(resource),
+        lookupContainerKey,
+        namespace,
+        operation
+      })
+    : operation === "create"
+      ? `Create a ${namespace} record.`
+      : operation === "update"
+        ? `Update a ${namespace} record.`
+        : `Delete a ${namespace} record.`;
 
   return Object.freeze({
     description: actionLabel,
@@ -278,9 +414,15 @@ function createActionInput(
 ) {
   const definitions = scopeInputValidator ? [scopeInputValidator] : [];
   if (operation === "list") {
-    definitions.push(...createStandardCrudListQueryValidators({ resource, listFilterQueryValidator }));
+    definitions.push(...createStandardCrudListQueryValidators({
+      resource,
+      listFilterQueryValidator,
+      fieldsetsQueryValidator: createJsonApiFieldsetsQueryValidator({ resource })
+    }));
   } else if (operation === "view") {
-    definitions.push(recordIdParamsValidator, ...createStandardCrudViewQueryValidators());
+    definitions.push(recordIdParamsValidator, ...createStandardCrudViewQueryValidators({
+      fieldsetsQueryValidator: createJsonApiFieldsetsQueryValidator({ resource })
+    }));
   } else if (operation === "create") {
     definitions.push(operationInputs.create || resource.operations.create.body);
   } else if (operation === "update") {

package/src/server/jsonApiResourceContract.js

@@ -0,0 +1,119 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { resolveCrudResourceScopeName } from "@jskit-ai/resource-crud-core/shared/crudLookup";
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function resolveSchemaFieldDefinitions(definition = null) {
+  const schema = definition?.schema;
+  if (!schema || typeof schema.getFieldDefinitions !== "function") {
+    return {};
+  }
+
+  const definitions = schema.getFieldDefinitions();
+  return isRecord(definitions) ? definitions : {};
+}
+
+function resolveJsonApiRelationshipEntries(definition = null) {
+  const entries = [];
+
+  for (const [fieldKey, fieldDefinition] of Object.entries(resolveSchemaFieldDefinitions(definition))) {
+    const normalizedFieldDefinition = isRecord(fieldDefinition) ? fieldDefinition : {};
+    const relationshipType = String(normalizedFieldDefinition.belongsTo || "").trim();
+    if (relationshipType) {
+      const relationshipName = String(normalizedFieldDefinition.as || fieldKey || "").trim();
+      if (!relationshipName) {
+        continue;
+      }
+
+      entries.push(Object.freeze({
+        attributeKey: fieldKey,
+        relationshipName,
+        relationshipType,
+        labelKey: String(normalizedFieldDefinition?.relation?.labelKey || "").trim(),
+        required: normalizedFieldDefinition.required === true,
+        nullable: normalizedFieldDefinition.nullable === true
+      }));
+      continue;
+    }
+
+    const relation = isRecord(normalizedFieldDefinition.relation)
+      ? normalizedFieldDefinition.relation
+      : {};
+    if (String(relation.kind || "").trim().toLowerCase() !== "collection") {
+      continue;
+    }
+
+    const collectionRelationshipType = resolveCrudResourceScopeName(
+      relation.target || relation.targetResource || relation.namespace || relation.apiPath
+    );
+    if (!collectionRelationshipType) {
+      continue;
+    }
+
+    const collectionRelationshipName = String(
+      relation.as || normalizedFieldDefinition.as || fieldKey || ""
+    ).trim();
+    if (!collectionRelationshipName) {
+      continue;
+    }
+
+    entries.push(Object.freeze({
+      attributeKey: fieldKey,
+      relationshipName: collectionRelationshipName,
+      relationshipType: collectionRelationshipType,
+      labelKey: String(relation.labelKey || "").trim(),
+      many: true,
+      required: normalizedFieldDefinition.required === true,
+      nullable: normalizedFieldDefinition.nullable === true
+    }));
+  }
+
+  return Object.freeze(entries);
+}
+
+function resolveJsonApiFieldsetContract(resource = {}) {
+  const primaryType = normalizeText(resource?.namespace);
+  const relationshipEntries = resolveJsonApiRelationshipEntries(resource?.operations?.view?.output);
+  const lookupContainerKey = normalizeText(resource?.contract?.lookup?.containerKey);
+  const primaryFields = Object.freeze(
+    Object.keys(resolveSchemaFieldDefinitions(resource?.operations?.view?.output))
+      .map((entry) => normalizeText(entry))
+      .filter((entry) => entry && entry !== lookupContainerKey)
+  );
+  const aliasMappings = Object.freeze(
+    relationshipEntries
+      .filter((entry) => entry.relationshipName !== entry.relationshipType)
+      .map((entry) => Object.freeze({
+        alias: entry.relationshipName,
+        resourceType: entry.relationshipType
+      }))
+  );
+  const resourceTypes = [];
+  const seenTypes = new Set();
+  for (const resourceType of [
+    primaryType,
+    ...relationshipEntries.map((entry) => normalizeText(entry.relationshipType))
+  ]) {
+    if (!resourceType || seenTypes.has(resourceType)) {
+      continue;
+    }
+    seenTypes.add(resourceType);
+    resourceTypes.push(resourceType);
+  }
+
+  return Object.freeze({
+    aliasMappings,
+    primaryType,
+    primaryFields,
+    relationshipEntries,
+    resourceTypes: Object.freeze(resourceTypes)
+  });
+}
+
+export {
+  resolveJsonApiFieldsetContract,
+  resolveJsonApiRelationshipEntries,
+  resolveSchemaFieldDefinitions
+};

package/src/server/listQueryValidators.js

@@ -4,6 +4,7 @@ import {
 } from "@jskit-ai/kernel/shared/validators";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { resolveCrudParentFilterKeys as resolveSharedCrudParentFilterKeys } from "@jskit-ai/resource-crud-core/shared/crudLookup";
+import { resolveJsonApiFieldsetContract } from "./jsonApiResourceContract.js";
 
 const listSearchQueryValidator = Object.freeze({
   schema: createSchema({
@@ -28,6 +29,28 @@ const lookupIncludeQueryValidator = Object.freeze({
   mode: "patch"
 });
 
+function createJsonApiFieldsetValueDefinition({ allowedFields = [] } = {}) {
+  const normalizedAllowedFields = [...new Set(
+    (Array.isArray(allowedFields) ? allowedFields : [])
+      .map((entry) => normalizeText(entry))
+      .filter(Boolean)
+  )];
+
+  return Object.freeze({
+    type: "array",
+    required: false,
+    items: {
+      type: "string",
+      minLength: 1,
+      ...(normalizedAllowedFields.length > 0
+        ? { enum: Object.freeze(normalizedAllowedFields) }
+        : {})
+    }
+  });
+}
+
+const jsonApiFieldsetValueDefinition = createJsonApiFieldsetValueDefinition();
+
 const jsonApiFieldsetsQueryValidator = Object.freeze({
   schema: createSchema({
     fields: {
@@ -36,18 +59,57 @@ const jsonApiFieldsetsQueryValidator = Object.freeze({
       messages: {
         default: "fields expects an object such as {\"bookings\":[\"petId\"],\"pets\":[\"name\"]}."
       },
-      values: {
-        type: "array",
-        items: {
-          type: "string",
-          minLength: 1
-        }
-      }
+      values: jsonApiFieldsetValueDefinition
     }
   }),
   mode: "patch"
 });
 
+function createJsonApiFieldsetsQueryValidator({ resource = {} } = {}) {
+  const contract = resolveJsonApiFieldsetContract(resource);
+  if (!contract.primaryType || contract.resourceTypes.length < 1) {
+    return jsonApiFieldsetsQueryValidator;
+  }
+
+  const firstRelationship = contract.relationshipEntries[0] || null;
+  const example = firstRelationship
+    ? `{"${contract.primaryType}":["${firstRelationship.attributeKey}"],` +
+      `"${firstRelationship.relationshipType}":["${firstRelationship.labelKey || "id"}"]}`
+    : `{"${contract.primaryType}":["id"]}`;
+  const allowedTypes = contract.resourceTypes.map((entry) => `"${entry}"`).join(", ");
+  const aliasGuidance = contract.aliasMappings
+    .map((entry) => `use "${entry.resourceType}" instead of "${entry.alias}"`)
+    .join("; ");
+  const additionalPropertiesMessage =
+    `fields keys must be JSON:API resource types. Allowed keys: ${allowedTypes}.` +
+    (aliasGuidance ? ` Relationship aliases are invalid keys; ${aliasGuidance}.` : "");
+  const fieldsetSchema = createSchema(
+    Object.fromEntries(
+      contract.resourceTypes.map((resourceType) => [
+        resourceType,
+        createJsonApiFieldsetValueDefinition({
+          allowedFields: resourceType === contract.primaryType ? contract.primaryFields : []
+        })
+      ])
+    )
+  );
+
+  return Object.freeze({
+    schema: createSchema({
+      fields: {
+        type: "object",
+        required: false,
+        schema: fieldsetSchema,
+        messages: {
+          default: `fields expects an object keyed by JSON:API resource type, such as ${example}.`,
+          additionalProperties: additionalPropertiesMessage
+        }
+      }
+    }),
+    mode: "patch"
+  });
+}
+
 function resolveCrudListUsesOrderedCursor(list = {}) {
   const entries = Array.isArray(list?.orderBy)
     ? list.orderBy
@@ -115,7 +177,8 @@ function createStandardCrudListQueryValidators({
   resource = {},
   listFilterQueryValidator = null,
   searchQueryValidator = listSearchQueryValidator,
-  includeQueryValidator = lookupIncludeQueryValidator
+  includeQueryValidator = lookupIncludeQueryValidator,
+  fieldsetsQueryValidator = jsonApiFieldsetsQueryValidator
 } = {}) {
   const resolvedListFilterQueryValidator =
     listFilterQueryValidator
@@ -132,21 +195,23 @@ function createStandardCrudListQueryValidators({
       ? [resolvedListFilterQueryValidator]
       : []),
     includeQueryValidator,
-    jsonApiFieldsetsQueryValidator
+    fieldsetsQueryValidator
   ];
 }
 
 function createStandardCrudViewQueryValidators({
-  includeQueryValidator = lookupIncludeQueryValidator
+  includeQueryValidator = lookupIncludeQueryValidator,
+  fieldsetsQueryValidator = jsonApiFieldsetsQueryValidator
 } = {}) {
   return [
     includeQueryValidator,
-    jsonApiFieldsetsQueryValidator
+    fieldsetsQueryValidator
   ];
 }
 
 export {
   createCrudCursorPaginationQueryValidator,
+  createJsonApiFieldsetsQueryValidator,
   listSearchQueryValidator,
   lookupIncludeQueryValidator,
   jsonApiFieldsetsQueryValidator,

package/src/server/routeContracts.js

@@ -6,86 +6,18 @@ import {
   composeSchemaDefinitions,
   recordIdParamsValidator
 } from "@jskit-ai/kernel/shared/validators";
-import { resolveCrudResourceScopeName } from "@jskit-ai/resource-crud-core/shared/crudLookup";
 import {
   createStandardCrudListQueryValidators,
   createStandardCrudViewQueryValidators,
   listSearchQueryValidator as defaultListSearchQueryValidator,
   lookupIncludeQueryValidator as defaultLookupIncludeQueryValidator
 } from "./listQueryValidators.js";
+import { resolveJsonApiRelationshipEntries } from "./jsonApiResourceContract.js";
 
 function isRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
-function resolveSchemaFieldDefinitions(definition = null) {
-  const schema = definition?.schema;
-  if (!schema || typeof schema.getFieldDefinitions !== "function") {
-    return {};
-  }
-
-  const definitions = schema.getFieldDefinitions();
-  return isRecord(definitions) ? definitions : {};
-}
-
-function resolveJsonApiRelationshipEntries(definition = null) {
-  const entries = [];
-
-  for (const [fieldKey, fieldDefinition] of Object.entries(resolveSchemaFieldDefinitions(definition))) {
-    const normalizedFieldDefinition = isRecord(fieldDefinition) ? fieldDefinition : {};
-    const relationshipType = String(normalizedFieldDefinition.belongsTo || "").trim();
-    if (relationshipType) {
-      const relationshipName = String(normalizedFieldDefinition.as || fieldKey || "").trim();
-      if (!relationshipName) {
-        continue;
-      }
-
-      entries.push(Object.freeze({
-        attributeKey: fieldKey,
-        relationshipName,
-        relationshipType,
-        labelKey: String(normalizedFieldDefinition?.relation?.labelKey || "").trim(),
-        required: normalizedFieldDefinition.required === true,
-        nullable: normalizedFieldDefinition.nullable === true
-      }));
-      continue;
-    }
-
-    const relation = isRecord(normalizedFieldDefinition.relation)
-      ? normalizedFieldDefinition.relation
-      : {};
-    if (String(relation.kind || "").trim().toLowerCase() !== "collection") {
-      continue;
-    }
-
-    const collectionRelationshipType = resolveCrudResourceScopeName(
-      relation.target || relation.targetResource || relation.namespace || relation.apiPath
-    );
-    if (!collectionRelationshipType) {
-      continue;
-    }
-
-    const collectionRelationshipName = String(
-      relation.as || normalizedFieldDefinition.as || fieldKey || ""
-    ).trim();
-    if (!collectionRelationshipName) {
-      continue;
-    }
-
-    entries.push(Object.freeze({
-      attributeKey: fieldKey,
-      relationshipName: collectionRelationshipName,
-      relationshipType: collectionRelationshipType,
-      labelKey: String(relation.labelKey || "").trim(),
-      many: true,
-      required: normalizedFieldDefinition.required === true,
-      nullable: normalizedFieldDefinition.nullable === true
-    }));
-  }
-
-  return Object.freeze(entries);
-}
-
 function readOwnValue(source = {}, key = "") {
   if (isRecord(source) && Object.hasOwn(source, key)) {
     return {

package/test/assistantActionConformance.test.js

@@ -11,14 +11,46 @@ import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudReso
 import { createCrudJsonApiActions } from "../src/server/jsonApiModule/actions.js";
 
 const BOOKINGS = Object.freeze([
-  Object.freeze({ id: "41", petId: "7", summary: "Wash and trim" }),
-  Object.freeze({ id: "42", petId: "8", summary: "Nail trim" })
+  Object.freeze({
+    id: "41",
+    serviceId: "11",
+    productId: "21",
+    contactId: "31",
+    petId: "7",
+    summary: "Wash and trim"
+  }),
+  Object.freeze({
+    id: "42",
+    serviceId: "12",
+    productId: "22",
+    contactId: "32",
+    petId: "8",
+    summary: "Nail trim"
+  })
 ]);
 const PETS = Object.freeze({
-  "7": Object.freeze({ id: "7", name: "Fido", species: "dog" }),
-  "8": Object.freeze({ id: "8", name: "Mabel", species: "cat" })
+  "7": Object.freeze({ id: "7", contactId: "31", breedId: "91", name: "Fido", species: "dog" }),
+  "8": Object.freeze({ id: "8", contactId: "32", breedId: "92", name: "Mabel", species: "cat" })
 });
 
+function lookupField(namespace, relationshipName) {
+  return {
+    type: "id",
+    required: true,
+    belongsTo: namespace,
+    as: relationshipName,
+    relation: {
+      kind: "lookup",
+      namespace,
+      valueKey: "id",
+      labelKey: "name"
+    },
+    operations: {
+      output: { required: true }
+    }
+  };
+}
+
 function createBookingsResource() {
   return defineCrudResource({
     namespace: "bookings",
@@ -30,21 +62,10 @@ function createBookingsResource() {
       }
     },
     schema: {
-      petId: {
-        type: "id",
-        required: true,
-        belongsTo: "pets",
-        as: "pet",
-        relation: {
-          kind: "lookup",
-          namespace: "pets",
-          valueKey: "id",
-          labelKey: "name"
-        },
-        operations: {
-          output: { required: true }
-        }
-      },
+      serviceId: lookupField("services", "service"),
+      productId: lookupField("products", "product"),
+      contactId: lookupField("contacts", "contact"),
+      petId: lookupField("pets", "pet"),
       summary: {
         type: "string",
         required: true,
@@ -77,20 +98,24 @@ function createBookingDocument(query = {}) {
     .includes("pet");
   const rows = BOOKINGS.slice(0, limit);
   const data = rows.map((booking) => {
-    const includePetLinkage = !selectedBookings || selectedBookings.includes("petId");
     return {
       type: "bookings",
       id: booking.id,
       attributes: selectFields({ summary: booking.summary }, selectedBookings),
-      ...(includePetLinkage
-        ? {
-            relationships: {
-              pet: {
-                data: { type: "pets", id: booking.petId }
-              }
-            }
-          }
-        : {})
+      relationships: {
+        service: {
+          data: { type: "services", id: booking.serviceId }
+        },
+        product: {
+          data: { type: "products", id: booking.productId }
+        },
+        contact: {
+          data: { type: "contacts", id: booking.contactId }
+        },
+        pet: {
+          data: { type: "pets", id: booking.petId }
+        }
+      }
     };
   });
   const included = includesPet
@@ -100,7 +125,15 @@ function createBookingDocument(query = {}) {
         attributes: selectFields({
           name: PETS[booking.petId].name,
           species: PETS[booking.petId].species
-        }, selectedPets)
+        }, selectedPets),
+        relationships: {
+          contact: {
+            data: { type: "contacts", id: PETS[booking.petId].contactId }
+          },
+          breed: {
+            data: { type: "breeds", id: PETS[booking.petId].breedId }
+          }
+        }
       }))
     : [];
 
@@ -123,8 +156,12 @@ function createFixture() {
       calls.push({ query, context });
       return returnJsonApiDocument(createBookingDocument(query));
     },
-    async getDocumentById() {
-      return returnJsonApiDocument({ data: createBookingDocument().data[0] });
+    async getDocumentById(_recordId, query) {
+      const document = createBookingDocument(query);
+      return returnJsonApiDocument({
+        data: document.data[0],
+        ...(document.included ? { included: document.included } : {})
+      });
     }
   };
   const definitions = createCrudJsonApiActions({
@@ -206,11 +243,32 @@ test("generated CRUD list contracts conform through native assistant discovery a
   assert.deepEqual(search.result.items.map((entry) => entry.actionId), ["crud.bookings.list"]);
   assert.equal(contract.ok, true);
   assert.equal(contract.result.inputSchema.properties.include.type, "string");
-  assert.equal(contract.result.inputSchema.properties.fields.type, "object");
+  const fieldsetInputSchema = resolveLocalSchemaReference(
+    contract.result.inputSchema,
+    contract.result.inputSchema.properties.fields
+  );
+  assert.deepEqual(
+    Object.keys(fieldsetInputSchema.properties),
+    ["bookings", "services", "products", "contacts", "pets"]
+  );
+  assert.equal(fieldsetInputSchema.additionalProperties, false);
+  assert.deepEqual(
+    fieldsetInputSchema.properties.bookings.items.enum,
+    ["id", "serviceId", "productId", "contactId", "petId", "summary"]
+  );
+  assert.equal(Object.hasOwn(fieldsetInputSchema.properties.pets.items, "enum"), false);
   assert.equal(Object.hasOwn(contract.result.inputSchema.properties, "workspaceSlug"), false);
   assert.match(contract.result.description, /include must be a comma-separated string/u);
-  assert.match(contract.result.description, /\{"bookings":\["petId"\],"pets":\["name"\]\}/u);
-  assert.match(contract.result.description, /items\[\]\.lookups\.pet\.name/u);
+  assert.match(contract.result.description, /\{"bookings":\["serviceId"\],"services":\["name"\]\}/u);
+  assert.match(
+    contract.result.description,
+    /fields keys must be JSON:API resource types: "bookings", "services", "products", "contacts", "pets"/u
+  );
+  assert.match(contract.result.description, /use "pets" instead of "pet"/u);
+  assert.match(
+    contract.result.description,
+    /"pet" -> resource type "pets" -> items\[\]\.lookups\.pet/u
+  );
   const primaryOutputSchema = resolveLocalSchemaReference(
     contract.result.outputSchema,
     contract.result.outputSchema.properties.items.items
@@ -229,21 +287,35 @@ test("generated CRUD list contracts conform through native assistant discovery a
     const response = await executeList(fixture, toolSet, { limit: 5 });
     assert.equal(response.ok, true);
     assert.deepEqual(response.result.result.items, [
-      { id: "41", petId: 7, summary: "Wash and trim" },
-      { id: "42", petId: 8, summary: "Nail trim" }
+      {
+        id: "41",
+        serviceId: 11,
+        productId: 21,
+        contactId: 31,
+        petId: 7,
+        summary: "Wash and trim"
+      },
+      {
+        id: "42",
+        serviceId: 12,
+        productId: 22,
+        contactId: 32,
+        petId: 8,
+        summary: "Nail trim"
+      }
     ]);
     assert.equal(response.result.result.nextCursor, null);
   });
 
   await t.test("sparse primary fields only", async () => {
     const response = await executeList(fixture, toolSet, {
-      fields: { bookings: ["petId"] },
+      fields: { bookings: ["serviceId"] },
       limit: 5
     });
     assert.equal(response.ok, true);
     assert.deepEqual(response.result.result.items, [
-      { id: "41", petId: 7 },
-      { id: "42", petId: 8 }
+      { id: "41", serviceId: 11 },
+      { id: "42", serviceId: 12 }
     ]);
   });
 
@@ -252,6 +324,8 @@ test("generated CRUD list contracts conform through native assistant discovery a
     assert.equal(response.ok, true);
     assert.equal(response.result.result.items[0].lookups.pet.name, "Fido");
     assert.equal(response.result.result.items[0].lookups.pet.species, "dog");
+    assert.equal(response.result.result.items[0].lookups.pet.contactId, "31");
+    assert.equal(response.result.result.items[0].lookups.pet.breedId, "91");
     assert.equal(response.result.result.items[1].lookups.pet.name, "Mabel");
   });
 
@@ -259,7 +333,7 @@ test("generated CRUD list contracts conform through native assistant discovery a
     const response = await executeList(fixture, toolSet, {
       workspaceSlug: "model-controlled-workspace",
       include: "pet",
-      fields: { bookings: ["petId"], pets: ["name"] },
+      fields: { bookings: ["id", "serviceId"], pets: ["name"] },
       limit: 5
     });
     assert.equal(response.ok, true);
@@ -267,7 +341,7 @@ test("generated CRUD list contracts conform through native assistant discovery a
     assert.deepEqual(JSON.parse(JSON.stringify(response.result.result.items)), [
       {
         id: "41",
-        petId: 7,
+        serviceId: 11,
         lookups: {
           petId: { id: "7", name: "Fido" },
           pet: { id: "7", name: "Fido" }
@@ -275,7 +349,7 @@ test("generated CRUD list contracts conform through native assistant discovery a
       },
       {
         id: "42",
-        petId: 8,
+        serviceId: 12,
         lookups: {
           petId: { id: "8", name: "Mabel" },
           pet: { id: "8", name: "Mabel" }
@@ -283,7 +357,12 @@ test("generated CRUD list contracts conform through native assistant discovery a
       }
     ]);
     assert.equal(Object.hasOwn(response.result.result.items[0], "summary"), false);
+    assert.equal(Object.hasOwn(response.result.result.items[0], "productId"), false);
+    assert.equal(Object.hasOwn(response.result.result.items[0], "contactId"), false);
+    assert.equal(Object.hasOwn(response.result.result.items[0], "petId"), false);
     assert.equal(Object.hasOwn(response.result.result.items[0].lookups.pet, "species"), false);
+    assert.equal(Object.hasOwn(response.result.result.items[0].lookups.pet, "contactId"), false);
+    assert.equal(Object.hasOwn(response.result.result.items[0].lookups.pet, "breedId"), false);
     assert.deepEqual(
       validateSchemaPayload(listDefinition.extensions.assistant.output, response.result.result, {
         phase: "output"
@@ -291,9 +370,47 @@ test("generated CRUD list contracts conform through native assistant discovery a
       response.result.result
     );
     assert.equal(fixture.calls.at(-1).query.workspaceSlug, undefined);
+    assert.deepEqual(fixture.calls.at(-1).query.fields, {
+      bookings: ["id", "serviceId"],
+      pets: ["name"]
+    });
     assert.equal(fixture.calls.at(-1).context.workspace.slug, "north-clinic");
   });
 
+  await t.test("sparse view projection removes unselected relationship linkage", async () => {
+    const viewContract = await fixture.catalog.executeToolCall({
+      toolName: "assistant_action_contract",
+      argumentsText: JSON.stringify({ actionId: "crud.bookings.view", version: 1 }),
+      context: fixture.context,
+      toolSet
+    });
+    assert.equal(viewContract.ok, true);
+
+    const response = await fixture.catalog.executeToolCall({
+      toolName: "assistant_action_execute",
+      argumentsText: JSON.stringify({
+        actionId: "crud.bookings.view",
+        version: 1,
+        input: {
+          recordId: "41",
+          include: "pet",
+          fields: { bookings: ["serviceId"], pets: ["name"] }
+        }
+      }),
+      context: fixture.context,
+      toolSet
+    });
+    assert.equal(response.ok, true);
+    assert.deepEqual(JSON.parse(JSON.stringify(response.result.result)), {
+      id: "41",
+      serviceId: 11,
+      lookups: {
+        petId: { id: "7", name: "Fido" },
+        pet: { id: "7", name: "Fido" }
+      }
+    });
+  });
+
   await t.test("limit and cursor truncation remain bounded", async () => {
     const response = await executeList(fixture, toolSet, { limit: 1 });
     assert.equal(response.ok, true);
@@ -317,8 +434,27 @@ test("generated CRUD list contracts conform through native assistant discovery a
     assert.equal(response.error.status, 400);
     assert.match(
       response.error.message,
-      /fields expects an object such as \{"bookings":\["petId"\],"pets":\["name"\]\}/u
+      /fields expects an object keyed by JSON:API resource type, such as \{"bookings":\["serviceId"\],"services":\["name"\]\}/u
+    );
+  });
+
+  await t.test("relationship aliases are rejected as sparse-fieldset resource keys", async () => {
+    const callCount = fixture.calls.length;
+    const response = await executeList(fixture, toolSet, {
+      include: "pet",
+      fields: { pet: ["name"] },
+      limit: 3
+    });
+    assert.equal(response.ok, false);
+    assert.equal(response.error.code, "ACTION_VALIDATION_FAILED");
+    assert.equal(response.error.status, 400);
+    assert.match(response.error.message, /fields\.pet: fields keys must be JSON:API resource types/u);
+    assert.match(
+      response.error.message,
+      /Allowed keys: "bookings", "services", "products", "contacts", "pets"/u
     );
+    assert.match(response.error.message, /use "pets" instead of "pet"/u);
+    assert.equal(fixture.calls.length, callCount);
   });
 
   await t.test("permission denial removes the generated action from native discovery", async () => {

package/test/listQueryValidators.test.js

@@ -10,6 +10,7 @@ import {
   listSearchQueryValidator,
   lookupIncludeQueryValidator,
   createCrudCursorPaginationQueryValidator,
+  createJsonApiFieldsetsQueryValidator,
   createCrudParentFilterQueryValidator,
   createStandardCrudListQueryValidators,
   createStandardCrudViewQueryValidators,
@@ -26,11 +27,13 @@ function composeSchemaDefinition(...definitions) {
 }
 
 function createCrudResource({
+  namespace = "",
   viewFields = {},
   createFields = {},
   patchFields = {}
 } = {}) {
   return {
+    ...(namespace ? { namespace } : {}),
     operations: {
       view: {
         output: {
@@ -90,6 +93,62 @@ test("lookupIncludeQueryValidator keeps include optional when merged with pagina
   assert.deepEqual(compiled.schema.querystring.required || [], []);
 });
 
+test("resource-aware sparse fieldsets enumerate JSON:API types and reject relationship aliases", () => {
+  const resource = createCrudResource({
+    namespace: "bookings",
+    viewFields: {
+      petId: {
+        type: "integer",
+        belongsTo: "pets",
+        as: "pet",
+        relation: {
+          labelKey: "name"
+        }
+      },
+      serviceId: {
+        type: "integer",
+        belongsTo: "services",
+        as: "service",
+        relation: {
+          labelKey: "name"
+        }
+      }
+    }
+  });
+  const validator = createJsonApiFieldsetsQueryValidator({ resource });
+  const transportSchema = validator.schema.toJsonSchema({ mode: "patch" });
+  const fieldsetReference = transportSchema.properties.fields.allOf[0].$ref;
+  const fieldsetSchema = transportSchema.definitions[fieldsetReference.slice("#/definitions/".length)];
+
+  assert.deepEqual(Object.keys(fieldsetSchema.properties), ["bookings", "pets", "services"]);
+  assert.equal(fieldsetSchema.additionalProperties, false);
+  assert.deepEqual(fieldsetSchema.properties.bookings.items.enum, ["petId", "serviceId"]);
+  assert.equal(Object.hasOwn(fieldsetSchema.properties.pets.items, "enum"), false);
+  assert.deepEqual(validateSchemaPayload(validator, {
+    fields: {
+      bookings: ["petId"],
+      pets: ["name"]
+    }
+  }, { phase: "input" }), {
+    fields: {
+      bookings: ["petId"],
+      pets: ["name"]
+    }
+  });
+  assert.throws(
+    () => validateSchemaPayload(validator, {
+      fields: {
+        pet: ["name"]
+      }
+    }, { phase: "input" }),
+    (error) => {
+      assert.match(error.fieldErrors?.["fields.pet"] || "", /Allowed keys: "bookings", "pets", "services"/u);
+      assert.match(error.fieldErrors?.["fields.pet"] || "", /use "pets" instead of "pet"/u);
+      return true;
+    }
+  );
+});
+
 test("createCrudCursorPaginationQueryValidator keeps numeric cursor validation for unordered lists", () => {
   const validator = createCrudCursorPaginationQueryValidator({});
 

package/test/routeContracts.test.js

@@ -180,7 +180,8 @@ test("createCrudJsonApiRouteContracts builds default CRUD JSON:API contracts", a
     limit: "25",
     fields: {
       contacts: ["id", "name"],
-      userProfiles: ["id", "name"]
+      userProfiles: ["id", "name"],
+      organizations: ["name"]
     }
   }, { phase: "input" });
 
@@ -192,7 +193,8 @@ test("createCrudJsonApiRouteContracts builds default CRUD JSON:API contracts", a
     limit: 25,
     fields: {
       contacts: ["id", "name"],
-      userProfiles: ["id", "name"]
+      userProfiles: ["id", "name"],
+      organizations: ["name"]
     }
   });