Explain complex attributes, again #504
Conversation
1318cfa to
f4cd8dd
Compare
| ([example](/examples/#complex-attributes)). | ||
|
|
||
| JSON API permits embedding arbitrary data structures as complex attributes in | ||
| resource objects. However, any object in a complex attribute **MUST** reserve |
There was a problem hiding this comment.
@bintoro This looks good! One small thing: would it be more accurate to keep the "object that constitutes or is contained in a complex attribute" language here?
There was a problem hiding this comment.
@ethanresnick Maybe. The phrase was my brainchild, but then I started doubting its necessity. If you think it adds clarity, I'll put it back. It just doesn't seem like "any object in a complex attribute" could realistically be misinterpreted.
While we're at it, the first paragraph used to have another clause:
"Complex attributes" are attributes whose value is an object or array, which in turn may contain values of any type.
And the second paragraph started like this:
JSON API thus permits embedding...
But then I thought it might be overkill. What do you think?
There was a problem hiding this comment.
Sorry I'm just responding to this! I've been bogged down with stuff :)
I think your simplifications were really good overall. It was only the removal of the "constitutes or is contained in" phrase that tripped me up initially. I agree, though, that it's unlikely that "any object in a complex attribute's value" could reasonably be misinterpreted. I still think there might be a value in precision here, but I guess I don't have strong feelings either way.
f4cd8dd to
0d85ddc
Compare
|
👍 for merge from me. |
|
👍 from me as well - as soon as we widen our header to accommodate another item :) |
|
Superseded by #653. I'll resubmit an example payload once the Examples page exists. |
The current explanation on complex attributes doesn't seem to be getting the point through. Once again, there was an issue opened asking how to do it.
Let's see if this revision does the trick.
A usage example was previously rejected from the base spec, so this time it's placed on the repurposed Examples page, introduced in PR #503.