[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [OASIS Issue Tracker] Updated: (ODATA-386) odata-v4.0-csprd01-part1-protocol, 3 Data Model, appears to be an unnumbered list of definitions, with annotations defined in a separate subsection - suggest new format, etc.
[ http://tools.oasis-open.org/issues/browse/ODATA-386?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Michael Pizzo updated ODATA-386:
--------------------------------
Proposal:
3 Data Model
This section provides a high-level description of the Entity Data Model (EDM): the abstract data model that is used to describe the data exposed by an OData service. An OData Metadata Document is a representation of a service's data model exposed for client consumption.
The central concepts in the EDM are entities, relationships, entity sets, actions, and functions.
Entities are instances of entity types (e.g. Customer, Employee, etc.).
Entity types are named structured types with a key. They define the named properties and relationships of an entity. Entity types may derive by single inheritance from other entity types.
The key of an entity type is formed from a subset of the primitive properties (e.g. CustomerId, OrderId, LineId, etc.) of the entity type.
Complex types are keyless named structured types consisting of a set of properties. These are value types whose instances cannot be referenced outside of their containing entity. Complex types are commonly used as property values in an entity or as parameters to operations.
Properties declared as part of a structured type's definition are called declared properties. Instances of structured types may contain additional undeclared dynamic properties. A dynamic property cannot have the same name as a declared property. Entity or complex types which allow clients to persist additional undeclared properties are called open types.
Relationships from one entity to another are represented as navigation properties. Navigation properties are generally defined as part of an entity type, but can also appear on entity instances as undeclared dynamic navigation properties. Each relationship has a cardinality.
Enumeration types are named primitive types whose values are named constants with underlying integer values.
Type definitions are named primitive types with fixed facet values such as maximum length or precision. Type definitions can be used in place of primitive typed properties, for example, within property definitions.
Entity sets are named collections of entities (e.g. Customers is an entity set containing Customer entities). An entity's key uniquely identifies the entity within an entity set. An entity can be a member of at most one entity set at any given point in time. Entity sets provide entry points into the data model.
Operations allow the execution of custom logic on parts of a data model. Functions are operations that do not have side effects and can be further composed, for example, with additional filter operations, functions or an action. Actions are operations that allow side effects, such as data modification, and cannot be further composed in order to avoid non-deterministic behavior.
Actions and functions are either bound to a type, enabling them to be called as members of an instance of that type, or unbound, in which case they are called as static operations. Action imports and function imports enable unbound actions and functions to be called from the service root.
Singletons are single entities which are accessed as children of the entity container.
An OData resource is anything in the model that can be addressed (an entity set, entity, property, or operation).
Refer to [OData-CSDL] for more information on the OData entity data model.
3.1 Annotations
Model and instance elements can be decorated with Annotations.
Annotations can be used to specify an individual fact about an element, such as whether it is read-only, or to define a common concept, such as a person or a movie.
Applied annotations consist of a term (the namespace-qualified name of the annotation being applied), a target (the model or instance element to which the term is applied), and a value. The value may be a static value, or an expression that may contain a path to one or more properties of an annotated entity.
Annotation terms are defined in metadata and have a name and a type.
A set of related terms in a common namespace comprises a Vocabulary.
was:If this is to be the location of definitions (always a good idea) and a description of the data model, suggest that it be all the definitions, formatted as a definitions list, perhaps even in separate sub-sections, followed by the data model that makes use of those definitions. The definitions need to be consistently worded, etc. Then compared to the text to make sure our usage is consistent with the definitions.
Environment: [Proposed]
Added proposed revised text for the section. It addresses incorrect use of MAY/MUST/SHOULD, dangling/incorrect references to related concepts, incompleteness, and attempts to clarify wording in general.
Note that I have left Annotations as a separate subsection of Data Model. I played with merging the two but ultimately decided it was a useful distinction to make between the elements that make up the Data Model and the ability to annotate those data model elements (as well as data instances).
> odata-v4.0-csprd01-part1-protocol, 3 Data Model, appears to be an unnumbered list of definitions, with annotations defined in a separate subsection - suggest new format, etc.
> ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
>
> Key: ODATA-386
> URL: http://tools.oasis-open.org/issues/browse/ODATA-386
> Project: OASIS Open Data Protocol (OData) TC
> Issue Type: Improvement
> Components: OData Protocol
> Affects Versions: V4.0_CSD01
> Environment: [Proposed]
> Reporter: Patrick Durusau
> Fix For: V4.0_CSD02
>
>
> odata-v4.0-csprd01-part1-protocol, section 3 is titled "Data Model" but appears to be an unnumbered list of definitions. And, annotations are split out into a separate subsection.
> The wording of the definitions (if that is what they are) is consistent from definition to definition. To illustrate:
> ****
> Entity types are nominal structured types with a key. They define the named properties of an entity and MAY define relationships with, or derived by single inheritance from, other entity types.
> The entity key of an entity type is formed from a subset of primitive properties (e.g. CustomerId, OrderId, LineId, etc.) of the entity type
> Complex types are keyless nominal structured types consisting of a set of properties. These are value types that lack identity. Complex types are commonly used as property values in an entity or as parameters to operations.
> ****
> First, note that "nominal" isn't defined until 4.1.
> If this is a list of definitions or details of the data model, shouldn't it be inclusive and complete?
> Second, "Entity types are nominal structured types with a key."
> key?
> Do we mean "entity key," which is defined in the next paragraph?
> Third, "Complex types are keyless nominal structured types consisting of a set of properties. These are value types that lack identity."
> lack identity? If nominal means what 4.1 suggests, then complex types have names. That leads me to puzzle over what it means to lack identity? Do we mean it lacks a key?
> FYI, identity is used only one other time in odata-v4.0-csprd01-part1-protocol, at 11.4.9.4 to say that:
> "have no individual identity, PATCH is not supported for collection properties.
> Services MUST treat collection properties as a unit."
> So I am assuming "identity" isn't central to the data model.
> I am curious about the reason for nominal versus named, unless that is just a legacy practice.
> BTW, the irony of:
> "Refer to [OData-CSDL] for more information on the OData entity data model."
> in CSDL was not lost on me. ;-)
--
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]