Class JSONSerializer
public⚠️ This is LEGACY documentation for a feature that is no longer encouraged to be used. If starting a new app or thinking of implementing a new adapter, consider writing a Handler instead to be used with the RequestManager
In EmberData a Serializer is used to serialize and deserialize records when they are transferred in and out of an external source. This process involves normalizing property names, transforming attribute values and serializing relationships.
By default, EmberData uses and recommends the JSONAPISerializer
.
JSONSerializer
is useful for simpler or legacy backends that may
not support the http://jsonapi.org/ spec.
For example, given the following User
model and JSON payload:
app/models/user.js | |
1 2 3 |
import Model, { attr, belongsTo, hasMany } from ' -data/model'; export default class UserModel extends Model { |
extractAttributes (modelClass, resourceHash) Object public
Defined in ../packages/serializer/src/json.js:640
- modelClass
- Object
- resourceHash
- Object
- returns
- Object
Returns the resource's attributes formatted as a JSON-API "attributes object".
http://jsonapi.org/format/#document-resource-object-attributes
extractErrors (store, typeClass, payload, id) Object public
Defined in ../packages/serializer/src/json.js:1387
- store
- Store
- typeClass
- Model
- payload
- Object
- id
- (String|Number)
- returns
- Object
- json The deserialized errors
extractErrors
is used to extract model errors when a call
to Model#save
fails with an InvalidError
. By default
Ember Data expects error information to be located on the errors
property of the payload object.
This serializer expects this errors
object to be an Array similar
to the following, compliant with the https://jsonapi.org/format/#errors specification:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
{ "errors": [ { "detail": "This username is already taken!", "source": { "pointer": "data/attributes/username" } }, { "detail": "Doesn't look like a valid email.", "source": { "pointer": "data/attributes/email" } } ] } |
The key detail
provides a textual description of the problem.
Alternatively, the key title
can be used for the same purpose.
The nested keys source.pointer
detail which specific element
of the request data was invalid.
Note that JSON-API also allows for object-level errors to be placed
in an object with pointer data
, signifying that the problem
cannot be traced to a specific attribute:
1 2 3 4 5 6 7 8 9 10 |
{ "errors": [ { "detail": "Some generic non property error message", "source": { "pointer": "data" } } ] } |
When turn into a Errors
object, you can read these errors
through the property base
:
Example of alternative implementation, overriding the default behavior to deal with a different format of errors:
app/serializers/post.js | |
1 2 3 4 5 6 7 8 9 10 11 |
import JSONSerializer from ' -data/serializer/json'; export default class PostSerializer extends JSONSerializer { extractErrors(store, typeClass, payload, id) { if (payload && typeof payload === 'object' && payload._problems) { payload = payload._problems; this.normalizeErrors(typeClass, payload); } return payload; } } |
extractId (modelClass, resourceHash) String public
Defined in ../packages/serializer/src/json.js:625
- modelClass
- Object
- resourceHash
- Object
- returns
- String
Returns the resource's ID.
extractMeta (store, modelClass, payload) public
Defined in ../packages/serializer/src/json.js:1352
- store
- Store
- modelClass
- Model
- payload
- Object
extractMeta
is used to deserialize any meta information in the
adapter payload. By default Ember Data expects meta information to
be located on the meta
property of the payload object.
Example
app/serializers/post.js | |
1 2 3 4 5 6 7 8 9 10 11 |
import JSONSerializer from ' -data/serializer/json'; export default class PostSerializer extends JSONSerializer { extractMeta(store, typeClass, payload) { if (payload && payload.hasOwnProperty('_pagination')) { let meta = payload._pagination; delete payload._pagination; return meta; } } } |
extractPolymorphicRelationship (relationshipModelName, relationshipHash, relationshipOptions) Object public
Defined in ../packages/serializer/src/json.js:700
- relationshipModelName
- Object
- relationshipHash
- Object
- relationshipOptions
- Object
- returns
- Object
Returns a polymorphic relationship formatted as a JSON-API "relationship object".
http://jsonapi.org/format/#document-resource-object-relationships
relationshipOptions
is a hash which contains more information about the
polymorphic relationship which should be extracted:
resourceHash
complete hash of the resource the relationship should be extracted fromrelationshipKey
key under which the value for the relationship is extracted from the resourceHashrelationshipMeta
meta information about the relationship
extractRelationship (relationshipModelName, relationshipHash) Object public
Defined in ../packages/serializer/src/json.js:665
- relationshipModelName
- Object
- relationshipHash
- Object
- returns
- Object
Returns a relationship formatted as a JSON-API "relationship object".
http://jsonapi.org/format/#document-resource-object-relationships
extractRelationships (modelClass, resourceHash) Object public
Defined in ../packages/serializer/src/json.js:724
- modelClass
- Object
- resourceHash
- Object
- returns
- Object
Returns the resource's relationships formatted as a JSON-API "relationships object".
http://jsonapi.org/format/#document-resource-object-relationships
keyForAttribute (key, method) String public
Defined in ../packages/serializer/src/json.js:1522
- key
- String
- method
- String
- returns
- String
- normalized key
keyForAttribute
can be used to define rules for how to convert an
attribute name in your model to a key in your JSON.
Example
app/serializers/application.js | |
1 2 3 4 5 6 7 8 |
import JSONSerializer from ' -data/serializer/json'; import { underscore } from '<app-name>/utils/string-utils'; export default class ApplicationSerializer extends JSONSerializer { keyForAttribute(attr, method) { return underscore(attr).toUpperCase(); } } |
keyForLink (key, kind) String public
Defined in ../packages/serializer/src/json.js:1578
- key
- String
- kind
- String
- `belongsTo` or `hasMany`
- returns
- String
- normalized key
keyForLink
can be used to define a custom key when deserializing link
properties.
keyForRelationship (key, typeClass, method) String public
Defined in ../packages/serializer/src/json.js:1549
- key
- String
- typeClass
- String
- method
- String
- returns
- String
- normalized key
keyForRelationship
can be used to define a custom key when
serializing and deserializing relationship properties. By default
JSONSerializer
does not provide an implementation of this method.
Example
app/serializers/post.js | |
1 2 3 4 5 6 7 8 |
import JSONSerializer from ' -data/serializer/json'; import { underscore } from '<app-name>/utils/string-utils'; export default class PostSerializer extends JSONSerializer { keyForRelationship(key, relationship, method) { return `rel_${underscore(key)}`; } } |
modelNameFromPayloadKey (key) String public
Defined in ../packages/serializer/src/json.js:796
- key
- String
- returns
- String
- the model's modelName
Dasherizes the model name in the payload
normalize (typeClass, hash) Object public
Defined in ../packages/serializer/src/json.js:561
- typeClass
- Model
- hash
- Object
- returns
- Object
Normalizes a part of the JSON payload returned by the server. You should override this method, munge the hash and call super if you have generic normalization to do.
It takes the type of the record that is being normalized (as a Model class), the property where the hash was originally found, and the hash to normalize.
You can use this method, for example, to normalize underscored keys to camelized or other general-purpose normalizations.
Example
app/serializers/application.js | |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
import JSONSerializer from '@ember-data/serializer/json'; import { underscore } from '<app-name>/utils/string-utils'; import { get } from '@ember/object'; export default class ApplicationSerializer extends JSONSerializer { normalize(typeClass, hash) { let fields = typeClass.fields; fields.forEach(function(type, field) { let payloadField = underscore(field); if (field === payloadField) { return; } hash[field] = hash[payloadField]; delete hash[payloadField]; }); return super.normalize(...arguments); } } |
normalizeArrayResponse (store, primaryModelClass, payload, id, requestType) Object public
Defined in ../packages/serializer/src/json.js:494
Available since v1.13.0
- store
- Store
- primaryModelClass
- Model
- payload
- Object
- id
- String|Number
- requestType
- String
- returns
- Object
- JSON-API Document
normalizeQueryResponse, normalizeFindManyResponse, and normalizeFindHasManyResponse delegate to this method by default.
normalizeCreateRecordResponse (store, primaryModelClass, payload, id, requestType) Object public
Defined in ../packages/serializer/src/json.js:404
Available since v1.13.0
- store
- Store
- primaryModelClass
- Model
- payload
- Object
- id
- String|Number
- requestType
- String
- returns
- Object
- JSON-API Document
Called by the default normalizeResponse implementation when the
type of request is createRecord
normalizeDeleteRecordResponse (store, primaryModelClass, payload, id, requestType) Object public
Defined in ../packages/serializer/src/json.js:422
Available since v1.13.0
- store
- Store
- primaryModelClass
- Model
- payload
- Object
- id
- String|Number
- requestType
- String
- returns
- Object
- JSON-API Document
Called by the default normalizeResponse implementation when the
type of request is deleteRecord
normalizeFindAllResponse (store, primaryModelClass, payload, id, requestType) Object public
Defined in ../packages/serializer/src/json.js:314
Available since v1.13.0
- store
- Store
- primaryModelClass
- Model
- payload
- Object
- id
- String|Number
- requestType
- String
- returns
- Object
- JSON-API Document
Called by the default normalizeResponse implementation when the
type of request is findAll
normalizeFindBelongsToResponse (store, primaryModelClass, payload, id, requestType) Object public
Defined in ../packages/serializer/src/json.js:332
Available since v1.13.0
- store
- Store
- primaryModelClass
- Model
- payload
- Object
- id
- String|Number
- requestType
- String
- returns
- Object
- JSON-API Document
Called by the default normalizeResponse implementation when the
type of request is findBelongsTo
normalizeFindHasManyResponse (store, primaryModelClass, payload, id, requestType) Object public
Defined in ../packages/serializer/src/json.js:350
Available since v1.13.0
- store
- Store
- primaryModelClass
- Model
- payload
- Object
- id
- String|Number
- requestType
- String
- returns
- Object
- JSON-API Document
Called by the default normalizeResponse implementation when the
type of request is findHasMany
normalizeFindManyResponse (store, primaryModelClass, payload, id, requestType) Object public
Defined in ../packages/serializer/src/json.js:368
Available since v1.13.0
- store
- Store
- primaryModelClass
- Model
- payload
- Object
- id
- String|Number
- requestType
- String
- returns
- Object
- JSON-API Document
Called by the default normalizeResponse implementation when the
type of request is findMany
normalizeFindRecordResponse (store, primaryModelClass, payload, id, requestType) Object public
Defined in ../packages/serializer/src/json.js:278
Available since v1.13.0
- store
- Store
- primaryModelClass
- Model
- payload
- Object
- id
- String|Number
- requestType
- String
- returns
- Object
- JSON-API Document
Called by the default normalizeResponse implementation when the
type of request is findRecord
normalizeQueryRecordResponse (store, primaryModelClass, payload, id, requestType) Object public
Defined in ../packages/serializer/src/json.js:296
Available since v1.13.0
- store
- Store
- primaryModelClass
- Model
- payload
- Object
- id
- String|Number
- requestType
- String
- returns
- Object
- JSON-API Document
Called by the default normalizeResponse implementation when the
type of request is queryRecord
normalizeQueryResponse (store, primaryModelClass, payload, id, requestType) Object public
Defined in ../packages/serializer/src/json.js:386
Available since v1.13.0
- store
- Store
- primaryModelClass
- Model
- payload
- Object
- id
- String|Number
- requestType
- String
- returns
- Object
- JSON-API Document
Called by the default normalizeResponse implementation when the
type of request is query
normalizeResponse (store, primaryModelClass, payload, id, requestType) Object public
Defined in ../packages/serializer/src/json.js:217
Available since v1.13.0
- store
- Store
- primaryModelClass
- Model
- payload
- Object
- id
- String|Number
- requestType
- String
- returns
- Object
- JSON-API Document
The normalizeResponse
method is used to normalize a payload from the
server to a JSON-API Document.
http://jsonapi.org/format/#document-structure
This method delegates to a more specific normalize method based on
the requestType
.
To override this method with a custom one, make sure to call
return super.normalizeResponse(store, primaryModelClass, payload, id, requestType)
with your
pre-processed data.
Here's an example of using normalizeResponse
manually:
1 2 3 4 5 6 7 8 |
socket.on('message', function(message) { let data = message.data; let modelClass = store.modelFor(data.modelName); let serializer = store.serializerFor(data.modelName); let normalized = serializer.normalizeSingleResponse(store, modelClass, data, data.id); store.push(normalized); }); |
normalizeSaveResponse (store, primaryModelClass, payload, id, requestType) Object public
Defined in ../packages/serializer/src/json.js:458
Available since v1.13.0
- store
- Store
- primaryModelClass
- Model
- payload
- Object
- id
- String|Number
- requestType
- String
- returns
- Object
- JSON-API Document
normalizeUpdateRecordResponse, normalizeCreateRecordResponse and normalizeDeleteRecordResponse delegate to this method by default.
normalizeSingleResponse (store, primaryModelClass, payload, id, requestType) Object public
Defined in ../packages/serializer/src/json.js:476
Available since v1.13.0
- store
- Store
- primaryModelClass
- Model
- payload
- Object
- id
- String|Number
- requestType
- String
- returns
- Object
- JSON-API Document
normalizeQueryResponse and normalizeFindRecordResponse delegate to this method by default.
normalizeUpdateRecordResponse (store, primaryModelClass, payload, id, requestType) Object public
Defined in ../packages/serializer/src/json.js:440
Available since v1.13.0
- store
- Store
- primaryModelClass
- Model
- payload
- Object
- id
- String|Number
- requestType
- String
- returns
- Object
- JSON-API Document
Called by the default normalizeResponse implementation when the
type of request is updateRecord
serialize (snapshot, options) Object public
Defined in ../packages/serializer/src/json.js:957
- snapshot
- Snapshot
- options
- Object
- returns
- Object
- json
Called when a record is saved in order to convert the record into JSON.
By default, it creates a JSON object with a key for each attribute and belongsTo relationship.
For example, consider this model:
app/models/comment.js | |
1 2 3 |
import Model, { attr, belongsTo } from ' -data/model'; export default class CommentModel extends Model { |
serializeAttribute (snapshot, json, key, attribute) public
Defined in ../packages/serializer/src/json.js:1168
- snapshot
- Snapshot
- json
- Object
- key
- String
- attribute
- Object
serializeAttribute
can be used to customize how attr
properties are serialized
For example if you wanted to ensure all your attributes were always
serialized as properties on an attributes
object you could
write:
app/serializers/application.js | |
1 2 3 4 5 6 7 8 |
import JSONSerializer from ' -data/serializer/json'; export default class ApplicationSerializer extends JSONSerializer { serializeAttribute(snapshot, json, key, attributes) { json.attributes = json.attributes || {}; super.serializeAttribute(snapshot, json.attributes, key, attributes); } } |
serializeBelongsTo (snapshot, json, relationship) public
Defined in ../packages/serializer/src/json.js:1216
- snapshot
- Snapshot
- json
- Object
- relationship
- Object
serializeBelongsTo
can be used to customize how belongsTo
properties are serialized.
Example
app/serializers/post.js | |
1 2 3 4 5 6 7 8 9 10 11 12 |
import JSONSerializer from ' -data/serializer/json'; export default class PostSerializer extends JSONSerializer { serializeBelongsTo(snapshot, json, relationship) { let key = relationship.key; let belongsTo = snapshot.belongsTo(key); key = this.keyForRelationship ? this.keyForRelationship(key, "belongsTo", "serialize") : key; json[key] = !belongsTo ? null : belongsTo.record.toJSON(); } } |
serializeHasMany (snapshot, json, relationship) public
Defined in ../packages/serializer/src/json.js:1270
- snapshot
- Snapshot
- json
- Object
- relationship
- Object
serializeHasMany
can be used to customize how hasMany
properties are serialized.
Example
app/serializers/post.js | |
1 2 3 4 5 6 7 8 9 10 11 12 |
import JSONSerializer from ' -data/serializer/json'; export default class PostSerializer extends JSONSerializer { serializeHasMany(snapshot, json, relationship) { let key = relationship.key; if (key === 'comments') { return; } else { super.serializeHasMany(...arguments); } } } |
serializeIntoHash (hash, typeClass, snapshot, options) public
Defined in ../packages/serializer/src/json.js:1135
- hash
- Object
- typeClass
- Model
- snapshot
- Snapshot
- options
- Object
You can use this method to customize how a serialized record is added to the complete JSON hash to be sent to the server. By default the JSON Serializer does not namespace the payload and just sends the raw serialized JSON object. If your server expects namespaced keys, you should consider using the RESTSerializer. Otherwise you can override this method to customize how the record is added to the hash. The hash property should be modified by reference.
For example, your server may expect underscored root objects.
app/serializers/application.js | |
1 2 3 4 5 6 7 8 9 |
import RESTSerializer from ' -data/serializer/rest'; import { decamelize } from '<app-name>/utils/string-utils'; export default class ApplicationSerializer extends RESTSerializer { serializeIntoHash(data, type, snapshot, options) { let root = decamelize(type.modelName); data[root] = this.serialize(snapshot, options); } } |
serializePolymorphicType (snapshot, json, relationship) public
Defined in ../packages/serializer/src/json.js:1317
- snapshot
- Snapshot
- json
- Object
- relationship
- Object
You can use this method to customize how polymorphic objects are
serialized. Objects are considered to be polymorphic if
{ polymorphic: true }
is pass as the second argument to the
belongsTo
function.
Example
app/serializers/comment.js | |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
import JSONSerializer from ' -data/serializer/json'; export default class CommentSerializer extends JSONSerializer { serializePolymorphicType(snapshot, json, relationship) { let key = relationship.key; let belongsTo = snapshot.belongsTo(key); key = this.keyForAttribute ? this.keyForAttribute(key, 'serialize') : key; if (!belongsTo) { json[key + '_type'] = null; } else { json[key + '_type'] = belongsTo.modelName; } } } |
shouldSerializeHasMany (snapshot, key, relationshipType) Boolean public
Defined in ../packages/serializer/src/json.js:934
- snapshot
- Snapshot
- key
- String
- relationshipType
- String
- returns
- Boolean
- true if the hasMany relationship should be serialized
Check if the given hasMany relationship should be serialized
By default only many-to-many and many-to-none relationships are serialized.
This could be configured per relationship by Serializer's attrs
object.