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

Define a validation term for terms applicable in a given context

    XMLWordPrintable

    Details

    • Type: New Feature
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: V4.01_CS01
    • Fix Version/s: V4.01_CS02
    • Component/s: Vocabularies
    • Labels:
      None
    • Proposal:
      Hide

      Add new term ApplicableTerms to the Validation vocabulary that can be used to hint at a list of additional annotations applicable in the context of the target annotated with this ApplicableTerms:

        <Term Name="ApplicableTerms" Type="Collection(Core.QualifiedTermName)">
    <Annotation Term="Core.Description" String="Names of specific terms that are applicable and may be applied in the current context. This annotation does not restrict the use of other terms." />
  </Term>

       

      Example 1: Express the applicability of term Exclusive in the context of terms Minimum and Maximum:

      Applied:

      <Annotations Target="SomeType/SomeSensorProperty">
    <Annotation Term="Validation.Maximum" Decimal="1.34529">
      <Annotation Term="Validation.Exclusive" />
    </Annotation>
  </Annotations>

       Enhanced Terms: 

        <Term Name="Minimum" Type="Edm.Decimal" Scale="variable" AppliesTo="Property Parameter Term">
    <Annotation Term="Core.Description" String="Minimum value that a property, parameter, or term can have." />
    <Annotation Term="ApplicableTerms">
      <Collection>
        <String>Validation.Exclusive</String>
      </Collection>
    </Annotation>
  </Term>

       

        <Term Name="Maximum" Type="Edm.Decimal" Scale="variable" AppliesTo="Property Parameter Term">
    <Annotation Term="Core.Description" String="Maximum value that a property, parameter, or term can have." />
    <Annotation Term="ApplicableTerms">
      <Collection>
        <String>Validation.Exclusive</String>
      </Collection>
    </Annotation>
  </Term>

       

       Example 2: Individual term properties can be enhanced with further annotations

      Individual parts of a term such as a individual property or a complex type can be annotated to accept further annotations. Consider a term T with a structure having two properties, one of which may be further annotated with a certain aspect.

      <Term Name="HasAspect" Type="Core.Tag" />
  <Term Name="T" Type="TType" />
  <ComplexType Name="TType">
    <Property Name="P1" Type="Edm.String" />
    <Property Name="P2" Type="Edm.String">
      <Annotation Term="ApplicableTerms">
        <Collection>
          <String>HasAspect</String>
        </Collection>
      </Annotation>
    </Property>
  </ComplexType>

       Applied:

        <Annotations Target="SomeType/SomeProperty">
    <Annotation Term="T">
      <Record>
        <PropertyValue Property="P1" String="..." />
        <PropertyValue Property="P2" String="...">
          <Annotation Term="HasAspect" />
        </PropertyValue>
      </Record>
    </Annotation>
  </Annotations>

       

      Open: Which other term relations do exist and should be described?

      Show
      Add new term ApplicableTerms to the Validation vocabulary that can be used to hint at a list of additional annotations applicable in the context of the target annotated with this ApplicableTerms:   <Term Name= "ApplicableTerms" Type= "Collection(Core.QualifiedTermName)" >     <Annotation Term= "Core.Description" String= "Names of specific terms that are applicable and may be applied in the current context. This annotation does not restrict the use of other terms." />   </Term>   Example 1: Express the applicability of term Exclusive in the context of terms Minimum and Maximum: Applied: <Annotations Target= "SomeType/SomeSensorProperty" >     <Annotation Term= "Validation.Maximum" Decimal= "1.34529" >       <Annotation Term= "Validation.Exclusive" />     </Annotation>   </Annotations>  Enhanced Terms:    <Term Name= "Minimum" Type= "Edm.Decimal" Scale= "variable" AppliesTo= "Property Parameter Term" >     <Annotation Term= "Core.Description" String= "Minimum value that a property, parameter, or term can have." />     <Annotation Term= "ApplicableTerms" >       <Collection>         <String> Validation.Exclusive </String>       </Collection>     </Annotation>   </Term>     <Term Name= "Maximum" Type= "Edm.Decimal" Scale= "variable" AppliesTo= "Property Parameter Term" >     <Annotation Term= "Core.Description" String= "Maximum value that a property, parameter, or term can have." />     <Annotation Term= "ApplicableTerms" >       <Collection>         <String> Validation.Exclusive </String>       </Collection>     </Annotation>   </Term>     Example 2: Individual term properties can be enhanced with further annotations Individual parts of a term such as a individual property or a complex type can be annotated to accept further annotations. Consider a term T with a structure having two properties, one of which may be further annotated with a certain aspect. <Term Name= "HasAspect" Type= "Core.Tag" />   <Term Name= "T" Type= "TType" />   <ComplexType Name= "TType" >     <Property Name= "P1" Type= "Edm.String" />     <Property Name= "P2" Type= "Edm.String" >       <Annotation Term= "ApplicableTerms" >         <Collection>           <String> HasAspect </String>         </Collection>       </Annotation>     </Property>   </ComplexType>   Applied:   <Annotations Target= "SomeType/SomeProperty" >     <Annotation Term= "T" >       <Record>         <PropertyValue Property= "P1" String= "..." />         <PropertyValue Property= "P2" String= "..." >           <Annotation Term= "HasAspect" />         </PropertyValue>       </Record>     </Annotation>   </Annotations>   Open : Which other term relations do exist and should be described?
    • Resolution:
      Hide

      https://github.com/oasis-tcs/odata-vocabularies/pull/36

      Show
      https://github.com/oasis-tcs/odata-vocabularies/pull/36

      Description

      Terms are sometimes intended to be used only in certain contexts. Consider, for example, terms Minimum and Maximum from the Validation vocabulary. As stated in ODATA-856, they can optionally be augmented with an annotation of the Exclusive term.

      The Validation vocabulary documents this dependency in the description of term Exclusive. The descriptions of terms Minimum and Maximum, however, contain no related "forward reference" to Exclusive. Or to any other annotation, possibly from another vocabulary, that hypothetically could be applied in their context. This leads to the situation that the interface established by a term may or may not be fully described, and clients effectively do not know, which other terms may be applied in a context to add further aspects to the annotated target. In the given example, one has to read through the entire vocabulary to find out that Exclusive plays a role.

      While this can be mitigated by improving the documentation, the problem becomes more relevant, if annotations are not hand-crafted, but created by modeling tools. Such tools want to guide users and prevent misuse by reducing the overall set of annotations to those applicable in a given context. This requires a machine-readable format for expressing these dependencies. Such a formal description also reduces astonishment on client side, since it can prepare logic for all described combinations of term applications (as opposed to gradually learn the full complexity from different metadata documents)

      The list of applicable terms is open, since there are terms that may be used in any context, e.g. Core.Example. This feature enhances the existing term syntax of AppliesTo="Annotation" with optional information, which other annotations accept this term, described in the definitions of these other terms.

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              gerald.krause1 Gerald Krause
            • Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: