zhongwei/gh-secondsky-sap-skills-skills-sap-fiori-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-secondsky-sap-skills-ski…/references/annotations.md
Zhongwei Li fee63d563a Initial commit
2025-11-30 08:55:20 +08:00

10 KiB
Raw Permalink Blame History

Annotations Reference

Comprehensive reference for working with annotations in SAP Fiori tools.

Table of Contents

  1. Language Server Features
  2. Supported File Types
  3. Supported Vocabularies
  4. Code Completion
  5. Micro-Snippets
  6. Diagnostics
  7. Internationalization
  8. Service Modeler
  9. Common Annotation Patterns

Language Server Features

SAP Fiori tools provides two annotation language servers:

Server File Type Scope
CDS OData Language Server .cds files CAP projects
XML Annotation Language Server annotation.xml files All projects

Capabilities

  • Code completion for annotation targets, terms, attributes, values
  • Validation against OData vocabularies and project metadata
  • Navigation to referenced annotations
  • Quick vocabulary information views
  • Internationalization (i18n) support

Supported File Types

CDS Annotation Files

Location: CAP project .cds files

annotate CatalogService.Products with @(
    UI: {
        HeaderInfo: {
            TypeName: 'Product',
            TypeNamePlural: 'Products',
            Title: { Value: name }
        },
        LineItem: [
            { Value: ID },
            { Value: name },
            { Value: price }
        ]
    }
);

XML Annotation Files

Location: webapp/annotations/*.xml

Prerequisites:

  1. OData Service with local metadata copy
  2. Path specified in manifest.json as local Uri
  3. Metadata contains <edm:Schema> definitions
  4. Single EntityContainer in metadata
  5. Valid XML file with </edmx:DataServices/Schema> nodes

Manifest Configuration:

{
  "sap.app": {
    "dataSources": {
      "mainService": {
        "uri": "/sap/opu/odata/sap/SERVICE/",
        "type": "OData",
        "settings": {
          "localUri": "localService/metadata.xml",
          "annotations": ["annotation"]
        }
      },
      "annotation": {
        "type": "ODataAnnotation",
        "uri": "annotations/annotation.xml"
      }
    }
  }
}

Supported Vocabularies

OASIS OData v4 Vocabularies

Vocabulary Namespace Description
Core Org.OData.Core.V1 Core vocabulary terms
Capabilities Org.OData.Capabilities.V1 Service capabilities
Aggregation Org.OData.Aggregation.V1 Aggregation support
Authorization Org.OData.Authorization.V1 Authorization schemes
JSON Org.OData.JSON.V1 JSON-related terms
Measures Org.OData.Measures.V1 Units of measure
Repeatability Org.OData.Repeatability.V1 Request repeatability
Temporal Org.OData.Temporal.V1 Temporal data
Validation Org.OData.Validation.V1 Data validation

SAP OData Vocabularies

Vocabulary Namespace Description
Analytics com.sap.vocabularies.Analytics.v1 Analytical annotations
CodeList com.sap.vocabularies.CodeList.v1 Code list definitions
Common com.sap.vocabularies.Common.v1 Common terms
Communication com.sap.vocabularies.Communication.v1 Contact information
DataIntegration com.sap.vocabularies.DataIntegration.v1 Data integration
DirectEdit com.sap.vocabularies.DirectEdit.v1 Direct editing
Graph com.sap.vocabularies.Graph.v1 Graph structures
Hierarchy com.sap.vocabularies.Hierarchy.v1 Hierarchical data
HTML5 com.sap.vocabularies.HTML5.v1 HTML5 rendering
ODM com.sap.vocabularies.ODM.v1 One Domain Model
PDF com.sap.vocabularies.PDF.v1 PDF generation
PersonalData com.sap.vocabularies.PersonalData.v1 Personal data marking
Preview com.sap.vocabularies.Preview.v1 Preview features
Session com.sap.vocabularies.Session.v1 Session handling
UI com.sap.vocabularies.UI.v1 UI annotations

Code Completion

Activation

  • Windows: Ctrl + Space
  • macOS: Cmd + Space

Context-Aware Suggestions

Code completion provides suggestions based on:

  • Project metadata (entities, properties, associations)
  • OData vocabulary definitions
  • Current cursor context

Path Navigation

Use / character to:

  1. Accept current segment selection
  2. Trigger completion for next segment
  3. Navigate multi-segment annotation paths

Supported Contexts

  • Annotation targets
  • Terms and term values
  • Attributes and attribute values
  • Record properties
  • Path expressions

Micro-Snippets

Pre-defined code blocks for rapid annotation development.

Available Snippets

Snippet Type Description
Annotation Target <Annotations Target=""></Annotations>
Terms Complete term structures
Records Record with properties
Property Values Property value templates

Record Snippet Types

  1. Minimal Version: Only mandatory properties (nullable=false)
  2. Complete Version: All available properties

Usage Example

Within <Schema> tags:

  1. Trigger code completion
  2. Select annotation target snippet
  3. Cursor positions inside quotes for immediate target selection

Diagnostics

Validation Scope

The language server validates:

  • Annotation syntax
  • Vocabulary compliance
  • Metadata references
  • Property types and values

Message Types

Type Severity Description
Error High Must fix before deployment
Warning Medium Potential issues
Info Low Informational messages

Accessing Diagnostics

  1. Hover: Mouse over highlighted sections
  2. Problems Panel: View > Problems (all issues)

Quick Fixes

Light bulb icon provides automatic fixes:

  • Missing required properties
  • Type mismatches
  • Value corrections

Limitations

Not Supported:

  • Annotations embedded in metadata
  • Dynamic expressions
  • Backend annotation file modifications (local copies only)

Internationalization

Configuration

Non-CAP Projects:

// webapp/manifest.json
{
  "sap.ui5": {
    "models": {
      "i18n": {
        "type": "sap.ui.model.resource.ResourceModel",
        "settings": {
          "bundleName": "project.i18n.i18n"
        }
      }
    }
  }
}

CAP Projects:

// .cdsrc.json or package.json
{
  "i18n": {
    "folders": ["_i18n", "i18n", "assets/i18n"]
  }
}

Key Naming Conventions

Project Type Format Example
Non-CAP camelCase productTitle
CAP PascalCase ProductTitle

i18n Scenarios

  1. Non-internationalized labels: Convert to i18n key references
  2. Missing i18n keys: Auto-generate with matching values
  3. Duplicate text: Link to existing i18n entries

Mass i18n Generation

Bulk externalization of multiple UI texts:

  1. Access via Page Editor or annotation file
  2. Select multiple translatable strings
  3. Generate keys in batch operation

Best Practice

Handle i18n near project completion to minimize unused entries and reduce localization costs.

Service Modeler

Purpose

Visualize OData service metadata and annotations for exploration and overriding.

Launching

  • Command Palette: Fiori: Open Service Modeler
  • Context Menu: Right-click folder > "Override Annotations"
  • Editor: Click icon when metadata.xml is open

Features

Annotation Display:

  • View backend and local annotation files
  • Local annotations override backend annotations
  • Search annotations by term or target

Source Navigation:

  • "Show in Source" icon opens original file
  • Highlighting for context

Editing Annotations

Backend annotations cannot be modified directly. Local annotations:

  • Location: /webapp/annotations/<filename>.xml
  • Edit via XML Code Editor
  • Delete using Service Modeler delete icon

Override Priority

Local annotations win over backend annotations when:

  • Same annotation term
  • Same qualifier
  • Same target

Common Annotation Patterns

List Report Line Item

<Annotations Target="Namespace.EntityType">
    <Annotation Term="UI.LineItem">
        <Collection>
            <Record Type="UI.DataField">
                <PropertyValue Property="Value" Path="PropertyName"/>
                <PropertyValue Property="Label" String="Column Label"/>
            </Record>
        </Collection>
    </Annotation>
</Annotations>

Selection Fields (Filter Bar)

<Annotation Term="UI.SelectionFields">
    <Collection>
        <PropertyPath>Property1</PropertyPath>
        <PropertyPath>Property2</PropertyPath>
    </Collection>
</Annotation>

Header Info

<Annotation Term="UI.HeaderInfo">
    <Record Type="UI.HeaderInfoType">
        <PropertyValue Property="TypeName" String="Entity"/>
        <PropertyValue Property="TypeNamePlural" String="Entities"/>
        <PropertyValue Property="Title">
            <Record Type="UI.DataField">
                <PropertyValue Property="Value" Path="Name"/>
            </Record>
        </PropertyValue>
    </Record>
</Annotation>

Object Page Facets

<Annotation Term="UI.Facets">
    <Collection>
        <Record Type="UI.ReferenceFacet">
            <PropertyValue Property="Label" String="General"/>
            <PropertyValue Property="ID" String="GeneralFacet"/>
            <PropertyValue Property="Target" AnnotationPath="@UI.FieldGroup#General"/>
        </Record>
    </Collection>
</Annotation>

Field Group

<Annotation Term="UI.FieldGroup" Qualifier="General">
    <Record Type="UI.FieldGroupType">
        <PropertyValue Property="Data">
            <Collection>
                <Record Type="UI.DataField">
                    <PropertyValue Property="Value" Path="Property1"/>
                </Record>
            </Collection>
        </PropertyValue>
    </Record>
</Annotation>

Documentation Source

GitHub: https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs/Developing-an-Application

Key files:

  • maintaining-annotations-with-language-server-6fc93f8.md
  • code-completion-dd4fc3b.md
  • micro-snippets-addf811.md
  • diagnostics-1fd8f54.md
  • internationalization-i18n-eb427f2.md
  • visualizing-annotations-with-service-modeler-58784b5.md
  • working-with-annotations-55bfb91.md
  • overriding-annotations-2f1bb9c.md
Reference in New Issue View Git Blame Copy Permalink