Somehow writeOnly seems to have broken? Bug?

[BasMichielsen]

I have the following simple struct for which I want a speciesID when a new record needs to be added (in request) but when used as a response the speciesID field should not be present. I very much believe this used to work a few huma versions earlier, but now in the response the field appears to be there. Also, removing writeOnly="true" has no effect, in both cases the same behaviour is exhibited.

type Animal struct {
	ID        string `json:"ID" format:"uuid" readOnly:"true" doc:"The ID of this animal."`
	Name      string `json:"name" doc:"The name of this animal."`
	SpeciesID string `json:"speciesID" format:"uuid" writeOnly:"true"`
}

Funny addition: Stoplight's Response Example does not contain the field speciesID but the true response does. So somehow Stoplight thinks it should not be there, probably because of the writeOnly="true" tag, yet it seems somewhere internally the field is not removed from the response.

[danielgtaylor]

@BasMichielsen I see how this could be a little confusing. The writeOnly option is just used by Huma to generate the OpenAPI. Huma won't remove those values from your response object (and I don't think it ever did?) so you will be responsible for doing that, and it should be used together with omitEmtpy if the same object is used in a response, like:

SpeciesID string `json:"speciesID,omitempty" format:"uuid" writeOnly:"true"`

Later in your code you can use a projection or field selection in the DB call to not load that field, or manually clear it in your handler like:

resp.Body.SpeciesID = ""
return resp, nil

Hope that helps! I will try and update the documentation to make this more clear.

[BasMichielsen]

@danielgtaylor Thanks for having a look into this. I read the updated docs and I understand the current behaviour of huma. Now that you mention that huma never did remove the fields from the response I went to have a look at my own code and what I did differently previously. It appears that I did in fact use writeOnly="true" together with omitempty and that combination does remove the field automatically from the response. So that is likely the behaviour I was referring to. However, I noticed that later I removed the omitempty because it made the field optional in the request. So, I probably have been working against myself in two different instances "the field should be removed from the response" => writeOnly="true" + omitempty, and then later "the field should be required in the request" => remove omitempty and suddenly it popped up again in the response.

How can I implement the requirements "required in request" + "automatically removed in response" together?

[BasMichielsen]

I seem to have found the answer to my own question, just for reference and perhaps for others with the same question. The combination of readOnly:"true" omitempty and required:"true" makes the field required on requests and automatically removed from response if the backend ensures that the field contains a value that is considered empty by omitempty.

@danielgtaylor feel free to integrate this finding with the docs if you want. I reckon my case is relatively common?

[danielgtaylor]

@BasMichielsen thanks, makes sense. FYI another option if things start to get too complex is just to use different structs. You can always use composition have a struct of common fields and then embed it in the request/response.

[BasMichielsen]

That is actually a really nice idea! I do something similar now by having a struct Animal with fields that describe the animal in question and an AnimalPlus struct that is a composition of Animal plus more fields that I want in the response. In this case it contains a Species field in which I embed the species of the animal in question, and thus do not fill the speciesID field of Animal. However, it never occurred to me that I could make a three way split based on what I want in the response and what in the request and have Animal as an abstract definition, probably because I was under the impression that huma automatically removed my speciesID field (as mentioned earlier). However, the setup Animal, AnimalForRequest and AnimalForResponse is actually clearer and offers only those fields that are required in the request/response and others not.
Hmmm, in my next project with huma I will certainly opt for that. And perhaps in the current project too if I find the time to refactor.