[DOC EmbeddedRecordsMixin] Assert from JSONAPISerializer

Use of EmbeddedRecordsMixin and JSONAPISerializer together asserts instead of warns. Allows for setting "isEmbeddedRecordsMixinCompatible" on the serializer for when parts of the API are compatible.

packages/-ember-data/tests/integration/serializers/json-api-serializer-test.js

@@ -714,10 +714,18 @@ module('integration/serializers/json-api-serializer - JSONAPISerializer', functi
     });
   });
 
-  testInDebug('JSON warns when combined with EmbeddedRecordsMixin', function(assert) {
-    assert.expectWarning(function() {
+  testInDebug('Asserts when combined with EmbeddedRecordsMixin', function(assert) {
+    assert.expectAssertion(function() {
       DS.JSONAPISerializer.extend(DS.EmbeddedRecordsMixin).create();
-    }, /The JSONAPISerializer does not work with the EmbeddedRecordsMixin/);
+    }, /You've used the EmbeddedRecordsMixin in/);
+  });
+
+  testInDebug('Allows EmbeddedRecordsMixin if isEmbeddedRecordsMixinCompatible is true', function(assert) {
+    assert.expectNoAssertion(function() {
+      DS.JSONAPISerializer.extend(DS.EmbeddedRecordsMixin, {
+        isEmbeddedRecordsMixinCompatible: true,
+      }).create();
+    });
   });
 
   testInDebug('Asserts when normalized attribute key is not found in payload but original key is', function(assert) {

packages/serializer/addon/json-api.js

@@ -129,6 +129,20 @@ import { normalizeModelName } from '@ember-data/store';
   @extends JSONSerializer
 */
 const JSONAPISerializer = JSONSerializer.extend({
+  init(...args) {
+    this._super(...args);
+
+    if (DEBUG) {
+      assert(
+        `You've used the EmbeddedRecordsMixin in ${this.toString()} which is not fully compatible with the JSON:API specification. Please confirm that this works for your specific API and add \`this.isEmbeddedRecordsMixinCompatible = true\` to your serializer.`,
+        !this.isEmbeddedRecordsMixin || this.isEmbeddedRecordsMixinCompatible === true,
+        {
+          id: 'ds.serializer.embedded-records-mixin-not-supported',
+        }
+      );
+    }
+  },
+
   /**
     @method _normalizeDocumentHelper
     @param {Object} documentHash
@@ -185,6 +199,8 @@ const JSONAPISerializer = JSONSerializer.extend({
     @private
   */
   _normalizeResourceHelper(resourceHash) {
+    console.log(this.isEmbeddedRecordsMixinCompatible, this.isEmbeddedRecordsMixin);
+
     assert(this.warnMessageForUndefinedType(), !isNone(resourceHash.type), {
       id: 'ds.serializer.type-is-undefined',
     });
@@ -568,13 +584,6 @@ if (DEBUG) {
           id: 'ds.serializer.json-api.extractMeta',
         }
       );
-      warn(
-        'The JSONAPISerializer does not work with the EmbeddedRecordsMixin because the JSON API spec does not describe how to format embedded resources.',
-        !props.isEmbeddedRecordsMixin,
-        {
-          id: 'ds.serializer.embedded-records-mixin-not-supported',
-        }
-      );
     },
     warnMessageForUndefinedType() {
       return (