Denormalization behavior with embedded models

[backbone87]

Lets assume we have entity Book and Chapter. We will treat this as a 1-1 relation, but this also applies to 1-n relations.
`
(i will use yaml serialization for comments)

We asume that we have 1 book and 2 chapters already and that one chapter is related to book (1-1 remember).

"@id": /books/great-book
"@type": type:Book
title: A Great Book
content: /chapters/first-chapter

"@id": /chapters/first-chapter
"@type": type:Chapter
headline: The Beginning

"@id": /chapters/second-chapter
"@type": type:Chapter
headline: Continue

The context

type: http://example.com/
title: http://example.com/title
content:
  "@id": http://example.com/content
  "@type": @id
headline: http://example.com/headline

There are actually several different possibilities when updating the Book with an embedded update.
We do a PUT /books/great-book with the following documents

"@id": /books/great-book # can be infered by endpoint
"@type": Book # can be infered by endpoint
content:
  "@id": /chapters/first-chapter
  headline: Lets Start

Meaning:

• Relate /books/great-book with content of /chapters/first-chapter. This is a noop
• Update /chapter/first-chapter with headline of Lets Start (old value was The Beginning)

"@id": /books/great-book # can be infered by endpoint
"@type": Book # can be infered by endpoint
title: A Great Book
content:
  "@id": /chapters/second-chapter
  headline: Going On

Meaning:

• Relate /books/great-book with content of /chapters/second-chapter.
• Update /chapters/second-chapter with headline of Going On

"@id": /books/great-book # can be infered by endpoint
"@type": Book # can be infered by endpoint
title: A Great Book
content:
  "@id": /chapters/new-chapter
  headline: Finish

Meaning:

• Relate /books/great-book with content of /chapters/new-chapter. But this chapter doesnt exist. Should it be created, or should the denormalization fail? (failing results in 400, 404 or 409 depending on preference)
• If we created the /chapters/new-chapter we set its headline to Finish

"@id": /books/great-book # can be infered by endpoint
"@type": Book # can be infered by endpoint
content:
  headline: Lets start

Meaning:

• the given chapter is a blank node and gets a blank id of _:1
• Obviously there is no chapter _:1. we have 3 possibilities
  • Create a new chapter (and update it)
  • Fail (400, 404, 409)
  • Use whatever chapter is currently set as content of the book and update this (fails if there is no current content)

While the first 2 examples are pretty straight forward, the last two can get wonky.

@soyuka Whats your opinion on this?

[soyuka]

For the first examples, it looks a lot like the behavior of what a PATCH method should do no?

I agree with most of the examples, and I think they'd almost work as-is in ApiPlatform. However:

"@id": /books/great-book # can be infered by endpoint
"@type": Book # can be infered by endpoint
title: A Great Book
content:
  "@id": /chapters/new-chapter
  headline: Finish

Assumes that the id of new-chapter is writable. If not it'll result in an error ofc.
The second example with a blank node should be an auto generated identifier IMO or results in an error.

Tldr if you add the information of how the identifier is built (writable/readonly) you can resolve the last two cases.

[backbone87]

For the first examples, it looks a lot like the behavior of what a PATCH method should do no?

api platform doesnt make a distinction between PATCH and PUT. there is also no real consensus about how a PUT vs PATCH should look like. The only real hard distinction from a protocol view is that PUT must be idempotent while PATCH may not.

Regarding the last 2 examples: you must take into account that we are not necessarily translating to a relational persistance layer, but an in memory object model.

For example an EmailAddress value object with 2 properties email (required) and displayName (optional) has no artificial identity (its value identifies it). You can use embeddables in doctrine to model this and in JSON-LD it may be a blank node object. Idk if its fine to give it any identity you want besides a blank node id, because after deserialization the @id of such an object would not matter anymore.

[soyuka]

Regarding the last 2 examples: you must take into account that we are not necessarily translating to a relational persistance layer, but an in memory object model.

Totally agreed. We still have some issues with blank nodes IIRC api-platform/core#956

May I ask though how you're using this repository? May it be useful to others? (maybe just update the README if it is 😄 )

[backbone87]

in some api-platform tickets there was the wish to rewrite/redesign the serializers. based on that i started this repo to implement a well designed json-ld serializer. while it is now directly implemented as a symfony serializer (normalizer+encoder), i maybe want to allow standalone serialize feature and just provide an integration with symfony serializer.