@sap/cds-compiler 4.3.2 → 4.4.2

package/lib/edm/annotations/genericTranslation.js

@@ -5,166 +5,11 @@ const edmUtils = require('../edmUtils.js');
 const oDataDictionary = require('../../gen/Dictionary.json');
 const preprocessAnnotations = require('./preprocessAnnotations.js');
 const { forEachDefinition } = require('../../model/csnUtils');
-const { forEach } = require('../../utils/objectUtils');
 const { isBetaEnabled, setProp } = require('../../base/model.js');
+const { xpr2edmJson, getEdmJsonHandler } = require('./edmJson.js');
+const { vocabularyDefinitions } = require('./vocabularyDefinitions.js');
+const { EdmPathTypeMap } = require('../EdmPrimitiveTypeDefinitions.js');
 
-/*
-   OASIS: https://github.com/oasis-tcs/odata-vocabularies/tree/master/vocabularies
-   Aggregation (published)
-   Authorization (published)
-   Capabilities (published)
-   Core (published)
-   JSON (published)
-   Measures (published)
-   Repeatability (published)
-   Temporal (published)
-   Validation (published)
-
-   SAP: https://github.com/SAP/odata-vocabularies/tree/master/vocabularies
-   Analytics (published)
-   CodeList (published)
-   Common (published)
-   Communication (published)
-   DataIntegration (published)
-   Graph (published, experimental)
-   Hierarchy (published, experimental)
-   HTML5 (published, experimental)
-   ODM (published, experimental)
-   Offline (experimental)
-   PDF (published)
-   PersonalData (published)
-   Session (published)
-   UI (published)
-*/
-
-const vocabularyDefinitions = {
-  Aggregation: {
-    ref: { Uri: 'https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.xml' },
-    inc: { Alias: 'Aggregation', Namespace: 'Org.OData.Aggregation.V1' },
-    int: { filename: 'Aggregation.xml' },
-  },
-  Analytics: {
-    ref: { Uri: 'https://sap.github.io/odata-vocabularies/vocabularies/Analytics.xml' },
-    inc: { Alias: 'Analytics', Namespace: 'com.sap.vocabularies.Analytics.v1' },
-    int: { filename: 'Analytics.xml' },
-  },
-  Authorization: {
-    ref: { Uri: 'https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Authorization.V1.xml' },
-    inc: { Alias: 'Authorization', Namespace: 'Org.OData.Authorization.V1' },
-    int: { filename: 'Authorization.xml' },
-  },
-  Capabilities: {
-    ref: { Uri: 'https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Capabilities.V1.xml' },
-    inc: { Alias: 'Capabilities', Namespace: 'Org.OData.Capabilities.V1' },
-    int: { filename: 'Capabilities.xml' },
-  },
-  CodeList: {
-    ref: { Uri: 'https://sap.github.io/odata-vocabularies/vocabularies/CodeList.xml' },
-    inc: { Alias: 'CodeList', Namespace: 'com.sap.vocabularies.CodeList.v1' },
-    int: { filename: 'CodeList.xml' },
-  },
-  Common: {
-    ref: { Uri: 'https://sap.github.io/odata-vocabularies/vocabularies/Common.xml' },
-    inc: { Alias: 'Common', Namespace: 'com.sap.vocabularies.Common.v1' },
-    int: { filename: 'Common.xml' },
-  },
-  Communication: {
-    ref: { Uri: 'https://sap.github.io/odata-vocabularies/vocabularies/Communication.xml' },
-    inc: { Alias: 'Communication', Namespace: 'com.sap.vocabularies.Communication.v1' },
-    int: { filename: 'Communication.xml' },
-  },
-  Core: {
-    ref: { Uri: 'https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.xml' },
-    inc: { Alias: 'Core', Namespace: 'Org.OData.Core.V1' },
-    int: { filename: 'Core.xml' },
-  },
-  DataIntegration: {
-    ref: { Uri: 'https://sap.github.io/odata-vocabularies/vocabularies/DataIntegration.xml' },
-    inc: { Alias: 'DataIntegration', Namespace: 'com.sap.vocabularies.DataIntegration.v1' },
-    int: { filename: 'DataIntegration.xml' },
-  },
-  Graph: {
-    ref: { Uri: 'https://sap.github.io/odata-vocabularies/vocabularies/Graph.xml' },
-    inc: { Alias: 'Graph', Namespace: 'com.sap.vocabularies.Graph.v1' },
-    int: { filename: 'Graph.xml' },
-  },
-  Hierarchy: {
-    ref: { Uri: 'https://sap.github.io/odata-vocabularies/vocabularies/Hierarchy.xml' },
-    inc: { Alias: 'Hierarchy', Namespace: 'com.sap.vocabularies.Hierarchy.v1' },
-    int: { filename: 'Hierarchy.xml' },
-  },
-  HTML5: {
-    ref: { Uri: 'https://sap.github.io/odata-vocabularies/vocabularies/HTML5.xml' },
-    inc: { Alias: 'HTML5', Namespace: 'com.sap.vocabularies.HTML5.v1' },
-    int: { filename: 'HTML5.xml' },
-  },
-  JSON: {
-    ref: { Uri: 'https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.JSON.V1.xml' },
-    inc: { Alias: 'JSON', Namespace: 'Org.OData.JSON.V1' },
-    int: { filename: 'JSON.xml' },
-  },
-  Measures: {
-    ref: { Uri: 'https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Measures.V1.xml' },
-    inc: { Alias: 'Measures', Namespace: 'Org.OData.Measures.V1' },
-    int: { filename: 'Measures.xml' },
-  },
-  ODM: {
-    ref: { Uri: 'https://sap.github.io/odata-vocabularies/vocabularies/ODM.xml' },
-    inc: { Alias: 'ODM', Namespace: 'com.sap.vocabularies.ODM.v1' },
-    int: { filename: 'ODM.xml' },
-  },
-  Offline: {
-    ref: { Uri: 'https://sap.github.io/odata-vocabularies/vocabularies/Offline.xml' },
-    inc: { Alias: 'Offline', Namespace: 'com.sap.vocabularies.Offline.v1' },
-    int: { filename: 'Offline.xml' },
-  },
-  PDF: {
-    ref: { Uri: 'https://sap.github.io/odata-vocabularies/vocabularies/PDF.xml' },
-    inc: { Alias: 'PDF', Namespace: 'com.sap.vocabularies.PDF.v1' },
-    int: { filename: 'PDF.xml' },
-  },
-  PersonalData: {
-    ref: { Uri: 'https://sap.github.io/odata-vocabularies/vocabularies/PersonalData.xml' },
-    inc: { Alias: 'PersonalData', Namespace: 'com.sap.vocabularies.PersonalData.v1' },
-    int: { filename: 'PersonalData.xml' },
-  },
-  Repeatability: {
-    ref: { Uri: 'https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Repeatability.V1.xml' },
-    inc: { Alias: 'Repeatability', Namespace: 'Org.OData.Repeatability.V1' },
-    int: { filename: 'Repeatability.xml' },
-  },
-  Session: {
-    ref: { Uri: 'https://sap.github.io/odata-vocabularies/vocabularies/Session.xml' },
-    inc: { Alias: 'Session', Namespace: 'com.sap.vocabularies.Session.v1' },
-    int: { filename: 'Session.xml' },
-  },
-  UI: {
-    ref: { Uri: 'https://sap.github.io/odata-vocabularies/vocabularies/UI.xml' },
-    inc: { Alias: 'UI', Namespace: 'com.sap.vocabularies.UI.v1' },
-    int: { filename: 'UI.xml' },
-  },
-  Validation: {
-    ref: { Uri: 'https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Validation.V1.xml' },
-    inc: { Alias: 'Validation', Namespace: 'Org.OData.Validation.V1' },
-    int: { filename: 'Validation.xml' },
-  },
-  /* unvalidated vocabularies below here:
-     A vocabulary is unvalidated if it doesn't have an int.filename property as this indicates that
-     the vocabulary is added to the validation dictionary
-     Example:
-  'Org.Snafu.V1': {
-    'ref': { Uri: 'https://snafu.org/snafu.xml' },
-    'inc': { Alias: 'Snafu', Namespace: 'Org.Snafu.V1' },
-  },
-  */
-};
-
-/* create inverted voc definitions list to allow addressing full qualified vocabularies
-Object.entries(vocabularyDefinitions).forEach(([n, v]) => {
-  if(!vocabularyDefinitions[v.inc.Namespace])
-    vocabularyDefinitions[v.inc.Namespace] = vocabularyDefinitions[n];
-});
-*/
 /** ************************************************************************************************
  * csn2annotationEdm
  *
@@ -174,20 +19,20 @@ Object.entries(vocabularyDefinitions).forEach(([n, v]) => {
  */
 function csn2annotationEdm( reqDefs, csnVocabularies, serviceName,
                             Edm = undefined, options = undefined, messageFunctions = undefined, mergedVocDefs = vocabularyDefinitions ) {
-  // global variable where we store all the generated annotations
-  const gAnnosArray = [];
+  const gAnnosArray = []; // global variable where we store all the generated annotations
+  const usedExperimentalTerms = {}; // take note of all experimental annos that have been used
+  const usedDeprecatedTerms = {}; // take note of all deprecated annos that have been used
 
+  const { v } = options;
   const { message } = messageFunctions;
-
+  const { handleEdmJson } = getEdmJsonHandler(Edm, options, messageFunctions, handleTerm);
   const [ userDefinedTermDict, allKnownVocabularies ] = createUserDefinedTermDictionary();
 
+
   allKnownVocabularies.push(...Object.keys(mergedVocDefs));
   allKnownVocabularies.sort((a, b) => b.length - a.length);
   const whatsMyTermNamespace = anno => allKnownVocabularies.reduce((rc, ns) => (!rc && anno && anno.startsWith(`@${ns}.`) ? ns : rc), undefined);
 
-  // Static dynamic expression dictionary, loaded with Edm creators
-  const [ dynamicExpressions, dynamicExpressionNames ] = initEdmJson();
-
   // annotation preprocessing
   preprocessAnnotations.preprocessAnnotations(reqDefs, serviceName, options);
 
@@ -209,63 +54,6 @@ function csn2annotationEdm( reqDefs, csnVocabularies, serviceName,
             { name: serviceName, '#': 'service' } );
   }
 
-  // provide functions for dictionary lookup
-  //   use closure to avoid making "dict" and "experimental" global variables
-  const { getDictTerm, getDictType } = (function createDictGetters() {
-    const dict = options.dictReplacement || oDataDictionary; // tests can set different dictionary via options
-    const experimental = {}; // take note of all experimental annos that have been used
-    const deprecated = {}; // take note of all deprecated annos that have been used
-
-    return {
-      // called to look-up a term in the dictionary
-      //   in addition: - note usage of the respective vocabulary
-      //                - issue a warning if the term is flagged as "experimental"
-      getDictTerm(termName, msg) {
-        const dictTerm = (dict.terms[termName] ||
-          userDefinedTermDict.terms[`${serviceName}.${termName}`] ||
-          userDefinedTermDict.terms[termName]);
-        // register vocabulary usage if possible
-        const vocName = termName.slice(0, termName.indexOf('.'));
-        const myVocDef = mergedVocDefs[vocName];
-        if (myVocDef && !myVocDef.$ignore)
-          myVocDef.used = true;
-        else if (dictTerm?.$myServiceRoot &&
-          userDefinedTermDict.xrefs[dictTerm?.$myServiceRoot])
-          userDefinedTermDict.xrefs[dictTerm.$myServiceRoot].used = true;
-        if (dictTerm) {
-          // issue message for usage of experimental Terms, but only once per Term
-          if (dictTerm.$experimental && !experimental[termName]) {
-            message('odata-anno-dict', msg.location, { anno: msg.anno(), '#': 'experimental' });
-            experimental[termName] = true;
-          }
-          if (dictTerm.$deprecated && !deprecated[termName]) {
-            message('odata-anno-def', msg.location,
-                    { anno: msg.anno(), depr: dictTerm.$deprecationText, '#': 'deprecated' });
-            deprecated[termName] = true;
-          }
-        }
-        return dictTerm;
-      },
-      // called to look-up a type in the dictionary
-      //   in addition, note usage of the respective vocabulary
-      getDictType(typeName) {
-        const dictType = (dict.types[typeName] ||
-          userDefinedTermDict.types[`${serviceName}.${typeName}`] ||
-          userDefinedTermDict.types[typeName]);
-        if (dictType) {
-          // register usage of vocabulary
-          const vocName = typeName.slice(0, typeName.indexOf('.'));
-          const myVocDef = mergedVocDefs[vocName];
-          if (myVocDef && !myVocDef.$ignore)
-            myVocDef.used = true;
-        }
-        return dictType;
-      },
-    };
-  }());
-
-  const { v } = options;
-
   // Copy annotations from origin to parameter entity if it's
   // qualified with #$parameters or if its applicable to an EntitySet or Singleton
   forEachDefinition(reqDefs, (object) => {
@@ -514,6 +302,12 @@ function csn2annotationEdm( reqDefs, csnVocabularies, serviceName,
       if (knownAnnos.length === 0)
         return;
     }
+    if (isBetaEnabled(options, 'annotationExpressions')) {
+      knownAnnos.forEach((knownAnno) => {
+        if (knownAnno.search(/\.\$edmJson\./g) < 0)
+          carrier[knownAnno] = xpr2edmJson(carrier, knownAnno, location, options, messageFunctions);
+      });
+    }
 
     const prefixTree = createPrefixTree();
 
@@ -803,13 +597,18 @@ function csn2annotationEdm( reqDefs, csnVocabularies, serviceName,
             steps.splice(i, steps.length - i, steps.slice(i).join('.'));
         }
         if (innerAnnotation) {
-        // A voc annotation has two steps (Namespace+Name),
-        // any further steps need to be rendered separately
-          const innerAnnoSteps = innerAnnotation.split('.');
-          const tailSteps = innerAnnoSteps.splice(2, innerAnnoSteps.length - 2);
-          // prepend annotation prefix (path) to tail steps
-          tailSteps.splice(0, 0, `@${innerAnnoSteps.join('.')}`);
-          steps.push(...tailSteps);
+          // A voc annotation has two steps (Namespace+Name),
+          // any further steps need to be rendered separately
+          if (innerAnnotation.startsWith('sap.')) {
+            steps.push(`@${innerAnnotation}`);
+          }
+          else {
+            const innerAnnoSteps = innerAnnotation.split('.');
+            const tailSteps = innerAnnoSteps.splice(2, innerAnnoSteps.length - 2);
+            // prepend annotation prefix (path) to tail steps
+            tailSteps.splice(0, 0, `@${innerAnnoSteps.join('.')}`);
+            steps.push(...tailSteps);
+          }
         }
         mergePathStepsIntoPrefixTree(prefixTreeP, steps, 0);
       }
@@ -1142,8 +941,12 @@ function csn2annotationEdm( reqDefs, csnVocabularies, serviceName,
   // note: expr can also be provided if an enum/complex type/collection is expected
   function handleExpression( value, dTypeName ) {
     let typeName = 'Path';
-    if ( [ 'Edm.AnnotationPath', 'Edm.ModelElementPath', 'Edm.NavigationPropertyPath', 'Edm.PropertyPath', 'Edm.Path' ].includes(dTypeName) )
-      typeName = dTypeName.split('.')[1];
+    if ( EdmPathTypeMap[dTypeName] ) {
+      if (dTypeName === 'Edm.AnyPropertyPath')
+        typeName = 'PropertyPath';
+      else
+        typeName = dTypeName.split('.')[1];
+    }
 
     if (value) {
       // replace all occurrences of '.' by '/' up to first '@'
@@ -1496,142 +1299,6 @@ function csn2annotationEdm( reqDefs, csnVocabularies, serviceName,
   }
 
 
-  // Not everything that can occur in OData annotations can be expressed with
-  // corresponding constructs in cds annotations. For these special cases
-  // we have a kind of "inline assembler" mode, i.e. you can in cds provide
-  // as annotation value a json snippet that looks like the final edm-json.
-  // See example in test/odataAnnotations/smallTests/edmJson_noReverse_ok
-  // and test3/ODataBackends/DynExpr
-
-  function handleEdmJson( obj, msg, exprDef = undefined ) {
-    let edmNode;
-    if (obj == null)
-      return edmNode;
-
-    const dynExprs = edmUtils.intersect(dynamicExpressionNames, Object.keys(obj));
-
-    if (dynExprs.length > 1) {
-      message('odata-anno-value', msg.location,
-              { anno: msg.anno(), rawvalues: dynExprs, '#': 'multexpr' });
-      return edmNode;
-    }
-
-    if (dynExprs.length === 0) {
-      if (typeof obj === 'object' && !Array.isArray(obj) && Object.keys(obj).length === 1) {
-        const k = Object.keys(obj)[0];
-        const val = obj[k];
-        edmNode = new Edm.ValueThing(v, k[0] === '$' ? k.slice(1) : k, val );
-        edmNode.setJSON( { [edmNode.kind]: val } );
-      }
-      // This thing is either a record or a collection or a literal
-      else if (Array.isArray(obj)) {
-        // EDM JSON doesn't mention annotations on collections
-        edmNode = new Edm.Collection(v);
-        obj.forEach(o => edmNode.append(handleEdmJson(o, msg)));
-      }
-      else if (typeof obj === 'object') {
-        edmNode = new Edm.Record(v);
-        const annos = Object.create(null);
-        const props = Object.create(null);
-        Object.entries(obj).forEach(([ k, val ]) => {
-          if (k === '@type') {
-            edmNode.setJSON({ Type: val });
-            // try to shorten full qualified type URI to short type name
-            const parts = val.split('#');
-            const shortTypeName = parts[parts.length - 1];
-            edmNode.setXml({ Type: shortTypeName });
-          }
-          else {
-            let child;
-            const [ head, tail ] = k.split('@');
-            if (tail) {
-              child = handleTerm(tail, val, msg);
-            }
-            else {
-              child = new Edm.PropertyValue(v, head);
-              child.append(handleEdmJson(val, msg));
-            }
-            if (child) {
-              if (tail && head.length) {
-                if (!annos[head])
-                  annos[head] = [ child ];
-                else
-                  annos[head].push(child);
-              }
-              else {
-                if (head.length)
-                  props[head] = child;
-                edmNode.append(child);
-              }
-            }
-          }
-        });
-        // add collected annotations to record members
-        Object.entries(annos).forEach(([ n, val ]) => {
-          if (props[n])
-            props[n].prepend(...val);
-        });
-      }
-      else { // literal
-        edmNode = new Edm.ValueThing(v,
-                                     exprDef && exprDef.valueThingName || getXmlTypeName(obj), obj);
-        // typename for static expression rendering
-        edmNode.setJSON( { [getJsonTypeName(obj)]: obj } );
-      }
-    }
-    else {
-      // name of special property determines element kind
-      exprDef = dynamicExpressions[dynExprs[0]];
-      edmNode = exprDef.create(obj);
-
-      // iterate over each obj.property and translate expression into EDM
-      forEach(obj, (name, val) => {
-        if (exprDef) {
-          if (exprDef.anno && name[0] === '@') {
-            edmNode.append(handleTerm(name.slice(1), val, msg));
-          }
-          else if (exprDef.attr && exprDef.attr.includes(name)) {
-            if (name[0] === '$')
-              edmNode.setEdmAttribute(name.slice(1), val);
-          }
-          else if (exprDef.jsonAttr && exprDef.jsonAttr.includes(name)) {
-            if (name[0] === '$')
-              edmNode.setJSON( { [name.slice(1)]: val });
-          }
-          else if (exprDef.children) {
-            if (Array.isArray(val)) {
-              val.forEach((a) => {
-                edmNode.append(handleEdmJson(a, msg, exprDef));
-              });
-            }
-            else {
-              edmNode.append(handleEdmJson(val, msg, exprDef));
-            }
-          }
-        }
-      });
-    }
-    return edmNode;
-
-    function getXmlTypeName( val ) {
-      let typeName = 'String';
-      if (typeof val === 'boolean')
-        typeName = 'Bool';
-
-      else if (typeof val === 'number')
-        typeName = Number.isInteger(val) ? 'Int' : 'Decimal';
-
-      return typeName;
-    }
-
-    function getJsonTypeName( val ) {
-      const typeName = getXmlTypeName(val);
-      if (typeName === 'Int')
-        return 'Edm.Int32';
-      return `Edm.${typeName}`;
-    }
-  }
-
   /**
    * translate vocabulary definitions into a userDefinedTermDict
    * with the same structure as the global jsonDictionary that
@@ -1763,65 +1430,57 @@ function csn2annotationEdm( reqDefs, csnVocabularies, serviceName,
     }
   }
 
-  function initEdmJson() {
-    // Static dynamic expression dictionary, loaded with Edm creators
-    const dynamicExpressionsP = {
-      $And: { create: () => new Edm.Expr(v, 'And'), anno: true },
-      $Or: { create: () => new Edm.Expr(v, 'Or'), anno: true },
-      $Not: { create: () => new Edm.Expr(v, 'Not'), anno: true },
-      $Eq: { create: () => new Edm.Expr(v, 'Eq'), anno: true },
-      $Ne: { create: () => new Edm.Expr(v, 'Ne'), anno: true },
-      $Gt: { create: () => new Edm.Expr(v, 'Gt'), anno: true },
-      $Ge: { create: () => new Edm.Expr(v, 'Ge'), anno: true },
-      $Lt: { create: () => new Edm.Expr(v, 'Lt'), anno: true },
-      $Le: { create: () => new Edm.Expr(v, 'Le'), anno: true },
-      // valueThingName: 'EnumMember' Implicit Cast Rule String => Primitive Type is OK
-      $Has: { create: () => new Edm.Expr(v, 'Has'), anno: true },
-      $In: { create: () => new Edm.Expr(v, 'In'), anno: true },
-      $Add: { create: () => new Edm.Expr(v, 'Add'), anno: true },
-      $Sub: { create: () => new Edm.Expr(v, 'Sub'), anno: true },
-      $Neg: { create: () => new Edm.Expr(v, 'Neg'), anno: true },
-      $Mul: { create: () => new Edm.Expr(v, 'Mul'), anno: true },
-      $Div: { create: () => new Edm.Expr(v, 'Div'), anno: true },
-      $DivBy: { create: () => new Edm.Expr(v, 'DivBy'), anno: true },
-      $Mod: { create: () => new Edm.Expr(v, 'Mod'), anno: true },
-      $Apply: {
-        create: () => new Edm.Apply(v),
-        attr: [ '$Function' ],
-        anno: true,
-      },
-      $Cast: {
-        create: () => new Edm.Cast(v),
-        attr: [ '$Type' ],
-        jsonAttr: [ '$Collection' ],
-        anno: true,
-      },
-      $IsOf: {
-        create: () => new Edm.IsOf(v),
-        attr: [ '$Type' ],
-        anno: true,
-      },
-      $If: { create: () => new Edm.If(v), anno: true },
-      $LabeledElement: {
-        create: () => new Edm.LabeledElement(v),
-        attr: [ '$Name' ],
-        anno: true,
-      },
-      $LabeledElementReference: {
-        create: obj => new Edm.LabeledElementReference(v, obj.$LabeledElementReference),
-      },
-      $UrlRef: { create: () => new Edm.UrlRef(v), anno: true },
-      $Null: { create: () => new Edm.Null(v), anno: true, children: false },
-    };
+  //-------------------------------------------------------------------------------------------------
+  // Dictionary access
+  //-------------------------------------------------------------------------------------------------
 
-    Object.entries(dynamicExpressionsP).forEach(([ k, dv ]) => {
-      if (!dv.name)
-        dv.name = k.slice(1);
-      if (dv.children === undefined)
-        dv.children = true;
-    });
-    return [ dynamicExpressionsP, Object.keys(dynamicExpressionsP) ];
+  // called to look-up a term in the dictionary
+  //   in addition: - note usage of the respective vocabulary
+  //                - issue a warning if the term is flagged as "experimental"
+  function getDictTerm( termName, msg ) {
+    const dict = options.dictReplacement || oDataDictionary; // tests can set different dictionary via options
+    const dictTerm = (dict.terms[termName] ||
+          userDefinedTermDict.terms[`${serviceName}.${termName}`] ||
+          userDefinedTermDict.terms[termName]);
+    // register vocabulary usage if possible
+    const vocName = termName.slice(0, termName.indexOf('.'));
+    const myVocDef = mergedVocDefs[vocName];
+    if (myVocDef && !myVocDef.$ignore)
+      myVocDef.used = true;
+    else if (dictTerm?.$myServiceRoot &&
+          userDefinedTermDict.xrefs[dictTerm?.$myServiceRoot])
+      userDefinedTermDict.xrefs[dictTerm.$myServiceRoot].used = true;
+    if (dictTerm) {
+      // issue message for usage of experimental Terms, but only once per Term
+      if (dictTerm.$experimental && !usedExperimentalTerms[termName]) {
+        message('odata-anno-dict', msg.location, { anno: msg.anno(), '#': 'experimental' });
+        usedExperimentalTerms[termName] = true;
+      }
+      if (dictTerm.$deprecated && !usedDeprecatedTerms[termName]) {
+        message('odata-anno-def', msg.location,
+                { anno: msg.anno(), depr: dictTerm.$deprecationText, '#': 'deprecated' });
+        usedDeprecatedTerms[termName] = true;
+      }
+    }
+    return dictTerm;
   }
+  // called to look-up a type in the dictionary
+  //   in addition, note usage of the respective vocabulary
+  function getDictType( typeName ) {
+    const dict = options.dictReplacement || oDataDictionary; // tests can set different dictionary via options
+    const dictType = (dict.types[typeName] ||
+          userDefinedTermDict.types[`${serviceName}.${typeName}`] ||
+          userDefinedTermDict.types[typeName]);
+    if (dictType) {
+      // register usage of vocabulary
+      const vocName = typeName.slice(0, typeName.indexOf('.'));
+      const myVocDef = mergedVocDefs[vocName];
+      if (myVocDef && !myVocDef.$ignore)
+        myVocDef.used = true;
+    }
+    return dictType;
+  }
+
   //-------------------------------------------------------------------------------------------------
   //-------------------------------------------------------------------------------------------------
   //-------------------------------------------------------------------------------------------------