search

kevinswiber / siren

Structured Interface for Representing Entities, super-rad hypermedia
MIT License
1.3k stars 71 forks source link

Action name uniqueness constraint #57

Closed tompahoward closed 9 years ago

tompahoward commented 9 years ago

As discussed over at https://groups.google.com/forum/#!topic/siren-hypermedia/cwyIzM4jwOc

apsoto commented 9 years ago

The description is good, but the location in the document is strange sandwiched between name and class.

Seems like it belongs under the Action header above name

tompahoward commented 9 years ago

I'm happy with is position, but I agree it's confusing because of the switch from name's <code> heading to Uniqueness Constraint's non-code heading. I've switched it to a level 6 heading and I think that make's it clearer that it's a sub-heading to name.

Let me know what you think.

apsoto commented 9 years ago

Now that you've adjusted it I see the intent better. Seems to me the sub-heading is unnecessary. It's just part of the name spec/doc

kevinswiber commented 9 years ago

Should the behavior of clients be undefined? Would it make sense to say clients should default to picking the last-defined action with the same name?

On formatting: The emphasis on MUST and undefined are inconsistent with the rest of the document. I agree that the sub-heading is a little much, but I don't feel too strongly about it.

tompahoward commented 9 years ago

Layout and formatting updated.

I specified the behaviour as undefined, because that's the only option that is backward compatible with existing clients. I can change it to "When parsing a document that violated this constraint, clients MUST ignore all but the last action for a repeated name." However, making that change would make a unknown number of existing clients non-conforming with the spec. Are you ok with that?

I'd prefer the spec to more specific (i.e. take the last action rather than undefined), but being new to this, I don't know how important it is to avoid making existing clients non-conforming. What's your guidance?

apsoto commented 9 years ago

makes sense to me to keep it backward compatible unless there is some versioning on the spec

tompahoward commented 9 years ago

@kevinswiber, do you want me to keep it backward compatible or would you prefer me to increment the spec version number?

If the later, should the new version be 0.6.2, 0.7.0, or something else?

kevinswiber commented 9 years ago

@tompahoward @apsoto Backwards compatibility is the right approach. If we had a "client implementation considerations" document, and we probably should, we could suggest handling it that way. I'm good to merge!