Open odrotbohm opened 3 years ago
@odrotbohm :
yes -- this is a weak point in the spec. it was originally there because we wanted to start with just a single template in the response but allow for futures where multiple templates where returned. so, you're assumptions are correct.
what's a good alternative here? things we need to support (i think):
there may be other important scenarios, too.
ideas?
Hi,
I think default
should not exist at all. It does not give any information about what it can or can not do. You have to check name, method, properties to understand what the template does. I think the template keys should in most case be domain driven.
For example, if we've got a template to confirm a payment, it could be named confirm-payment
, being the only available template or not.
Is there a use case where default
is obvious for a client ?
I'm working with HAL+Form in business projects and this default
template is really painful. I've got a lot of resources with each its representation and I'm like "Oh yeah, in this representation, the default template does that" instead of "Of course confirm-payment just confirms a payment !".
Maybe default
should be a boolean property of templates instead, like:
confirm-payment: {
default: true,
name: 'Confirm payment',
properties: [...]
}
yes @ecattez , this needs attention.
i'd like to make sure we don't break anything that's already out there, so first, i'd like to keep "default" (taking away is a breaking change, i think).
but maybe we can move this from "MUST" to "SHOULD" and then offer some guidance along the lines of @odrotbohm to help those curently depending on it.
something like this text:
@odrotbohm
your comment about the documentation is spot on. i've never quite had the wright way to say that the collection key (JSON key) is what this is about, not a property named key
.
surely this is a common problem, right?
what's a better way to write this up?
Summarizing, regarding default
, what if we:
default
for the name of the templatedefault
but should consider the first map entry the default one as fallbackRe keys: I think it's fine to talk about the key requirements right here:
The
_templates
element contains a dictionary collection of template objects. …
in a way discussed above and remove 3.2.2 entirely?
This issue just came up again. @mamund – Do you think we're far enough down the discussion to come to some level of consensus? I'll happily draft a PR.
yes. let's sort out an agreement and make the changes.
feel free to draft a PR to get this rolling and let's see if we an close this out in a timely way.
thanks for this.
Would I submit changes to the index.adoc
, index.html
or both?
IIRC, the adoc is the final source. we generate the HTML from there.
Mike Amundsen
APIs, Microservices, and Digital Transformation 7310 Turfway Rd. Suite 550, Florence, KY, 41042
@.*** https://zoom.us/j/8593726715 http://linkedin.com/in/mamund http://b.mamund.com/meetme http://training.amundsen.com http://twitter.com/mamund
On Sun, Jan 15, 2023 at 5:17 PM Oliver Drotbohm @.***> wrote:
Would I submit changes to the index.adoc, index.html or both?
— Reply to this email directly, view it on GitHub https://github.com/mamund/hal-forms/issues/82#issuecomment-1383267806, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAJLSGF2QQQS2VH7OKM32LWSRZQ7ANCNFSM5BH4RYLA . You are receiving this because you were mentioned.Message ID: @.***>
Template key specification
The specification of the
_templates
collection is a bit odd. It lists all properties, including thekey
property, when in fact – I think –key
is not an actual property, but the key of the dictionary of all templates. From the spec, you could think that a_templates
definition might look like this:The reason you can get to this assumption is that
key
is discussed on the same level ascontentType
et al. and among all properties that can be used within a single template entry. Does it make sense to pull that discussion up into 3.2 to avoid this confusion?Template key defaulting
There's still room for clarification in the required naming for multiple templates. Assume you have a single, logical template
foo
. As per the spec, that needs to be nameddefault
. If that resource evolves to support a second templatebar
, would (should?) the list of template names change tofoo
,bar
or stay withdefault
,bar
? The former might be disrupting to clients that look fordefault
only. The latter – and that renaming in general – mask the logical name for the advertised first transition.This always seemed a bit weird to me. What's the original intention behind that "if it's one, it's got to be named
default
" rule? I suspected that it was introduced to make it easy for clients to find "a default" template, but as the spec currently restricts the rules to the case of one template present only, it would be the single, canonical template anyway, wouldn't it? To convey those high-level semantics, I would expect usingdefault
to be of even greater significance in the case of multiple templates, although you could argue that with a stable key ordering, clients could generally assume the first entry to be "the default one". I am not sure how common it is to rely on ordering of the keys within a JSON map, though. If it's not common, then staying withdefault
in the case of multiple templates available would kind of be required.The current state of affairs complicates the implementation of the server as it's not obvious how to behave in case of multiple templates (see this ticket in Spring HATEOAS) for example. Anyone aware how other server libraries treat this?