Nested Required payload attributes are not required in docs.

[ribas...@gmail.com]

Using the example from the docs, I am trying to create a resource with a required nested attribute.

action :create do
routing { post '' }
payload do
attribute :title, String, required: true
attribute :text, String, required: true
attribute :author do
attribute :id, Integer, required: true
end
attribute :tags, Attributor::Collection.of(String)
end
end

The docs that are generated from this shows that title and text are required but author id is optional. This seems wrong to me if I understand the documentation.

Thanks,

Enric Ribas

[Josep Blanquer]

Enric,

A couple of things to clarify how this works:

1.  The required/optional separation in the docs is based on the top-level attribute requirements.
   
2. Requirements in an inner struct (like your author attribute) only are applied "if" the attribute is passed. (i.e. they are not going to transitively make the enclosing structures be "required").

So, with that in mind, the payload you have defined above says that:

the attribute :author Struct is "NOT" required. If it is, you need to define it like you do in any other attribute.

So, perhaps, what you are really trying to express is:

   attribute :author, required: true do

      attribute :id, Integer, required: true
    end

...which means, the author attribute is always required. And from its attributes, the "id" should always be passed in too. (but you could have other inner attributes like :name that are not necessarily required)

Now, you bring up an interesting (but tangential point) about how to best document nested requirements in the doc browser...because the initial grouping of the table rows is only based on the top level attributes, but then any nested attributes might or might not be required (and should still be documented in the table)...so, we might need to add some column or marker to denote that. For example, in your case, the nested "id" inside the author should be properly marked as "required" in the table...regardless of the top level author being required or not...

Thank you for the feedback!

Josep M.

--
You received this message because you are subscribed to the Google Groups "praxis-support" group.
To unsubscribe from this group and stop receiving emails from it, send an email to praxis-suppor...@googlegroups.com.
To post to this group, send email to praxis-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/praxis-support/610fce71-caa0-4c51-bd4d-13bb0d73fef5%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[ribas...@gmail.com]

Thank you for your very in-depth reply. I appreciate your time.

The behaviour of Praxis is what I expected, I guess it was just the output of the API docs that was confusing. Yes, I think it's a little unclear as to what would happen. It would be great to have another column or a slightly different format.

But now I understand how it works and can continue on. :)

--enric