Skip to Content
Author's profile photo Ashish Kumar

Vocabulary-Based Annotation Support in Service Builder

So far using SAP NetWeaver Gateway you can annotate OData elements only with SAP annotations, now it is possible to enhance the metadata with custom-annotations also and this can be done with vocabulary-based annotation.  Basically vocabularies provide the ability to annotate metadata. A vocabulary file is a namespace that contains terms and these terms are used to annotate OData artifacts.

This blog will explain how you can annotate metadata with consumer specific vocabulary using SAP NetWeaver Gateway Service Builder tool.

This feature is available from SAP NetWeaver Gateway SP07.


Step-by-Step Procedure

Following are steps which you need to follow

  • Upload Vocabularies into the Vocabulary Repository
  • Create a Project
  • Import a vocabulary file
  • Add Vocabulary-Based Annotations
  • Generate Runtime Artifact
  • Registration and Activation of the Generated Service

Upload Vocabularies into the Vocabulary Repository

Start the Service Builder by using the transaction SEGW.

To upload a vocabulary file into the Vocabulary Repository in the Service Builder, proceed as follows:

  1. From menu bar choose Extras ->Vocabulary Repository . The central Vocabulary Repository opens and shows a table for displaying the vocabulary ID, version, namespace, and description. Any previously uploaded vocabulary files are displayed here, otherwise the table is empty.UploadVocabulary.png
  2. Change to edit mode and choose Append Row to add a new row to the table.
  3. Enter a unique vocabulary ID for the vocabulary file you want to upload. Version 1 is assigned automatically to the first version of
    the vocabulary file you upload.
  4. Click the Upload icon in the Upload Vocabulary Content column to navigate to the vocabulary file you want to upload. The namespace of the vocabulary file is entered automatically.
  5. Enter a description for the newly uploaded vocabulary file.
  6. Save the changes and choose Enter.

Create a Project

  1. Create a New Project by clicking on /wp-content/uploads/2014/01/4_367978.jpg

  2. Select Service with Vocabulary-Based Annotations in order to use custom annotations.

Project Type.PNG

  3. Use any of the available options(like Import ,Redefine etc) to create OData service.

  Import a vocabulary file

  • In the edit mode, right click on the Data Model, choose Import->Vocabulary in the resulting menu.
  • The Vocabulary Repository window appears.
  • Select the required vocabulary(s) and click continue.


  • In the Tree view a new folder with the name Vocabularies will be created under the Data Model
    and the vocabularies imported into this folder.

Vocabulary Folder.PNG

  • Double click on the Terms node under the Vocabularies folder to see the details of the imported annotations in the mass maintenance view.


Note: Terms can be classified into following types

    1. Core Type
    2. Type Definition
    3. Enum Type
    4. Complex Type
    5. Entity Type

Add Vocabulary-Based Annotations

Once the vocabulary definitions are added to the data model, the terms from the vocabulary definition can be used to annotate the vocabulary based services if the term applies to the respective OData artifacts.

To add annotations to artifacts for which vocabularies define applicable terms, proceed as follows:

  • Double-click the subfolder that contains the artifacts you want to annotate, for example, Entity Sets. Existing entity sets are listed in the mass maintenance view.


  • Choose the Annotations pushbutton to see the vocabulary that is valid for these entity sets. If more than one vocabulary defines applicable terms, you can select the vocabulary you want to use to annotate the entity set and, if required, toggle between the different vocabularies. If none of the imported vocabularies includes applicable terms for entity sets, for example, this pushbutton is not enabled.


  • After you have selected the vocabulary you want to use for the annotations, all entity sets are displayed in a table in the mass maintenance view with the name of the applicable vocabulary displayed as a header.
  • To create annotations for an entity set, select either the entire row to create all available annotations, or select the applicable cells for each annotation you want to create and choose the Create Annotation pushbutton. You can select more than one row and more than one cell to enable the mass maintenance of multiple entity sets and annotations, for example.
  • Annotation value can be maintained in Annotation Data table.


  • If you want to delete any annotations, select the relevant rows or cells and choose the Delete Annotation pushbutton.
  • Save your entries.

Generate Runtime Artifact

Vocabulary related code can be found in DEFINE_VOCAB_ANNOTATIONS( ) of  generated MPC class.


In SP7, commented code gets generated for annotation. Follow the instructions provided in method.

Registration and Activation of the Generated Service

Refer to section “Registration and Activation of the Generated Service” of my blog on SPI.

You will find new tags namely Annotation Targets in metadata file.


That is all for now and if need be this blog be enhanced, stay tuned 😉 Any feedback is highly appreciated 🙂

Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Om Band
      Om Band

      Very elaborate...

      Author's profile photo Former Member
      Former Member

      Great blog, thanks for the input

      Author's profile photo Wolfgang Röckelein
      Wolfgang Röckelein

      How can I add a Description/LongDescription from Org.OData.Core.V1 to an Entity or an Attribute in SEGW?

      Author's profile photo Jewgenij Moldawski
      Jewgenij Moldawski

      Do You know how in the mean time? I don't 🙂

      Do anyone have an idea?

      Author's profile photo Rahul Yadav
      Rahul Yadav

      i am not getting in my vocabularies list.. any idea?

      Author's profile photo Carlos Roggan
      Carlos Roggan

      Very instructive and easy to follow - who could ask for more? 😉

      Thanks for the great blog, Ashish!

      Author's profile photo David Fryda
      David Fryda


      First thanks.


      Do I have to implement sorting and filter methods on server side?




      Author's profile photo Yaowu Feng
      Yaowu Feng

      Can I edit the DEFINE_VOCAB_ANNOTATIONS( ) ? because when I edit annotation in SEGW, there is some annotation parameter can't find. for example, the 'Qualifier', I want to edit method DEFINE_VOCAB_ANNOTATIONS and add this parameter. but after I added this parameter, how do I RUN it and make it effective? thank you.