[OASIS Issue Tracker] (ODATA-808) Minor changes to new OnlyDeclaredProperties annotation

[OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>]

     [ https://issues.oasis-open.org/browse/ODATA-808?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Michael Pizzo updated ODATA-808:
--------------------------------

    Environment: [Proposed]  (was: [Applied])
    Description: 
The new "OnlyDeclaredProperties" should apply to complex types as well as entity types, since both can be open and both can have dynamic properties unless otherwise annotated.

Also, the resolution suggested one of two alternatives; either calling the term "AdditionalProperties", consistent with the JSON Schema spec, or coming up with a name that meant dynamic properties wouldn't exist, so we could define a default and use it as a tagging term. We left it to the editors in the hopes that we could find a better name than "OnlyDeclaredProperties" for the tagging option, but since this should be the exception to what clients should be prepared to accept, I would prefer to go with the (more intuitive) option of using "AdditionalProperties" and require the service to provide the value "false" for cases where additional properties were not allowed: 
 <Annotation Term="Core.AdditionalProperties" Bool="false"/> 

Finally, we should define what happens if this annotation specifies that additional properties are not allowed, but the type is marked as open. A type may be defined as open in a common definition, but restricted in a particular usage, so it probably makes sense for the annotation to override the attribute.

  was:
In OData V3 only opentypes were allowed to return properties not advertised in $metadata.

In OData V4, for increased resiliency, we said that clients should be prepared to handle additional properties on any resource, and the introduction of PATCH as the preferred method for updating allows that to happen without loss.

However, we lost the ability for a service to say that they will never return additional properties (which is probably the default case). Since clients are required to support additional properties we didn't think this was important, but as we look to a json-schema format it becomes interesting for telling clients (i.e., for validation) whether or not additional properties are allowed.

       Proposal: 
Rename "OnlyDeclaredProperties" to "AdditionalProperties".
Make apply to ComplexTypes as well as EntityTypes
Clarify that, if the type has the OpenType=true attribute, and the annotation specifying that additional properties are not allowed, that this usage of the type is closed and does not support additional properties. 

  was:
Add a new tagging annotation "OnlyDeclaredProperties" that applies to entity types and specifies that the service will not return dynamic properties not specified in $metadata.

This only refers to properties. Services are still allowed to return instance annotations. JSON-Schema representation would include patternproperties for annotations.

Applied: https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/vocabularies/Org.OData.Core.V1.xml?rev=673


> Minor changes to new OnlyDeclaredProperties annotation
> ------------------------------------------------------
>
>                 Key: ODATA-808
>                 URL: https://issues.oasis-open.org/browse/ODATA-808
>             Project: OASIS Open Data Protocol (OData) TC
>          Issue Type: Bug
>          Components: Vocabularies
>    Affects Versions: V4.0_ERRATA02
>         Environment: [Proposed]
>            Reporter: Michael Pizzo
>             Fix For: V4.0_ERRATA03
>
>
> The new "OnlyDeclaredProperties" should apply to complex types as well as entity types, since both can be open and both can have dynamic properties unless otherwise annotated.
> Also, the resolution suggested one of two alternatives; either calling the term "AdditionalProperties", consistent with the JSON Schema spec, or coming up with a name that meant dynamic properties wouldn't exist, so we could define a default and use it as a tagging term. We left it to the editors in the hopes that we could find a better name than "OnlyDeclaredProperties" for the tagging option, but since this should be the exception to what clients should be prepared to accept, I would prefer to go with the (more intuitive) option of using "AdditionalProperties" and require the service to provide the value "false" for cases where additional properties were not allowed: 
>  <Annotation Term="Core.AdditionalProperties" Bool="false"/> 
> Finally, we should define what happens if this annotation specifies that additional properties are not allowed, but the type is marked as open. A type may be defined as open in a common definition, but restricted in a particular usage, so it probably makes sense for the annotation to override the attribute.



--
This message was sent by Atlassian JIRA
(v6.2.2#6258)