Annotations.md

Supported Annotations

The OData to OpenAPI Mapping can be fine-tuned via annotations in the CSDL ($metadata) XML 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
ComputedDefaultValue	Property	omit from required properties if key
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	title 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	ComplexType, EntityType, EnumerationType, Parameter, Property, TypeDefinition	description of Schema 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
DeepUpdateSupport  /Supported	EntityContainer	PATCH operations support deep update
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
/CustomHeaders	EntitySet, Singleton	custom headers
/CustomQueryOptions	EntitySet, Singleton	custom query options
/ErrorResponses	EntitySet, Singleton	error response status codes with descriptions
/FilterSegmentSupported	EntitySet	DELETE operation with /$filter segment on collection for deleting existing entities
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
/CustomHeaders	EntitySet	custom headers
/CustomQueryOptions	EntitySet	custom query options
/ErrorResponses	EntitySet	error response status codes with descriptions
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
/CustomHeaders	EntitySet	custom headers
/CustomQueryOptions	EntitySet	custom query options
/ErrorResponses	EntitySet, Singleton	error response status codes with descriptions
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
/CustomHeaders	EntitySet, Singleton	custom headers
/CustomQueryOptions	EntitySet, Singleton	custom query options
/ErrorResponses	EntitySet, Singleton	error response status codes with descriptions
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
/UpdateMethod	EntitySet, Singleton	define update method (default is PATCH)
/Description	EntitySet, Singleton	summary of Operation Object
/LongDescription	EntitySet, Singleton	description of Operation Object
/CustomHeaders	EntitySet, Singleton	custom headers
/CustomQueryOptions	EntitySet, Singleton	custom query options
/ErrorResponses	EntitySet, Singleton	error response status codes with descriptions
/FilterSegmentSupported	EntitySet	PATCH operation with /$filter segment on collection for modifying existing entities
OperationRestrictions  /CustomHeaders	Action, Function	custom headers
/CustomQueryOptions	Action, Function	custom query options
/ErrorResponses	Action, Function	error response status codes with descriptions

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

JSON

Term	Annotation Target	OpenAPI field
Schema	Property, CustomParameter	schema of property, custom header, or custom query option