Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add name to embedded entities #31

Closed
wants to merge 8 commits into from
Closed

Add name to embedded entities #31

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
71f65d7
[fix #11] Add semantics for specifying client-side validation
Apr 9, 2013
de9f368
fix anchor link?
Apr 9, 2013
75284ef
Merge remote-tracking branch 'upstream/master'
Feb 18, 2014
a6ed10c
Update to sub-entities:
Feb 18, 2014
355b223
fix accidental whitespace
Feb 18, 2014
feb7d30
oops
Feb 18, 2014
4a6d2ed
add quotes
Feb 19, 2014
6590fde
rename `name` to `id`
Feb 22, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 27 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,27 +16,30 @@ The media type for JSON Siren is `application/vnd.siren+json`.
```json
{
"class": [ "order" ],
"properties": {
"orderNumber": 42,
"properties": {
"orderNumber": 42,
"itemCount": 3,
"status": "pending"
},
"entities": [
{
"class": [ "items", "collection" ],
"rel": [ "http://x.io/rels/order-items" ],
{
"id": "items",
"rel": [ "http://x.io/rels/order-items" ],
"href": "http://api.x.io/orders/42/items"
},
{
"class": [ "info", "customer" ],
"rel": [ "http://x.io/rels/customer" ],
"properties": {
"customerId": "pj123",
"name": "Peter Joseph"
},
"links": [
{ "rel": [ "self" ], "href": "http://api.x.io/customers/pj123" }
]
"id": "customer",
"rel": [ "http://x.io/rels/customer" ],
"entity": {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is this?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "standard entity" representation. It's now nested inside of a sub-entity wrapper. By doing this we don't have to modify the actual entity if its nested. Attributes like "href", "rel", and "name" would go in the sub-entity wrapper since they would never be found on the standard entity.

*I'm using the term "standard entity" in the way it is used in the docs to signify an entity that is not a "sub-entity"

"class": [ "info", "customer" ],
"properties": {
"customerId": "pj123",
"name": "Peter Joseph"
},
"links": [
{ "rel": [ "self" ], "href": "http://api.x.io/customers/pj123" }
]
}
}
],
"actions": [
Expand All @@ -63,7 +66,7 @@ The media type for JSON Siren is `application/vnd.siren+json`.

##Introduction

Siren is a hypermedia specification for representing entities. As HTML is used for visually representing documents on a Web site, Siren is a specification for presenting entities via a Web API. Siren offers structures to communicate information about entities, actions for executing state transitions, and links for client navigation.
Siren is a hypermedia specification for representing entities. As HTML is used for visually representing documents on a Web site, Siren is a specification for presenting entities via a Web API. Siren offers structures to communicate information about entities, actions for executing state transitions, and links for client navigation.

Siren is intended to be a general specification of a generic media type that can be applied to other types that are not inherently hypermedia-powered. The initial implementation is JSON Siren. Other implementations, such as XML Siren, may also be implemented using the Siren specification.

Expand Down Expand Up @@ -104,7 +107,7 @@ A collection of action objects, represented in JSON Siren as an array such as `{
####`title`
Descriptive text about the entity. Optional.


###Sub-Entities

Sub-entities can be expressed as either an embedded link or an embedded representation. In JSON Siren, sub-entities are represented by an `entities` array, such as `{ "entities": [{ ... }] }`.
Expand All @@ -113,9 +116,9 @@ Sub-entities can be expressed as either an embedded link or an embedded represen

A sub-entity that's an embedded link may contain the following:

#####`class`
#####`id`

Describes the nature of an entity's content based on the current representation. Possible values are implementation-dependent and should be documented. MUST be an array of strings. Optional.
The id of the sub-entity. Optional.

#####`rel`

Expand All @@ -127,7 +130,11 @@ The URI of the linked sub-entity. Required.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a good reason to remove the rel requirement for sub-entities?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

rel is still required for both "linked" sub entities and "embedded" sub entities. That section addressed the difference between a "standard" entity and an "embedded" sub-entity, however, that difference no longer exists so I thought it would make sense to remove it.

There is still the section that defines what a rel is and it states that it is required for sub entities. (it just doesn't show up in the diff)

Is there a better way to communicate the rel requirement?

####Embedded Representation

Embedded sub-entity representations retain all the characteristics of a standard entity, but MUST also contain a `rel` attribute describing the relationship of the sub-entity to its parent.
Unlike an embedded link, a sub-entity that's an embedded representation must contain an `entity` instead of an `href`:

#####`entity`

The embedded representation of the entity, retaining all the characteristics of a standard entity. Required.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This would be a good place to note the rel requirement, if we really need it to be there. I'm not convinced it should be a requirement, but we shouldn't silently delete the requirement. That should be a separate issue, IMO.


###Classes vs. Relationships

Expand Down Expand Up @@ -200,7 +207,7 @@ A name describing the control. Required.
The input type of the field. This may include any of the following [input types](http://www.w3.org/TR/html5/single-page.html#the-input-element) specified in HTML5:

`hidden`, `text`, `search`, `tel`, `url`, `email`, `password`, `datetime`, `date`,
`month`, `week`, `time`, `datetime-local`,
`month`, `week`, `time`, `datetime-local`,
`number`, `range`, `color`, `checkbox`,
`radio`, `file`, `image`, `reset`, `button`

Expand Down