Embedded models and links

[ahacking]

Firstly, what a promising library that looks like it will solve the client synchronisation problem with a good design approach.

@dgeb I have covered the embedded links issue on the json-api spec and I have been reviewing orbit for use in one of my apps. I have to say it looks very good, except for a couple of things I'll cover below.

There are two areas that with some minor changes could potentially allow model structures that have embedded attributes with links, the first being orbit-common/schema.js and the second being orbit-common/source.js.

If the schema.js instead just relied on the type being 'has-many' or 'has-one' to build up __rels[] there would be no need to segregate attributes and links.

The second change is to add support for embedded has-one and has-many models which don't (necessarily) have ids (or at least dont have server ids).

With schema avoiding segregation of links and allowing nested/embedded models (ie any value type that requires a breakdown into sub properties) , Orbit would move a step closer to supporting data sources and resources that have embedded structure.

The second area is orbit-common/source.js, which defines findLink(), addLink() and removeLink(). It is not clear that these are needed in the public api if the existing methods simply check if the property name exists in__rels[] and do an addLink/removeLink vs normal property handling. It would be nice to be agnostic to whether a property is an attribute or a link.

I would be keen to get your feedback on the above, as I'm seriously wanting to use Orbit if I can a path forward to supporting resources with structure/embedded models/links.

I'm also prepared to work up a PR to get there if you're interested and with your insight into the code if the proposal is viable and there aren't any obvious blockers.

[dgeb]

@ahacking great to see that you're interested in using Orbit. I've enjoyed our discussions over in json-api :)

With schema avoiding segregation of links and allowing nested/embedded models (ie any value type that requires a breakdown into sub properties) , Orbit would move a step closer to supporting data sources and resources that have embedded structure.

Embedding is currently a serialization concern that can be handled in individual Orbit sources. Remotely embedded models can be deserialized and assigned local ids so that relationships can be tracked in Orbit records.

Can you elaborate on some use cases that you feel would benefit from allowing embedded models in Orbit's normalized form?

Are you concerned with ease of access to embedded models from their containers? Record dirtying / persistence?

The second area is orbit-common/source.js, which defines findLink(), addLink() and removeLink(). It is not clear that these are needed in the public api if the existing methods simply check if the property name exists in__rels[] and do an addLink/removeLink vs normal property handling. It would be nice to be agnostic to whether a property is an attribute or a link.

findLink may have different implementations in different sources. Consider links in json-api: they may be specified as ids or hrefs. Although this is not fully implement in the JSONAPISource (a PR is expected soon), findLink should support either case.

addLink / removeLink internally call transform, which is implemented uniquely in each source. It's up to each source to know how its "contents" should be transformed.

Let's discuss your schema / id proposal over in #42.

[ahacking]

I'll elaborate more tomorrow but for embedded it would be nice to declaratively say a model is embedded even though yes it is a serializer concern. Do you have any thoughts for decorating model schema with serializer hints or concerns? I can see that for some backends certain attributes are only readable or only specifiable on create and never update and in my case some links should be embedded (but which ones?).

Per model serializer concerns need to be configured somewhere so any suggestions or thoughts on that would be great.

Some use cases for embedded in my application are entities of type color with a link to color space, or measurements with link to the unit type, or contact addresses, phone etc embedded in the contact in defined order. They are properties that have components to them eg think complex number and should never be resources. I have shapes or sizes that are a set of measurements where some dimensions are measured in meters and others millimeters. I don't want to normalize these to resources/endpoints as they don't exist on their own. Taken to it's conclusion you would have endpoints for a persons height and links to that vs just the height and unit as an embedded value.

Hope that gives you some insight into the kinds of attributes I need to model that don't stand on their own as resources.

[dgeb]

Wow, this issue is over 6 years old! I'm open to discussing this topic more in the context of Orbit's current interfaces, but am going to close this issue for lack of activity.