Skip to content

Commit

Permalink
Add cookbook page about model names convention (#9394)
Browse files Browse the repository at this point in the history
* Add cookbook page about model names

* Update guides/cookbook/model-name.md

Co-authored-by: Chris Thoburn <runspired@users.noreply.github.com>

* Update guides/cookbook/model-name.md

Co-authored-by: Chris Thoburn <runspired@users.noreply.github.com>

* Update guides/cookbook/model-name.md

Co-authored-by: Chris Thoburn <runspired@users.noreply.github.com>

* Update guides/cookbook/model-name.md

Co-authored-by: Chris Thoburn <runspired@users.noreply.github.com>

* Update guides/cookbook/index.md

Co-authored-by: Chris Thoburn <runspired@users.noreply.github.com>

* Final touches

---------

Co-authored-by: Chris Thoburn <runspired@users.noreply.github.com>
  • Loading branch information
Baltazore and runspired committed May 16, 2024
1 parent 0a06640 commit fdd783b
Show file tree
Hide file tree
Showing 2 changed files with 56 additions and 0 deletions.
1 change: 1 addition & 0 deletions guides/cookbook/index.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
# Cookbook

- [Incremental Adoption Guide](./incremental-adoption-guide.md)
- [Naming Conventions: Should resource types be singular or plural? What to choose? Why is that?](./naming-conventions.md)
55 changes: 55 additions & 0 deletions guides/cookbook/naming-conventions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# Model Name: singular or plural? What to choose? Why is that?

-[Cookbook](./index.md)

## Resource Type (model name) conventions – or, why it was singular

If you have been working with EmberData for a while, you might remember a convention about singular-dasherized resource types (or modelNames). It was a convention that model names should be singular. But why is that? Why not plural? And why dasherized?

There is no longer any strict rule in EmberData governing what naming convention to use for resource types. Before, you may have been using singular names, because you had default Serializer configured in your app. The default serializers assume types should be singular and dasherized, and since they do the job of data normalization for you, they would singularize and dasherize the `types` received from your server.

### So what to choose?

When using EmberData without Legacy setup, you are responsible for data normalization. You can choose whatever you want. You can use singular or plural names. It is up to you. Or up to your backend to be precise, as it would be beneficial for you to not do all that normalization on frontend. Just have it as a part of API contract of your app. But remember, you need to be consistent. If you choose singular names, stick with it. If you choose plural names, stick with it. **Be Consistent!**

What does consistency look like?

#### Let's say your convention is singular dasherized, e.g. `user-setting`

- the API should respond with `user-setting` (or your handler/serializer should normalize the type to)
- calls to store methods should use the same format: `store.findRecord('user-setting', '1')`
- relationship definitions should also use this format:

```ts
class User extends Model {
@hasMany('user-setting', { async: false, inverse: null }) userSettings;
}
```

- The model files should also use this format, e.g. the model would be located in `app/models/user-setting.{js,ts}`

#### But what about plural and snake case?

- the API should respond with `user_settings`
- calls to store methods: `store.findRecord('user_settings', '1')`
- relationship definitions:

```ts
class User extends Model {
@hasMany('user_settings', { async: false, inverse: null }) userSettings;
}
```

- The model file would be located in `app/models/user_settings.{js,ts}`

### But what about JSON:API spec?

It's pretty simple, JSON:API spec agnostic about the `type` field convention. Here is the quote from the spec:

> Note: This spec is agnostic about inflection rules, so the value of type can be either plural or singular. However, the same value should be used consistently throughout an implementation.

You can read more about it in the [JSON:API spec](https://jsonapi.org/format/#document-resource-object-identification).

---

- ⮐ [Cookbook](./index.md)

0 comments on commit fdd783b

Please sign in to comment.