[OASIS Issue Tracker] Updated: (ODATA-34) Control verbosity of $metadata response: include annotations or documentation

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

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

Ralf Handl updated ODATA-34:
----------------------------

    Proposal: 
Add a new Prefer preference value, defined as follows:

    odataVocabularies = "odata-vocabularies" "=" DQUOTE [ vocabularyIdentifier [ COMMA vocabularyIdentifier] ] DQUOTE
    vocabularyIdentifier =  STAR | [excludeOperator] ("Edm.Documentation" | vocabularyNamespace )
    vocabularyNamespace = namespace ["." STAR]
    excludeOperator = "-"

The value of odata-vocabularies is a comma separated list of vocabulary namespaces to include or exclude in a data or metadata response, with "*" representing all, and "Edm.Documentation" representing documentation elements within a metadata document. Prefer is (as always) a hint which can be ignored by the service. In the absence of the odata-vocabularies preference, the service is free to decide which vocabulary elements to return.

The most specific identifier always takes precedence (so a specific namespace takes precedence over *). The behavior if the same identifier value is specified to both be excluded and included is undefined; the service may return or omit the specified vocabulary but must not raise an exception.

Services MAY include the Preference-Applied header in the response to specify the specific vocabularies that may have been included in the response where appropriate but SHOULD NOT specify * or excluded vocabularies.

Examples:

Include all vocabularies, including documentation elements within a metadata document:
    Prefer: odata-vocabularies="*"
Do not include any vocabularies or documentation elements:
    Prefer: odata-vocabularies=""
Include only documentation elements:
    Prefer: odata-vocabularies="Edm.Documentation"
Include all vocabularies, but exclude documentation elements within a metadata document:
    Prefer: odata-vocabularies="*,-Edm.Documentation"
Include only vocabularies defined directly under the odata namespace:
    Prefer: odata-vocabularies="odata"
Include only vocabularies defined anywhere within the odata namespace:
    Prefer: odata-vocabularies="odata.*"

  was:
Add a new Prefer preference value, defined as follows:

    "odata-vocabularies" = quotation-mark [ vocabularyIdentifier [ COMMA vocabularyIdentifier] ] quotation-mark
    vocabularyIdentifier =  STAR | [excludeOperator] ("Edm.Documentation" | vocabularyNamespace )
    vocabularyNamespace = namespace ["." STAR]
    excludeOperator = "-"

The value of odata-vocabularies is a comma separated list of vocabulary namespaces to include or exclude in a data or metadata response, with "*" representing all, and "Edm.Documentation" representing documentation elements within a metadata document. Prefer is (as always) a hint which can be ignored by the service. In the absence of the odata-vocabularies preference, the service is free to decide which vocabulary elements to return.

The most specific identifier always takes precedence (so a specific namespace takes precedence over *). The behavior if the same identifier value is specified to both be excluded and included is undefined; the service may return or omit the specified vocabulary but must not raise an exception.

Services MAY include the Preference-Applied header in the response to specify the specific vocabularies that may have been included in the response where appropriate but SHOULD NOT specify * or excluded vocabularies.

Examples:

Include all vocabularies, including documentation elements within a metadata document:
    Prefer: odata-vocabularies="*"
Do not include any vocabularies or documentation elements:
    Prefer: odata-vocabularies=""
Include only documentation elements:
    Prefer: odata-vocabularies="Edm.Documentation"
Include all vocabularies, but exclude documentation elements within a metadata document:
    Prefer: odata-vocabularies="*,-Edm.Documentation"
Include only vocabularies defined directly under the odata namespace:
    Prefer: odata-vocabularies="odata"
Include only vocabularies defined anywhere within the odata namespace:
    Prefer: odata-vocabularies="odata.*"


> Control verbosity of $metadata response: include annotations or documentation
> -----------------------------------------------------------------------------
>
>                 Key: ODATA-34
>                 URL: http://tools.oasis-open.org/issues/browse/ODATA-34
>             Project: OASIS Open Data Protocol (OData) TC
>          Issue Type: New Feature
>          Components: OData CSDL v1.0, OData Protocol v1.0, OData URL Conventions v1.0
>    Affects Versions: WD01
>         Environment: [Proposed]
>            Reporter: Ralf Handl
>             Fix For: WD01
>
>
> Metadata documents may contain Documentation, ValueAnnotation and TypeAnnotation elements that quite increase the size of the document.
> It is desirable for (especially mobile) clients to control the size of the response and include e.g. only annotations of vocabularies the client can understand.
> This may be done via headers (Prefer, Accept?), system query options, or by exposing $metadata as an OData service itself, see ODATA-126:
> GET ~/$metadata/EntityTypes('Model.Person')?$expand=Annotations
> Ideally combined with filtering on expanded entities, see ODATA-32.

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://tools.oasis-open.org/issues/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira