@warp-drive-mirror/json-api 5.9.0-alpha.0 → 5.9.0-alpha.1

package/declarations/-private/validator/1.1/7.4_full-linkage.d.ts

@@ -0,0 +1,18 @@
+import type { ResourceDocument } from "@warp-drive-mirror/core/types/spec/document";
+import { type Reporter } from "../utils.js";
+/**
+* Validates that all `data` members of relationships have a matching
+* resource object in the `included` or `data` section of the document.
+*
+* Optionally: validates that all resource objects in `included` are reachable
+* from at least one relationship `data` member in the primary data. This is a
+* spec requirement but has allowed caveats such as for sparse-fields wherein
+* related resources may be present with the linkage property omitted.
+* This setting is on by default but can be disabled by setting `strict.enforceReachable`
+* to false.
+*
+* Version: 1.1
+* Section: 7.4
+* Link: https://jsonapi.org/format/#document-compound-documents
+*/
+export declare function validateFullLinkage(reporter: Reporter, doc: ResourceDocument): void;

package/declarations/-private/validator/1.1/7.4_no-duplicate-resources.d.ts

@@ -0,0 +1,12 @@
+import type { ResourceDocument } from "@warp-drive-mirror/core/types/spec/document";
+import type { Reporter } from "../utils.js";
+/**
+* A common mistake, especially during development when mocking responses, is to
+* return the same resource multiple times, sometimes with differing attributes or
+* relationships.
+*
+* Version: 1.1
+* Section: 7.4
+* Link: https://jsonapi.org/format/#document-compound-documents
+*/
+export declare function validateNoDuplicateResources(reporter: Reporter, doc: ResourceDocument): void;

package/declarations/-private/validator/utils.d.ts

@@ -5,6 +5,7 @@ import type { CacheCapabilitiesManager, SchemaService } from "@warp-drive-mirror
 import type { StructuredDataDocument, StructuredDocument, StructuredErrorDocument } from "@warp-drive-mirror/core/types/request";
 import type { FieldSchema } from "@warp-drive-mirror/core/types/schema/fields";
 import type { ResourceDataDocument, ResourceDocument, ResourceErrorDocument, ResourceMetaDocument } from "@warp-drive-mirror/core/types/spec/document";
+import type { ResourceObject } from "@warp-drive-mirror/core/types/spec/json-api-raw";
 export declare function inspectType(obj: unknown): string;
 export declare function isSimpleObject(obj: unknown): obj is Record<string, unknown>;
 export declare const RELATIONSHIP_FIELD_KINDS: string[];
@@ -27,6 +28,19 @@ interface ErrorReport {
 	type: "error" | "warning" | "info";
 	kind: "key" | "value";
 }
+export interface ResourcePresence {
+	data: Map<string, Map<string, ResourceInfo[]>>;
+	included: Map<string, Map<string, ResourceInfo[]>>;
+	all: Map<string, Map<string, ResourceInfo[]>>;
+}
+export interface ResourceInfo {
+	data: ResourceObject;
+	/**
+	* null if the only primary data member
+	*/
+	index: number | null;
+	location: "data" | "included";
+}
 export declare class Reporter {
 	capabilities: CacheCapabilitiesManager;
 	contextDocument: StructuredDocument<ResourceDocument>;
@@ -38,7 +52,10 @@ export declare class Reporter {
 		unknownType: boolean;
 		unknownAttribute: boolean;
 		unknownRelationship: boolean;
+		enforceReachable: boolean;
 	};
+	_presence: ResourcePresence | null;
+	get presence(): ResourcePresence;
 	constructor(capabilities: CacheCapabilitiesManager, doc: StructuredDocument<ResourceDocument>);
 	_typeFilter: Fuse<string> | undefined;
 	searchTypes(type: string): FuseResult<string>[];
@@ -72,4 +89,12 @@ export declare function isPushedDocument(doc: unknown): doc is {
 };
 export declare function logPotentialMatches(matches: FuseResult<string>[], kind: string): string;
 export declare function getRemoteField(fields: Map<string, FieldSchema>, key: string): FieldSchema | undefined;
+export declare function checkResourceInMap(map: Map<string, Map<string, ResourceInfo[]>>, resource: {
+	type: string;
+	id: string;
+}): boolean;
+export declare function checkResourcePresent(presence: ResourcePresence, resource: {
+	type: string;
+	id: string;
+}): boolean;
 export {};

package/dist/index.js

@@ -172,8 +172,44 @@ class Reporter {
     linkage: true,
     unknownType: true,
     unknownAttribute: true,
-    unknownRelationship: true
+    unknownRelationship: true,
+    enforceReachable: true
   };
+  _presence = null;
+  get presence() {
+    if (this._presence) {
+      return this._presence;
+    }
+    const primaryResources = new Map();
+    const includedResources = new Map();
+    const allResources = new Map();
+    const doc = this.contextDocument.content;
+    if (doc) {
+      if ('data' in doc && doc.data) {
+        if (Array.isArray(doc.data)) {
+          for (let i = 0; i < doc.data.length; i++) {
+            addResourceToMap(primaryResources, doc.data[i], i, 'data');
+            addResourceToMap(allResources, doc.data[i], i, 'data');
+          }
+        } else {
+          addResourceToMap(primaryResources, doc.data, null, 'data');
+          addResourceToMap(allResources, doc.data, null, 'data');
+        }
+      }
+    }
+    if (doc && 'included' in doc && Array.isArray(doc.included)) {
+      for (let i = 0; i < doc.included.length; i++) {
+        addResourceToMap(includedResources, doc.included[i], i, 'included');
+        addResourceToMap(allResources, doc.included[i], i, 'included');
+      }
+    }
+    this._presence = {
+      data: primaryResources,
+      included: includedResources,
+      all: allResources
+    };
+    return this._presence;
+  }
   constructor(capabilities, doc) {
     this.capabilities = capabilities;
     this.contextDocument = doc;
@@ -364,7 +400,7 @@ class Reporter {
         }
       }
     }
-    const contextStr = `${counts.error} errors and ${counts.warning} warnings found in the {json:api} document returned by ${this.contextDocument.request?.method} ${this.contextDocument.request?.url}`;
+    const contextStr = `${counts.error} errors and ${counts.warning} warnings found in the {json:api} document returned by ${this.contextDocument.request?.method ?? 'GET'} ${this.contextDocument.request?.url}`;
     const errorString = contextStr + `\n\n` + errorLines.join('\n');
 
     // eslint-disable-next-line no-console, @typescript-eslint/no-unused-expressions
@@ -429,6 +465,25 @@ function getRemoteField(fields, key) {
   }
   return field;
 }
+function addResourceToMap(map, resource, index, location) {
+  if (!map.has(resource.type)) {
+    map.set(resource.type, new Map());
+  }
+  if (!map.get(resource.type).has(resource.id)) {
+    map.get(resource.type).set(resource.id, []);
+  }
+  map.get(resource.type).get(resource.id).push({
+    data: resource,
+    index,
+    location
+  });
+}
+function checkResourceInMap(map, resource) {
+  return map.has(resource.type) && map.get(resource.type).has(resource.id);
+}
+function checkResourcePresent(presence, resource) {
+  return checkResourceInMap(presence.data, resource) || checkResourceInMap(presence.included, resource);
+}
 
 const VALID_TOP_LEVEL_MEMBERS = ['data', 'included', 'meta', 'jsonapi', 'links'];
 
@@ -862,6 +917,183 @@ function validateResourceRelationships(reporter, type, resource, path) {
   //   type instead of the concrete type.
 }
 
+/**
+ * Validates that all `data` members of relationships have a matching
+ * resource object in the `included` or `data` section of the document.
+ *
+ * Optionally: validates that all resource objects in `included` are reachable
+ * from at least one relationship `data` member in the primary data. This is a
+ * spec requirement but has allowed caveats such as for sparse-fields wherein
+ * related resources may be present with the linkage property omitted.
+ * This setting is on by default but can be disabled by setting `strict.enforceReachable`
+ * to false.
+ *
+ * Version: 1.1
+ * Section: 7.4
+ * Link: https://jsonapi.org/format/#document-compound-documents
+ */
+function validateFullLinkage(reporter, doc) {
+  const {
+    presence
+  } = reporter;
+
+  // validate that all `data` members of relationships have a matching
+  // resource object in the `included` or `data` section of the document.
+
+  // for each type
+  for (const type of presence.all.keys()) {
+    const typeMap = presence.all.get(type);
+    // for each id of the type
+    for (const id of typeMap.keys()) {
+      const resources = typeMap.get(id);
+      // for each occurrence of the resource
+      for (const resourceInfo of resources) {
+        const relationships = resourceInfo.data.relationships;
+        if (relationships) {
+          // for each relationship the occurrence has
+          for (const relName of Object.keys(relationships)) {
+            const rel = relationships[relName];
+            if (rel && 'data' in rel && rel.data !== null) {
+              // for each linkage in the relationship
+              if (Array.isArray(rel.data)) {
+                for (const linkage of rel.data) {
+                  if (!checkResourcePresent(presence, linkage)) {
+                    // report missing linkage
+                    const pathLike = resourceInfo.index === null ? [resourceInfo.location, 'relationships', relName, 'data'] : [resourceInfo.location, resourceInfo.index, 'relationships', relName, 'data'];
+                    const index = rel.data.indexOf(linkage);
+                    pathLike.push(index);
+                    reporter.error(pathLike, `No ResourceObject matching the ResourceIdentifier linkage '${linkage.type}:${linkage.id}' was found in this payload. Exclude the relationship data, include the related ResourceObject, or consider using a link to reference this relationship instead.`, 'value');
+                  }
+                }
+              } else {
+                if (!checkResourcePresent(presence, rel.data)) {
+                  const pathLike = resourceInfo.index === null ? [resourceInfo.location, 'relationships', relName, 'data'] : [resourceInfo.location, resourceInfo.index, 'relationships', relName, 'data'];
+                  reporter.error(pathLike, `No ResourceObject matching the ResourceIdentifier linkage '${rel.data.type}:${rel.data.id}' was found in this payload. Exclude the relationship data, include the related ResourceObject, or consider using a link to reference this relationship instead.`, 'value');
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Optionally: validate that all resources in `included` are reachable
+  // from at least one relationship `data` member in the primary data.
+  const seen = walkResourceGraph(presence);
+
+  // iterate all included resources
+  for (const type of presence.included.keys()) {
+    const typeMap = presence.included.get(type);
+    for (const id of typeMap.keys()) {
+      const seenId = `${type}:${id}`;
+      if (!seen.has(seenId)) {
+        // report unreachable included resource
+        const resources = typeMap.get(id);
+        for (const resourceInfo of resources) {
+          const {
+            index,
+            location
+          } = resourceInfo;
+          const pathLike = index !== null ? [location, index] : [location];
+          // TODO if fields were present, attempt to use them to determine if this resource was intentionally excluded from relationships
+          // as part of sparseFields.
+          if (reporter.strict.enforceReachable !== false) {
+            reporter.error(pathLike, `The included ResourceObject '${type}:${id} is unreachable by any path originating from a primary ResourceObject. Exclude this ResourceObject or add the appropriate relationship linkages.`, 'value');
+          } else {
+            reporter.warn(pathLike, `The included ResourceObject '${type}:${id} is unreachable by any path originating from a primary ResourceObject. Exclude this ResourceObject or add the appropriate relationship linkages.`, 'value');
+          }
+        }
+      }
+    }
+  }
+}
+
+/**
+ * builds a set of all reachable resources by walking the resource graph
+ * starting from the primary data resources.
+ */
+function walkResourceGraph(presence) {
+  const seen = new Set();
+  for (const resourceType of presence.data.keys()) {
+    for (const resourceId of presence.data.get(resourceType).keys()) {
+      walkResource(presence, seen, presence.data.get(resourceType).get(resourceId));
+    }
+  }
+  return seen;
+}
+function walkResource(presence, seen, resource) {
+  const resourceType = resource[0].data.type;
+  const resourceId = resource[0].data.id;
+  const seenId = `${resourceType}:${resourceId}`;
+  if (seen.has(seenId)) {
+    return;
+  }
+  seen.add(`${resourceType}:${resourceId}`);
+  for (const resourceInfo of presence.all.get(resourceType).get(resourceId)) {
+    const relationships = resourceInfo.data.relationships;
+    if (relationships) {
+      for (const relName of Object.keys(relationships)) {
+        const rel = relationships[relName];
+        if (rel && 'data' in rel && rel.data !== null) {
+          // for each linkage in the relationship
+          if (Array.isArray(rel.data)) {
+            for (const linkage of rel.data) {
+              if (checkResourcePresent(presence, linkage)) {
+                walkResource(presence, seen, presence.all.get(linkage.type).get(linkage.id));
+              }
+            }
+          } else {
+            if (checkResourcePresent(presence, rel.data)) {
+              walkResource(presence, seen, presence.all.get(rel.data.type).get(rel.data.id));
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+/**
+ * A common mistake, especially during development when mocking responses, is to
+ * return the same resource multiple times, sometimes with differing attributes or
+ * relationships.
+ *
+ * Version: 1.1
+ * Section: 7.4
+ * Link: https://jsonapi.org/format/#document-compound-documents
+ */
+function validateNoDuplicateResources(reporter, doc) {
+  const {
+    presence
+  } = reporter;
+
+  // validate that all `data` members of relationships have a matching
+  // resource object in the `included` or `data` section of the document.
+
+  // for each type
+  for (const type of presence.all.keys()) {
+    const typeMap = presence.all.get(type);
+    // for each id of the type
+    for (const id of typeMap.keys()) {
+      const resources = typeMap.get(id);
+      if (resources.length > 1) {
+        for (const resourceInfo of resources) {
+          const {
+            index,
+            location
+          } = resourceInfo;
+          const pathLike = index !== null ? [location, index] : [location];
+          const occurrences = resources.filter(r => r !== resourceInfo).map(r => r.index !== null ? `${r.location}[${r.index}]` : r.location);
+          const ourPath = index !== null ? `${location}[${index}]` : location;
+          const errorMsg = `Duplicate ResourceObject detected for '${type}:${id}'. Each ResourceObject MUST appear only once in a {json:api} Document.\n\nThis Occurrence:\n\t- ${ourPath}\n\nOther Occurrences:\n\t- ${occurrences.join('\n\t- ')}`;
+          reporter.error(pathLike, errorMsg, 'value');
+        }
+      }
+    }
+  }
+}
+
 function validateDocument(capabilities, doc) {
   macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
     if (!test) {
@@ -906,6 +1138,8 @@ function validateResourceDocument(reporter, doc) {
   validateTopLevelDocumentMembers(reporter, doc.content);
   validateLinks(reporter, doc.content, 'data' in doc.content && Array.isArray(doc.content?.data) ? 'collection-document' : 'resource-document');
   validateDocumentResources(reporter, doc.content);
+  validateNoDuplicateResources(reporter, doc.content);
+  validateFullLinkage(reporter, doc.content);
 
   // TODO @runspired - validateMeta on document
   // TODO @runspired - validateMeta on resource

package/dist/unpkg/dev/index.js

@@ -171,8 +171,44 @@ class Reporter {
     linkage: true,
     unknownType: true,
     unknownAttribute: true,
-    unknownRelationship: true
+    unknownRelationship: true,
+    enforceReachable: true
   };
+  _presence = null;
+  get presence() {
+    if (this._presence) {
+      return this._presence;
+    }
+    const primaryResources = new Map();
+    const includedResources = new Map();
+    const allResources = new Map();
+    const doc = this.contextDocument.content;
+    if (doc) {
+      if ('data' in doc && doc.data) {
+        if (Array.isArray(doc.data)) {
+          for (let i = 0; i < doc.data.length; i++) {
+            addResourceToMap(primaryResources, doc.data[i], i, 'data');
+            addResourceToMap(allResources, doc.data[i], i, 'data');
+          }
+        } else {
+          addResourceToMap(primaryResources, doc.data, null, 'data');
+          addResourceToMap(allResources, doc.data, null, 'data');
+        }
+      }
+    }
+    if (doc && 'included' in doc && Array.isArray(doc.included)) {
+      for (let i = 0; i < doc.included.length; i++) {
+        addResourceToMap(includedResources, doc.included[i], i, 'included');
+        addResourceToMap(allResources, doc.included[i], i, 'included');
+      }
+    }
+    this._presence = {
+      data: primaryResources,
+      included: includedResources,
+      all: allResources
+    };
+    return this._presence;
+  }
   constructor(capabilities, doc) {
     this.capabilities = capabilities;
     this.contextDocument = doc;
@@ -363,7 +399,7 @@ class Reporter {
         }
       }
     }
-    const contextStr = `${counts.error} errors and ${counts.warning} warnings found in the {json:api} document returned by ${this.contextDocument.request?.method} ${this.contextDocument.request?.url}`;
+    const contextStr = `${counts.error} errors and ${counts.warning} warnings found in the {json:api} document returned by ${this.contextDocument.request?.method ?? 'GET'} ${this.contextDocument.request?.url}`;
     const errorString = contextStr + `\n\n` + errorLines.join('\n');
 
     // eslint-disable-next-line no-console, @typescript-eslint/no-unused-expressions
@@ -423,6 +459,25 @@ function getRemoteField(fields, key) {
   }
   return field;
 }
+function addResourceToMap(map, resource, index, location) {
+  if (!map.has(resource.type)) {
+    map.set(resource.type, new Map());
+  }
+  if (!map.get(resource.type).has(resource.id)) {
+    map.get(resource.type).set(resource.id, []);
+  }
+  map.get(resource.type).get(resource.id).push({
+    data: resource,
+    index,
+    location
+  });
+}
+function checkResourceInMap(map, resource) {
+  return map.has(resource.type) && map.get(resource.type).has(resource.id);
+}
+function checkResourcePresent(presence, resource) {
+  return checkResourceInMap(presence.data, resource) || checkResourceInMap(presence.included, resource);
+}
 
 const VALID_TOP_LEVEL_MEMBERS = ['data', 'included', 'meta', 'jsonapi', 'links'];
 
@@ -856,6 +911,183 @@ function validateResourceRelationships(reporter, type, resource, path) {
   //   type instead of the concrete type.
 }
 
+/**
+ * Validates that all `data` members of relationships have a matching
+ * resource object in the `included` or `data` section of the document.
+ *
+ * Optionally: validates that all resource objects in `included` are reachable
+ * from at least one relationship `data` member in the primary data. This is a
+ * spec requirement but has allowed caveats such as for sparse-fields wherein
+ * related resources may be present with the linkage property omitted.
+ * This setting is on by default but can be disabled by setting `strict.enforceReachable`
+ * to false.
+ *
+ * Version: 1.1
+ * Section: 7.4
+ * Link: https://jsonapi.org/format/#document-compound-documents
+ */
+function validateFullLinkage(reporter, doc) {
+  const {
+    presence
+  } = reporter;
+
+  // validate that all `data` members of relationships have a matching
+  // resource object in the `included` or `data` section of the document.
+
+  // for each type
+  for (const type of presence.all.keys()) {
+    const typeMap = presence.all.get(type);
+    // for each id of the type
+    for (const id of typeMap.keys()) {
+      const resources = typeMap.get(id);
+      // for each occurrence of the resource
+      for (const resourceInfo of resources) {
+        const relationships = resourceInfo.data.relationships;
+        if (relationships) {
+          // for each relationship the occurrence has
+          for (const relName of Object.keys(relationships)) {
+            const rel = relationships[relName];
+            if (rel && 'data' in rel && rel.data !== null) {
+              // for each linkage in the relationship
+              if (Array.isArray(rel.data)) {
+                for (const linkage of rel.data) {
+                  if (!checkResourcePresent(presence, linkage)) {
+                    // report missing linkage
+                    const pathLike = resourceInfo.index === null ? [resourceInfo.location, 'relationships', relName, 'data'] : [resourceInfo.location, resourceInfo.index, 'relationships', relName, 'data'];
+                    const index = rel.data.indexOf(linkage);
+                    pathLike.push(index);
+                    reporter.error(pathLike, `No ResourceObject matching the ResourceIdentifier linkage '${linkage.type}:${linkage.id}' was found in this payload. Exclude the relationship data, include the related ResourceObject, or consider using a link to reference this relationship instead.`, 'value');
+                  }
+                }
+              } else {
+                if (!checkResourcePresent(presence, rel.data)) {
+                  const pathLike = resourceInfo.index === null ? [resourceInfo.location, 'relationships', relName, 'data'] : [resourceInfo.location, resourceInfo.index, 'relationships', relName, 'data'];
+                  reporter.error(pathLike, `No ResourceObject matching the ResourceIdentifier linkage '${rel.data.type}:${rel.data.id}' was found in this payload. Exclude the relationship data, include the related ResourceObject, or consider using a link to reference this relationship instead.`, 'value');
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Optionally: validate that all resources in `included` are reachable
+  // from at least one relationship `data` member in the primary data.
+  const seen = walkResourceGraph(presence);
+
+  // iterate all included resources
+  for (const type of presence.included.keys()) {
+    const typeMap = presence.included.get(type);
+    for (const id of typeMap.keys()) {
+      const seenId = `${type}:${id}`;
+      if (!seen.has(seenId)) {
+        // report unreachable included resource
+        const resources = typeMap.get(id);
+        for (const resourceInfo of resources) {
+          const {
+            index,
+            location
+          } = resourceInfo;
+          const pathLike = index !== null ? [location, index] : [location];
+          // TODO if fields were present, attempt to use them to determine if this resource was intentionally excluded from relationships
+          // as part of sparseFields.
+          if (reporter.strict.enforceReachable !== false) {
+            reporter.error(pathLike, `The included ResourceObject '${type}:${id} is unreachable by any path originating from a primary ResourceObject. Exclude this ResourceObject or add the appropriate relationship linkages.`, 'value');
+          } else {
+            reporter.warn(pathLike, `The included ResourceObject '${type}:${id} is unreachable by any path originating from a primary ResourceObject. Exclude this ResourceObject or add the appropriate relationship linkages.`, 'value');
+          }
+        }
+      }
+    }
+  }
+}
+
+/**
+ * builds a set of all reachable resources by walking the resource graph
+ * starting from the primary data resources.
+ */
+function walkResourceGraph(presence) {
+  const seen = new Set();
+  for (const resourceType of presence.data.keys()) {
+    for (const resourceId of presence.data.get(resourceType).keys()) {
+      walkResource(presence, seen, presence.data.get(resourceType).get(resourceId));
+    }
+  }
+  return seen;
+}
+function walkResource(presence, seen, resource) {
+  const resourceType = resource[0].data.type;
+  const resourceId = resource[0].data.id;
+  const seenId = `${resourceType}:${resourceId}`;
+  if (seen.has(seenId)) {
+    return;
+  }
+  seen.add(`${resourceType}:${resourceId}`);
+  for (const resourceInfo of presence.all.get(resourceType).get(resourceId)) {
+    const relationships = resourceInfo.data.relationships;
+    if (relationships) {
+      for (const relName of Object.keys(relationships)) {
+        const rel = relationships[relName];
+        if (rel && 'data' in rel && rel.data !== null) {
+          // for each linkage in the relationship
+          if (Array.isArray(rel.data)) {
+            for (const linkage of rel.data) {
+              if (checkResourcePresent(presence, linkage)) {
+                walkResource(presence, seen, presence.all.get(linkage.type).get(linkage.id));
+              }
+            }
+          } else {
+            if (checkResourcePresent(presence, rel.data)) {
+              walkResource(presence, seen, presence.all.get(rel.data.type).get(rel.data.id));
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+/**
+ * A common mistake, especially during development when mocking responses, is to
+ * return the same resource multiple times, sometimes with differing attributes or
+ * relationships.
+ *
+ * Version: 1.1
+ * Section: 7.4
+ * Link: https://jsonapi.org/format/#document-compound-documents
+ */
+function validateNoDuplicateResources(reporter, doc) {
+  const {
+    presence
+  } = reporter;
+
+  // validate that all `data` members of relationships have a matching
+  // resource object in the `included` or `data` section of the document.
+
+  // for each type
+  for (const type of presence.all.keys()) {
+    const typeMap = presence.all.get(type);
+    // for each id of the type
+    for (const id of typeMap.keys()) {
+      const resources = typeMap.get(id);
+      if (resources.length > 1) {
+        for (const resourceInfo of resources) {
+          const {
+            index,
+            location
+          } = resourceInfo;
+          const pathLike = index !== null ? [location, index] : [location];
+          const occurrences = resources.filter(r => r !== resourceInfo).map(r => r.index !== null ? `${r.location}[${r.index}]` : r.location);
+          const ourPath = index !== null ? `${location}[${index}]` : location;
+          const errorMsg = `Duplicate ResourceObject detected for '${type}:${id}'. Each ResourceObject MUST appear only once in a {json:api} Document.\n\nThis Occurrence:\n\t- ${ourPath}\n\nOther Occurrences:\n\t- ${occurrences.join('\n\t- ')}`;
+          reporter.error(pathLike, errorMsg, 'value');
+        }
+      }
+    }
+  }
+}
+
 function validateDocument(capabilities, doc) {
   (test => {
     if (!test) {
@@ -883,6 +1115,8 @@ function validateResourceDocument(reporter, doc) {
   validateTopLevelDocumentMembers(reporter, doc.content);
   validateLinks(reporter, doc.content, 'data' in doc.content && Array.isArray(doc.content?.data) ? 'collection-document' : 'resource-document');
   validateDocumentResources(reporter, doc.content);
+  validateNoDuplicateResources(reporter, doc.content);
+  validateFullLinkage(reporter, doc.content);
 
   // TODO @runspired - validateMeta on document
   // TODO @runspired - validateMeta on resource

package/dist/unpkg/dev-deprecated/index.js

@@ -171,8 +171,44 @@ class Reporter {
     linkage: true,
     unknownType: true,
     unknownAttribute: true,
-    unknownRelationship: true
+    unknownRelationship: true,
+    enforceReachable: true
   };
+  _presence = null;
+  get presence() {
+    if (this._presence) {
+      return this._presence;
+    }
+    const primaryResources = new Map();
+    const includedResources = new Map();
+    const allResources = new Map();
+    const doc = this.contextDocument.content;
+    if (doc) {
+      if ('data' in doc && doc.data) {
+        if (Array.isArray(doc.data)) {
+          for (let i = 0; i < doc.data.length; i++) {
+            addResourceToMap(primaryResources, doc.data[i], i, 'data');
+            addResourceToMap(allResources, doc.data[i], i, 'data');
+          }
+        } else {
+          addResourceToMap(primaryResources, doc.data, null, 'data');
+          addResourceToMap(allResources, doc.data, null, 'data');
+        }
+      }
+    }
+    if (doc && 'included' in doc && Array.isArray(doc.included)) {
+      for (let i = 0; i < doc.included.length; i++) {
+        addResourceToMap(includedResources, doc.included[i], i, 'included');
+        addResourceToMap(allResources, doc.included[i], i, 'included');
+      }
+    }
+    this._presence = {
+      data: primaryResources,
+      included: includedResources,
+      all: allResources
+    };
+    return this._presence;
+  }
   constructor(capabilities, doc) {
     this.capabilities = capabilities;
     this.contextDocument = doc;
@@ -363,7 +399,7 @@ class Reporter {
         }
       }
     }
-    const contextStr = `${counts.error} errors and ${counts.warning} warnings found in the {json:api} document returned by ${this.contextDocument.request?.method} ${this.contextDocument.request?.url}`;
+    const contextStr = `${counts.error} errors and ${counts.warning} warnings found in the {json:api} document returned by ${this.contextDocument.request?.method ?? 'GET'} ${this.contextDocument.request?.url}`;
     const errorString = contextStr + `\n\n` + errorLines.join('\n');
 
     // eslint-disable-next-line no-console, @typescript-eslint/no-unused-expressions
@@ -423,6 +459,25 @@ function getRemoteField(fields, key) {
   }
   return field;
 }
+function addResourceToMap(map, resource, index, location) {
+  if (!map.has(resource.type)) {
+    map.set(resource.type, new Map());
+  }
+  if (!map.get(resource.type).has(resource.id)) {
+    map.get(resource.type).set(resource.id, []);
+  }
+  map.get(resource.type).get(resource.id).push({
+    data: resource,
+    index,
+    location
+  });
+}
+function checkResourceInMap(map, resource) {
+  return map.has(resource.type) && map.get(resource.type).has(resource.id);
+}
+function checkResourcePresent(presence, resource) {
+  return checkResourceInMap(presence.data, resource) || checkResourceInMap(presence.included, resource);
+}
 
 const VALID_TOP_LEVEL_MEMBERS = ['data', 'included', 'meta', 'jsonapi', 'links'];
 
@@ -856,6 +911,183 @@ function validateResourceRelationships(reporter, type, resource, path) {
   //   type instead of the concrete type.
 }
 
+/**
+ * Validates that all `data` members of relationships have a matching
+ * resource object in the `included` or `data` section of the document.
+ *
+ * Optionally: validates that all resource objects in `included` are reachable
+ * from at least one relationship `data` member in the primary data. This is a
+ * spec requirement but has allowed caveats such as for sparse-fields wherein
+ * related resources may be present with the linkage property omitted.
+ * This setting is on by default but can be disabled by setting `strict.enforceReachable`
+ * to false.
+ *
+ * Version: 1.1
+ * Section: 7.4
+ * Link: https://jsonapi.org/format/#document-compound-documents
+ */
+function validateFullLinkage(reporter, doc) {
+  const {
+    presence
+  } = reporter;
+
+  // validate that all `data` members of relationships have a matching
+  // resource object in the `included` or `data` section of the document.
+
+  // for each type
+  for (const type of presence.all.keys()) {
+    const typeMap = presence.all.get(type);
+    // for each id of the type
+    for (const id of typeMap.keys()) {
+      const resources = typeMap.get(id);
+      // for each occurrence of the resource
+      for (const resourceInfo of resources) {
+        const relationships = resourceInfo.data.relationships;
+        if (relationships) {
+          // for each relationship the occurrence has
+          for (const relName of Object.keys(relationships)) {
+            const rel = relationships[relName];
+            if (rel && 'data' in rel && rel.data !== null) {
+              // for each linkage in the relationship
+              if (Array.isArray(rel.data)) {
+                for (const linkage of rel.data) {
+                  if (!checkResourcePresent(presence, linkage)) {
+                    // report missing linkage
+                    const pathLike = resourceInfo.index === null ? [resourceInfo.location, 'relationships', relName, 'data'] : [resourceInfo.location, resourceInfo.index, 'relationships', relName, 'data'];
+                    const index = rel.data.indexOf(linkage);
+                    pathLike.push(index);
+                    reporter.error(pathLike, `No ResourceObject matching the ResourceIdentifier linkage '${linkage.type}:${linkage.id}' was found in this payload. Exclude the relationship data, include the related ResourceObject, or consider using a link to reference this relationship instead.`, 'value');
+                  }
+                }
+              } else {
+                if (!checkResourcePresent(presence, rel.data)) {
+                  const pathLike = resourceInfo.index === null ? [resourceInfo.location, 'relationships', relName, 'data'] : [resourceInfo.location, resourceInfo.index, 'relationships', relName, 'data'];
+                  reporter.error(pathLike, `No ResourceObject matching the ResourceIdentifier linkage '${rel.data.type}:${rel.data.id}' was found in this payload. Exclude the relationship data, include the related ResourceObject, or consider using a link to reference this relationship instead.`, 'value');
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Optionally: validate that all resources in `included` are reachable
+  // from at least one relationship `data` member in the primary data.
+  const seen = walkResourceGraph(presence);
+
+  // iterate all included resources
+  for (const type of presence.included.keys()) {
+    const typeMap = presence.included.get(type);
+    for (const id of typeMap.keys()) {
+      const seenId = `${type}:${id}`;
+      if (!seen.has(seenId)) {
+        // report unreachable included resource
+        const resources = typeMap.get(id);
+        for (const resourceInfo of resources) {
+          const {
+            index,
+            location
+          } = resourceInfo;
+          const pathLike = index !== null ? [location, index] : [location];
+          // TODO if fields were present, attempt to use them to determine if this resource was intentionally excluded from relationships
+          // as part of sparseFields.
+          if (reporter.strict.enforceReachable !== false) {
+            reporter.error(pathLike, `The included ResourceObject '${type}:${id} is unreachable by any path originating from a primary ResourceObject. Exclude this ResourceObject or add the appropriate relationship linkages.`, 'value');
+          } else {
+            reporter.warn(pathLike, `The included ResourceObject '${type}:${id} is unreachable by any path originating from a primary ResourceObject. Exclude this ResourceObject or add the appropriate relationship linkages.`, 'value');
+          }
+        }
+      }
+    }
+  }
+}
+
+/**
+ * builds a set of all reachable resources by walking the resource graph
+ * starting from the primary data resources.
+ */
+function walkResourceGraph(presence) {
+  const seen = new Set();
+  for (const resourceType of presence.data.keys()) {
+    for (const resourceId of presence.data.get(resourceType).keys()) {
+      walkResource(presence, seen, presence.data.get(resourceType).get(resourceId));
+    }
+  }
+  return seen;
+}
+function walkResource(presence, seen, resource) {
+  const resourceType = resource[0].data.type;
+  const resourceId = resource[0].data.id;
+  const seenId = `${resourceType}:${resourceId}`;
+  if (seen.has(seenId)) {
+    return;
+  }
+  seen.add(`${resourceType}:${resourceId}`);
+  for (const resourceInfo of presence.all.get(resourceType).get(resourceId)) {
+    const relationships = resourceInfo.data.relationships;
+    if (relationships) {
+      for (const relName of Object.keys(relationships)) {
+        const rel = relationships[relName];
+        if (rel && 'data' in rel && rel.data !== null) {
+          // for each linkage in the relationship
+          if (Array.isArray(rel.data)) {
+            for (const linkage of rel.data) {
+              if (checkResourcePresent(presence, linkage)) {
+                walkResource(presence, seen, presence.all.get(linkage.type).get(linkage.id));
+              }
+            }
+          } else {
+            if (checkResourcePresent(presence, rel.data)) {
+              walkResource(presence, seen, presence.all.get(rel.data.type).get(rel.data.id));
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+/**
+ * A common mistake, especially during development when mocking responses, is to
+ * return the same resource multiple times, sometimes with differing attributes or
+ * relationships.
+ *
+ * Version: 1.1
+ * Section: 7.4
+ * Link: https://jsonapi.org/format/#document-compound-documents
+ */
+function validateNoDuplicateResources(reporter, doc) {
+  const {
+    presence
+  } = reporter;
+
+  // validate that all `data` members of relationships have a matching
+  // resource object in the `included` or `data` section of the document.
+
+  // for each type
+  for (const type of presence.all.keys()) {
+    const typeMap = presence.all.get(type);
+    // for each id of the type
+    for (const id of typeMap.keys()) {
+      const resources = typeMap.get(id);
+      if (resources.length > 1) {
+        for (const resourceInfo of resources) {
+          const {
+            index,
+            location
+          } = resourceInfo;
+          const pathLike = index !== null ? [location, index] : [location];
+          const occurrences = resources.filter(r => r !== resourceInfo).map(r => r.index !== null ? `${r.location}[${r.index}]` : r.location);
+          const ourPath = index !== null ? `${location}[${index}]` : location;
+          const errorMsg = `Duplicate ResourceObject detected for '${type}:${id}'. Each ResourceObject MUST appear only once in a {json:api} Document.\n\nThis Occurrence:\n\t- ${ourPath}\n\nOther Occurrences:\n\t- ${occurrences.join('\n\t- ')}`;
+          reporter.error(pathLike, errorMsg, 'value');
+        }
+      }
+    }
+  }
+}
+
 function validateDocument(capabilities, doc) {
   (test => {
     if (!test) {
@@ -883,6 +1115,8 @@ function validateResourceDocument(reporter, doc) {
   validateTopLevelDocumentMembers(reporter, doc.content);
   validateLinks(reporter, doc.content, 'data' in doc.content && Array.isArray(doc.content?.data) ? 'collection-document' : 'resource-document');
   validateDocumentResources(reporter, doc.content);
+  validateNoDuplicateResources(reporter, doc.content);
+  validateFullLinkage(reporter, doc.content);
 
   // TODO @runspired - validateMeta on document
   // TODO @runspired - validateMeta on resource

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warp-drive-mirror/json-api",
-  "version": "5.9.0-alpha.0",
+  "version": "5.9.0-alpha.1",
   "description": "A {json:api} Cache Implementation for WarpDrive",
   "keywords": [
     "ember-addon"
@@ -40,7 +40,7 @@
     }
   },
   "peerDependencies": {
-    "@warp-drive-mirror/core": "5.9.0-alpha.0"
+    "@warp-drive-mirror/core": "5.9.0-alpha.1"
   },
   "dependencies": {
     "@embroider/macros": "^1.18.1",
@@ -52,8 +52,8 @@
     "@babel/plugin-transform-typescript": "^7.28.0",
     "@babel/preset-typescript": "^7.27.1",
     "@types/json-to-ast": "^2.1.4",
-    "@warp-drive/internal-config": "5.9.0-alpha.0",
-    "@warp-drive-mirror/core": "5.9.0-alpha.0",
+    "@warp-drive/internal-config": "5.9.0-alpha.1",
+    "@warp-drive-mirror/core": "5.9.0-alpha.1",
     "decorator-transforms": "^2.3.0",
     "expect-type": "^1.2.2",
     "typescript": "^5.9.2",