Add a "writeOnly" (formerly "secret") annotation

[handrews]

This is for passwords and other senstive or write-only fields.

This addresses #249.

[dlax]

Quite straightforward, so why not?

[handrews]

Last call-ish on this one!

Given it's simplicity, and the fact that I'd like to move into the feature-freeze editorial review on Friday, I will probably merge this on Friday even though it will be one day early.

[philsturgeon]

I'm not sure if secret is the way to advertise the feature, even if it's what the keyword is being used for. I think writeOnly would be a tad more consistent?

Writing things but not being able to see them after is what they're asking for, no?

[handrews]

@philsturgeon I'm open to writeOnly, the same thought had occurred to me but I figured I'd see if this got any reaction at all :-)

@dlax and/or @chrisdostert how do you feel about it?

Thinking a bit more, I can see writeOnly as being a general annotation here, which UIs may or may not interpret as using a "password" widget in the UI. The UI Schema proposal would then including a more detailed indicator of what kind of widget to use.

Does that seem like a good distinction?

[handrews]

I reworked this as writeOnly and I like it a lot. Not sure if it needs to sit longer for consideration? I am still inclined to merge it on Friday and include it in final review but definitely speak up if you would be concerned about that. I could add a CREF note about "secret" as an alternative if there are concerns about people missing this discussion.

Another use case for writeOnly is that I often find that triggering actions in a RESTful system is done using state manipulation fields that are often logically nulled out as soon as they are processed (not a literal JSON null, but removed entirely). They have no state representation appearance, they are purely buttons/triggers that can be activated. So that would be a writeOnly field that is not a secret field. It's not removed from responses because of sensitivity, just because it is not useful in responses at all.

[philsturgeon]

Fantastic.

[chrisdostert]

@philsturgeon @handrews I think both are useful & have specific semantics & use cases.

Knowing something is write only is not the same as knowing it's secret.

For example, think of logging; write-only instances might be included in logs whereas secret instances might not.

[handrews]

@chrisdostert yes, agreed they are both useful. The proposal is that writeOnly is useful in general, and secret is useful in presentation (logging would be a presentation concern- I should be clear that I did not just mean "UI" as in "web form")

There is a similar separation for readOnly, where a read-only field might be managed as hidden form field (you can't change it so don't show it), or it might be managed by displaying the value as a non-editable field (you can't change it, but you should know about it).

So...
generic usage: readOnly, writeOnly
presentation: hidden, secret

[handrews]

This spec is for generic usage, presentation ideas go in json-schema-org/json-schema-vocabularies#2

[handrews]

Also, you can easily treat writeOnly as if it meant "secret" in your application without violating either the letter or spirit of the specification. The reverse is not true.

[handrews]

@chrisdostert if you want to argue that we should not move forward with writeOnly please do so by tomorrow. Otherwise I will assume that you want to see secret added somewhere but are OK with that being tracked as json-schema-org/json-schema-vocabularies#6 which I filed for this as a presentation description request.

[handrews]

Of course if you come back next week with new objections we can continue to discuss changes, I would just like to include this in the "final review" announcement for this weekend.