OASIS



References between EDMX Documents

Use Cases

Navigate Between Services

I want to blog about movies I’ve seen. Of course this will become an OData service. Now I’d like to link each blog entry to the corresponding movie entity in the Netflix catalog.

So I create a MovieBlogs OData service with a single entity set BlogPosts and a single entity type BlogPost with a navigation property Movie that uses the Netflix Title entity type.

My service’s sole concern is my blog posts. Using a navigation property to a Netflix Title will allow consumers to navigate from a blog post to the movie it talks about. It might even be possible to filter my blog posts by properties of the Title as long as my implementation can figure out how to delegate that request part to the Netflix service and use the result to internally filter my blog posts.

Consumers of my service need to know how the Netflix Title is structured, so I add a Reference to $metadata.

My service is not a proxy to the Netflix service, so I don’t want to have a Movies entity set in my service. Referencing Netflix does not add Netflix entity sets to my service.

Questions

• How do I “import” the Netflix.Catalog.v2 schema so I can use one of its types in a (navigation) property?

• How do “imports” the System.Data.Objects so I can use one of its entity sets as a navigation property binding?

Annotate Services

Susan has published a service listing all people ever participating in an OASIS TC.

Martin has published a vocabulary for Contact information.

I want to annotate the Person entity type in Susan’s service with Martin’s vCard term, so I create an EDMX document on the web containing my annotations.

Consumers of my annotations need to know where Susan’s service and Martin’s vocabulary can be found, so I add a Reference to Susan’s service and a Reference to Martin’s vocabulary.

My annotations document is just that: a document. It’s not a service, and referencing Susan’s service doesn’t change that.

Questions

• How do I “import” Susan’s schema so that I can target it with an annotation?

• How do I “import” Martin’s vocabulary so that I can use one of its terms?

Reuse Annotations Defined in a Different Edmx Document

I now want to annotate Susan’s service with UI annotations that are interpreted by my hyper-generic OData Viewer app. I want to create two sets of annotations: one for palm-sized devices, one for journal-sized devices.

As my app also understands the vCard term, I want to logically include the annotation file created for the first use case in both device-specific annotation documents without physically copying its contents into two places, and I don’t want to build a server component that “composes” a single addressable resource out of its constituents as my app already knows how to follow links.

Questions

• How do I “include” the Contact annotations in my Display annotations document?

Reuse Types and FunctionImports Defined in a Different Schema

Andrew has defined a type for “raw” XML data and several functions working on that XML type.

I want to use this type in my service and allow clients of my service to use some of these functions in queries to my service.

I only want to add those functions to my service that I have already implemented, and I also don’t want to “inherit” any entity sets that Andrew may have defined in his schema.

Questions

• How do I “add” one of Andrew’s function imports to my service without adding everything from his schema?

Advertise only “Important” Entity Sets in Service Document

My entity data model has hierarchical sub-structures with a few “important” or “root” entity types that are good starting points for hypermedia exploration and many “surrounding” or “dependent” entity types.

I only want to advertise the “important” entity sets in the service document, so I put them into the default entity container and the other entity sets in a “hidden” entity container.

I still want to navigate from entities in the default container to entities in the “hidden” container(s).

Questions

What are the differences when using something defined in

• a different container of the same schema,

• a different schema of the same document, or

• a different document?

Proposal

The Reference elements have a similar purpose as assembly references in C# or the classpath in Java: everything defined in referenced documents can be used in the referencing document using its namespace-qualified name.

Note: Reference is not recursive; references in referenced documents are ignored.

The Using element is similar to the using directive in C# or the import statement in Java: it introduces an alias that can be used instead of the namespace to qualify the name of a CSDL construct. In addition to making documents more readable it also allows switching to a new “version” of the referenced schema by simply changing the value of the Namespace attribute in a Using element.

Note: Using just introduces alternative names; it isn’t required for using a CSDL element from a different schema or document.

The Extends attribute of the EntityContainer element has a similar purpose as the colon in C# or the extends keyword in Java: the container specifying the Extends attribute “inherits” all child elements of the container named in the Extends attribute and thus adds them to the “URL space” of the service defined by this container.

Note: Extends is recursive: if the extended container extends another container etc. all container constructs defined along this chain end up in the first entity container.

The AnnotationsReference element is similar to the #include directive of C and C++, adding selected parts of the referenced document to the current document.

Note: AnnotationsReference is not recursive; references in referenced documents are ignored.

Terminology

• Service = all entity containers defined directly in the metadata document or “inherited” via the Extends attribute of an entity container in the service.

• Model = all CSDL constructs used in the service.

• Scope = the current Edmx document and all directly referenced documents. A CSDL element can only use other CSDL elements defined within the scope of its “source” document.

In the MovieBlogs example the service is just the default entity container of the MovieBlogs schema, the model is the content of the MovieBlogs schema plus the Title entity type and the Movies entity set defined in the Netflix metadata document, and the scope is the MovieBlogs metadata document plus the Netflix metadata document.

Required Changes And Clarifications

The Url attribute of a Reference element MUST point to an Edmx document that contains one or more schemas.

If the referenced document contains Reference elements, these are ignored (unless they are also referenced from the initial Edmx (metadata) document.

A schema is identified by its namespace. This namespace is completely defined by this schema, no “partial” namespaces or “merging” of multiple schema elements into one namespace.

As a consequence the client must refrain from processing a schema element whose namespace it already has processed.

All CSDL constructs in scope can be used via their namespace-qualified name at any location that allows a qualified name. Their definitions are “implicitly imported” into the model of the service.

All entity sets in scope can be used via their namespace-qualified name in the EntitySet attribute of the FunctionImport and NavigationPropertyBinding elements. This does not add these entity sets to the service document.

An entity container from a referenced schema can be added to the service by “extending” it with a container defined directly in the metadata document.

Note: extending an entity container defined in a schema of the initial metadata document is possible, but has the somewhat strange effect of making the same container elements available via two different URLs.

A function import from an “imported” schema can be added to the service via a new Source attribute for the FunctionImport element:

A FunctionImport element that specifies a Source attribute MUST NOT specify parameters or a return type, and vice versa.

Using elements MUST specify an Alias attribute because they now have no reason for existence other than introducing an alias. The Alias attribute was required in OData V1-V3 anyway.

Possible Further Steps

Allow AnnotationsReference to Include Single Terms

As an alternative to including all annotations based on a term namespace (aka vocabulary) we can add an attribute Term that allows including only annotations based on that single term.

Separate Signature Definition from FunctionImport

Similar to entity types and entity sets we could introduce a Function element that defines the parameters and the return type, and use that signature definition in FunctionImport elements.

For functions returning an entity or a collection of entities the function import would also provide the entity set binding.

We might also want a way to mark functions (or their “imports”) as “can (only) be used in filter expressions”, which could be done via the Capabilities vocabulary.

Related Jira Issues

ODATA-195: Simplify entity set qualification rules for NavigationPropertyBinding

If the target entity set is not defined in the same entity container as the enclosing EntitySet element, the entity set name must be qualified with the namespace or alias of the schema that defines the entity set, followed by the entity container.

Examples:

• EntitySet="SomeSet" for an entity set in the same container as the enclosing entity set

• EntitySet="SomeModel.SomeContainer.SomeSet" for an entity set in any container of a model in scope.

ODATA-193: Allow function imports to return entities from a different service

Allow the same notation for the EntitySet attribute as in NavigationPropertyBinding

ODATA-182: Define the term “model”

Model = all CSDL constructs used in service and defined in scope

ODATA-181: Referencing/reusing a model element from a different schema does not require to "include" this schema via a Using element

Define "in scope" to mean: defined in the same metadata document (multiple Schema elements can be contained in the same Edmx document) or defined in a metadata document directly referenced with an edmx:Reference element.

Section 7.3.2: shorten the first sentence to:

A navigation property MUST specify a value for the Type attribute. The value of the type attribute MUST resolve to an entity type or a collection of an entity type in scope.

Section 18.4: rephrase second paragraph to:

The type must be in scope, i.e. if a SimpleIdentifier is used, the type MUST be defined in the same schema, and if a QualifiedName is used, the type MUST be defined in the schema identified by the namespace or alias portion of the qualified name, and the identified schema MUST be part of the same metadata document or MUST have been referenced with edmx:Reference.

ODATA-180: Remove Extends attribute from EntityContainer element

Remove last paragraph from section 11.1

Note: this document proposes to close this issue without action.

ODATA-172: EntitySet may be qualified with namespace or alias and EntityContainer

Extend resourcePath rule:

resourcePath = [ [namespace "." ] entityContainerName "." ] entitySetName [ collectionNavigation ]

/ ...

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download