odata / vocabularies Goto Github PK

The OData core vocabulary includes the version number in the vocabulary namespace in addition to the URL. This seems redundant and would require OData services that reference the vocabulary to keep namespace and URL in sync.

The proposed convention for community vocabularies stored here would be to include the version in the file name but not the vocabulary namespace.

The structure of the accompanying documentation for vocabularies should account for new terms being added. The current display vocabulary documentation is not amenable to this. Restructure so that the display vocabulary documentation can serve as a template of how to add supplementary documentation going forward.

Similar to the comments that can be placed on elements in C#, we'd like to be able to document known / expected Error Codes that can be returned from an Operation. This allows us to be able to communicate what types of errors a client may expect to receive as well as a blurb about how they can handle it.

Tag the PRs with labels:
PR_Team: PR submitted by OData team members.
PR_Internal: PR submitted by a colleague within Microsoft.
PR_External: PR submitted by a GitHub user outside of Microsoft.

The repository contains six year old copies of the standard vocabularies Core and Capabilities, causing confusion for people accidentally landing here instead of https://github.com/oasis-tcs/odata-vocabularies.

Please remove these outdated copies.

I can't find any .NET examples for implementing these shared vocabularies. I want to use the Display vocabulary.

Trying to implement something i posted on the OData/WebApi issues but maybe this is a better place to ask..

Similar to IndexableByKey, add a Tag to Capabilities to indicate whether an entity set supports Upsert (11.4.4 of the protocol spec).

Question:
Should there be any flag / ability to differentiate support via PUT vs PATCH?

Open Data datasets are described using common terms, such as license, publisher, creation date, and update frequency.

In the open data community, DCAT (http://www.w3.org/TR/vocab-dcat/) defines common terms for this cataloging information, pulling also from Dublin Core (http://dublincore.org/documents/dcmi-terms/).

We should define OData vocabularies to allow marking up an OData service with the same terms for general dataset cataloging.

Currently, Navigation Properties can have a Description and LongDescription annotation placed on them. This can be used to describe what entities in the collection mean, relative to the entity.

We would like the ability to also describe what it means to manipulate entities in a collection.

For example, a service that is used for managing email distribution lists may expose a /Users entity set containing a collection of users and a Distribution/BlockedSenders navigation property contains users whom are blocked from sending mail to that distribution list. A POST to the /Users collection is creating a new user, while a POST to the Distribution/BlockedSenders collection is not creating a new user, but instead blocking them from sending mail to that distribution list. In this case, the service may wish to annotate the BlockedSenders navigation property something like:

Description: A collection of users who are blocked from sending mail to this distribution list.
InsertDescription: Inserting a reference to a user into this collection will block any email they send to this distribution list from being forwarded to other members.
DeleteDescription: Deleting a reference to a user from this collection will restore their ability to send emails to this distribution list.

These annotations could be further used to provide richer comments on auto-generated client libraries and formatted documentation.

The current specification is:

<Term Name="SupportedFormats" Type="Collection(Edm.String)">
  <Annotation Term="Core.Description" String="Media types of supported formats, including format parameters" />
  <Annotation Term="Core.IsMediaType" />
</Term>

It's not clear if only the metadata supports XML, application/xml should be included into the annotation:

  <Annotation Term="Org.OData.Capabilities.V1.SupportedFormats">
    <Collection>
     <String>application/json; odata.metadata=minimal; odata.streaming=true</String>
     <String>application/json; odata.metadata=minimal; odata.streaming=false</String>
     <String>application/json; odata.metadata=minimal</String>
     <String>application/json; odata.metadata=full; odata.streaming=true</String>
     <String>application/json; odata.metadata=full; odata.streaming=false</String>
     <String>application/json; odata.metadata=full</String>
     <String>application/json; odata.metadata=none; odata.streaming=true</String>
     <String>application/json; odata.metadata=none; odata.streaming=false</String>
     <String>application/json; odata.metadata=none</String>
     <String>application/json; odata.streaming=true</String>
     <String>application/json; odata.streaming=false</String>
     <String>application/json</String>
     <String>application/xml</String>
    </Collection>
  </Annotation>
</Annotations>

And in future when JSON is also supported for metadata, a new term like Capabilities.SupportedFormatForMetadata might be helpful for avoid confusion.

It would be very convenient to have a copy of the core vocabulary and the capabilities vocabulary stored here alongside the community vocabularies. Port the vocabularies here and add .md documentation.

The OData core vocabulary uses Org.OData as the root of the vocabulary namespace. We should determine a root namespace that indicates that a vocabulary is expected to be used by a reasonably large portion of the OData community.

The proposal in the initial vocabulary is OData.Community. However, the OData spec says:

The Namespace attribute MUST NOT use the reserved values Edm, odata, System, or Transient.

Determine whether the proposal is truly in conflict with the OData specification, and if so, determine a suitable alternative.

We should probably have a slightly better format for organizing this repository. Making it a dumping ground of xml files may be a bit overwhelming to browse.

Maybe we should have a folder for each top level division of a vocabulary's namespace? For example, Org.Odata.Capabilities.V1 would go in the folder odata-v4/org/odata/capabilities/v1

I'd be open to any organizational scheme, as long as we can roughly think of one and add it to contributing.md

Similar to how the Capabilities vocabulary allows annotating entity sets with information about when an entity set supports $filter, $orderby, and $expand, it should be possible to express the ability to use $select, and which properties may be explicitly not selectable.

An example of why this is needed:
Some services may have the same entity exposed in different entity sets, with different sets of properties available from the different entity sets. This may happen more often with non-contained entities. For example, a service with both Products and Orders entity sets, where Product can have a collection of Orders it is part of, and Order can have a collection of Products it includes, it may be possible to select all Product properties from /Products, but a limited selection of propertiess from /Orders(id)/Products.

Some operations have certain requirements of the entity they are being executed on in order to succeed.

For example, a service managing email may expose a Send operation on a EmailDraft, but sending the email may require at least one of To:, CC:, or BCC: have a value set. We would like the ability to express these requirements as their own annotation (distinct from Description).