Search

Supported Annotations

The OData to OpenAPI Mapping can be fine-tuned via annotations in the CSDL ($metadata) documents.

See Frequently Asked Questions for examples on how to use these annotations.

Core

Term Annotation Target OpenAPI field
Computed Property omit from Create and Update structures
DefaultNamespace Schema path templates for actions and functions without namespace prefix
Description Action, ActionImport, Function, FunctionImport summary of Operation Object
Description EntitySet, Singleton description of Tag Object
Description EntityType description of Request Body Object
Description ComplexType, EntityType, EnumerationType, Parameter, Property, TypeDefinition description of Schema Object
Description Schema, EntityContainer info.title
Example Property example of Schema Object
Immutable Property omit from Update structure
LongDescription Action, ActionImport, Function, FunctionImport description of Operation Object
LongDescription Schema, EntityContainer info.description
Permissions:Read Property omit read-only properties from Create and Update structures
SchemaVersion Schema info.version

Capabilities

Term Annotation Target OpenAPI field
CountRestrictions
 /Countable		 EntitySet $count system query option for GET operation
DeleteRestrictions
 /Deletable		 EntitySet, Singleton DELETE operation for deleting an existing entity
 /Description EntitySet, Singleton summary of Operation Object
 /LongDescription EntitySet, Singleton description of Operation Object
ExpandRestrictions
 /Expandable		 EntitySet, Singleton $expand system query option for GET operations
FilterRestrictions
 /Filterable		 EntitySet $filter system query option for GET operation
 /RequiredProperties EntitySet required properties in $filter system query option for GET operation (parameter description only)
 /RequiresFilter EntitySet $filter system query option for GET operation is required
IndexableByKey EntitySet GET, PATCH, and DELETE operations for a single entity within an entity set
InsertRestrictions
 /Insertable		 EntitySet POST operation for inserting a new entity
 /Description EntitySet summary of Operation Object
 /LongDescription EntitySet description of Operation Object
KeyAsSegmentSupported EntityContainer paths URL templates use key-as-segment style instead of parenthesis style
NavigationRestrictions
 /RestrictedProperties		 EntitySet, Singleton operations via a navigation path
  /DeleteRestrictions/... EntitySet, Singleton DELETE operation for deleting a contained entity via a navigation path
  /FilterRestrictions/... EntitySet, Singleton $filter system query option for reading related entities via a navigation path
  /InsertRestrictions/... EntitySet, Singleton POST operation for inserting a new related entity via a navigation path
  /ReadByKeyRestrictions/... EntitySet, Singleton GET operation for reading a contained entity by key via a navigation path
  /ReadRestrictions/... EntitySet, Singleton GET operation for reading related entities via a navigation path
  /SearchRestrictions/... EntitySet, Singleton $search system query option for reading related entities via a navigation path
  /SelectSupport/... EntitySet, Singleton $select system query option for reading related entities via a navigation path
  /SkipSupported EntitySet, Singleton $skip system query option for reading contained entities via a navigation path
  /SortRestrictions/... EntitySet, Singleton $orderby system query option for reading related entities via a navigation path
  /TopSupported EntitySet, Singleton $top system query option for reading contained entities via a navigation path
  /UpdateRestrictions/... EntitySet, Singleton PATCH operation for modifying a contained entity via a navigation path
ReadByKeyRestrictions
 /Readable		 EntitySet GET operation for reading a single entity by key
 /Description EntitySet summary of Operation Object
 /LongDescription EntitySet description of Operation Object
ReadRestrictions
 /Readable		 EntitySet, Singleton GET operation for reading an entity set or singleton
 /Description EntitySet, Singleton summary of Operation Object
 /LongDescription EntitySet, Singleton description of Operation Object
SearchRestrictions
 /Searchable		 EntitySet $search system query option for GET operation
SelectSupport
 /Supported		 EntitySet, Singleton $select system query option for GET operation
SkipSupported EntitySet $skip system query option for GET operation
SortRestrictions
 /NonSortableProperties		 EntitySet properties not listed in $orderby system query option for GET operation
 /Sortable EntitySet $orderby system query option for GET operation
TopSupported EntitySet $top system query option for GET operation
UpdateRestrictions
 /Updatable		 EntitySet, Singleton PATCH operation for modifying an existing entity
 /Description EntitySet, Singleton summary of Operation Object
 /LongDescription EntitySet, Singleton description of Operation Object

Validation

Term Annotation Target OpenAPI field
AllowedValues Property enum of Schema Object - list of allowed (string) values
Exclusive Property exclusiveMinimum/exclusiveMaximum of Schema Object
Maximum Property maximum of Schema Object
Minimum Property minimum of Schema Object
Pattern Property pattern of Schema Object

Authorization

Term Annotation Target OpenAPI field
Authorizations EntityContainer securitySchemes of Components Object / securityDefinitions of Swagger Object
SecuritySchemes EntityContainer security of OpenAPI / Swagger Object

Frequently Asked Questions

Examples for typical questions on how to fine-tune the generated OpenAPI descriptions.

How do I suppress GET (list and by-key) on an entity set?

To suppress both types of GET requests to an entity set, annotate it with

"@Capabilities.ReadRestrictions": {
    "Readable": false
}

How do I suppress GET (list) on an entity set?

To suppress only GET list requests to an entity set and still allow GET by-key, annotate it with

"@Capabilities.ReadRestrictions": {
    "Readable": false,
    "ReadByKeyRestrictions": {
        "Readable": true
    }
}

How do I suppress GET (by-key) on an entity set?

To suppress only GET by-key requests to an entity set and still allow GET list, annotate it with

"@Capabilities.ReadRestrictions": {
    "ReadByKeyRestrictions": {
        "Readable": false
    }
}
✉
Show/Hide Beta Features