Uploaded image for project: 'OASIS Open Data Protocol (OData) TC'
  1. OASIS Open Data Protocol (OData) TC
  2. 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.

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: V4.0_CSD01
    • Fix Version/s: V4.0_CSD02
    • Component/s: Protocol
    • Labels:
      None
    • Environment:

      [Applied]

    • Proposal:
      Hide

      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.

      Show
      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.
    • Resolution:
      Show
      Core: https://www.oasis-open.org/committees/document.php?document_id=49675&wg_abbrev=odata JSON: https://www.oasis-open.org/committees/document.php?document_id=49674&wg_abbrev=odata Atom: https://www.oasis-open.org/committees/document.php?document_id=49673&wg_abbrev=odata Accepted: https://www.oasis-open.org/committees/download.php/49679/odata-meeting-43_on-20130624-minutes.html#odata-386

      Description

      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.

        Attachments

          Activity

            People

            • Assignee:
              mikep Michael Pizzo
              Reporter:
              Patrick Patrick Durusau
            • Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: