-
Notifications
You must be signed in to change notification settings - Fork 9.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Allow definition of immutable values in Schema Object #2720
Comments
You can indicate "this field cannot be provided in the request payload" with the subchema |
I agree that there's probably a missing |
Related feature request(?) in the JSON Schema repo: |
It is important to remember that JSON Schema has no notion of whether it is being used for request validation or response validation. If you want to enforce a create only property, then you will need two JSON Schemas, one for the request payload when POSTing and one for response. If you do PUT to create then I don't know how to get around this without the validator having some additional context. |
Normally this type of interface will permit omitting fields that have documented defaults. Instead of A separate annotation propertly like "createOnly" might be easier for clients to understand, however -- and this would be useful for an overall document model that is used across multiple endpoints. |
Edit: I no longer agree with what I wrote in this comment. I now think that
|
able to create | able to edit | able to read | |
---|---|---|---|
default (all actions allowed) | t | t | t |
writeOnly | t | t | - |
createAndRead | t | - | t |
editAndRead | - | t | t |
createOnly | t | - | - |
editOnly | - | t | - |
readOnly | - | - | t |
not present in API (so probably doesn't matter?) | - | - | - |
I think that if it is possible to edit, then it usually doesn't matter if it is also possible to create.
So I consider editOnly
and editAndRead
not useful from practical point of view.
createOnly
, createAndRead
and readOnly
are all immutable
because they can't be edited.
The discussion here is about createOnly
vs immutable
. It think from this explanation and from the table I created it is clear that they are different concepts.
I hope that this table will help make correct decision about what should be included in JSON Schema specification.
In my opinion if we have already "readOnly" and "writeOnly" in JSON Schema specification then we should have also other options from this table.
Another option is to remove writeOnly
from specification and have only 3 attributes: each one for create
edit
and read
attributes as I explained above the table. So for example we could have:
createOnly
editOnly
readOnly
and be able to use up to two of them at once for each property (3 of them at once would mean default: all actions possible)
This seems weird. If field is read-only then it means PUT request can't modify it, so it doesn't matter if we send it in PUT request or not. Also
|
The HTTP PUT method is pretty strict about it's semantics.
PUT requires the full representation to be passed. It's "replace", not "merge and replace", or "modify and replace". If you don't include the read-only field in a PUT request, it's equivalent to removing that field which would be in violation of the the
💯 Exactly right |
I don't agree. Sending read-only fields to API shouldn't happen in PUT request (but if sent then it won't change anything, server may ignore such fields or return error code) |
I also wanted to hop in on this discussion as we have a similar requirement to have a way of indicating that a property is immutable/createOnly. I think the In our API we follow a rather strict (OData style) REST semantics where all CRUD operations are around the same resource type (not separate DTOs with different properties). On code generation the user will get one resource to work with. We have properties we can be supplied only during create and others which are computed/derived or navigation properties (in a data graph). An example: There is a User (resource) which has Orders (resource) and there is a bidirectional navigation between them. The Order has a This makes the **Second use case: ** If you have "many-to-many" relationships in your model. You can supply the IDs of the two related entities on create but not modify them afterwards because they are part of the PrimaryKey making them Disclaimer: We might be a bit influenced on how our models look like due to the .net Entity Framework Core conventions. There you have a ForeignKey property for the ID and a navigation property for the whole object on the same level. You can optionally load the navigation propety. Our API provides the same user(developer) experience on querying, loading and modifying data. We do not practice (or want to practice) a system where we have a nested object holding only the ID as this would have other negative impacts on the server side implementations. Hence I think something like an If we would go for a more breaking adaption likely we would allow setting for each property in which HTTP verbs it is utilized? This would even allow specifying a different behavior on PATCH, POST and PUT. |
A standard way to represent immutability would be useful. Examples: |
I've come across the requirement of defining an immutable field, that is, one that can only be set when the resource is created (POST). The field is not allowed to be modified, therefore it may not be changed via PUT/PATCH. This would be somewhat similar to writeOnly, but with an extra constraint that the field may only be written once, at creation.
The text was updated successfully, but these errors were encountered: