Uploaded image for project: 'OASIS Open Data Protocol (OData) TC'
  1. OASIS Open Data Protocol (OData) TC
  2. ODATA-350

Clearly describe the service documents role, expected usage and responsibility in comparison with $metadata




      As came up in the context of enhancing the "format documents" ATOM and JSON, the service document has a somewhat unthankful role as bootstrapping component, i.e. somehow crucial, but not mandatory for using a service, since $metadata based and/or ad hoc queries MAY achieve identical results.

      Triggered by Evan's comment on ODATA-315 "Or, preferably, conformance with the addressing conventions should be mandatory, so that clients with the metadata document can be guaranteed that they NEVER need to also access the service document." this issue's role is to ensure, that we define, separate and communicate the central concept of a service document in a holistic and economic way.

      Is the service document needed or would it be better to simply further amend the top-level $metadata so that clients only have to deal with one concept of meta information about the data being offered by the service which also remains a useful "channel" in the follow-up requests?

      Would removing the service document be feasible or end in a backwards compatibility nightmare, as a v3 client starting with a service document request would than never be able to start a communication with a v4 server (besides a HTTP 404 response)?

      If we "keep" the service document, it should IMO be clearly stated when and what for it MUST, SHOULD or if really necessary MAY be used and where the separation of concerns w.r.t. the $metadata is to be made.

      Currently this is not really clear to me. What do the others think?




            • Assignee:
              sdrees Stefan Hagen
            • Watchers:
              1 Start watching this issue


              • Created: