@API

BETA This annotation is beta and should be reviewed for completion and correctness.

Introduction

The API annotation allows to define deviating release states for single elements or associations within released APIs.

Schema Definitions

• This is an extension vocabulary for CSN Interop Effective Document.
• The interface is available as JSON Schema: api.schema.json.

Annotations Overview

Annotation	Scope	Description
@API.element	Type, Entity	Specifies the release state of an element which is part of an API.
@API.element.releaseState	Type, Entity	The annotation describes the release state of the annotated element.

@API.element

Specifies the release state of an element which is part of an API.

Scope: Type, Entity
Extending: BooleanType, StringType, LargeStringType, IntegerType, Int16Type, Integer64Type, UInt8Type, DecimalType, DoubleType, DateType, TimeType, DateTimeType, TimestampType, UUIDType, BinaryType, LargeBinaryType, AssociationType, CompositionType, CustomType, TypeDefinition, BooleanTypeDefinition, StringTypeDefinition, LargeStringTypeDefinition, IntegerTypeDefinition, Int16TypeDefinition, Integer64TypeDefinition, UInt8TypeDefinition, DecimalTypeDefinition, DoubleTypeDefinition, DateTypeDefinition, TimeTypeDefinition, DateTimeTypeDefinition, TimestampTypeDefinition, UUIDTypeDefinition, BinaryTypeDefinition, LargeBinaryTypeDefinition, AssociationTypeDefinition, CompositionTypeDefinition, EntityDefinition
Type: Object(releaseState, successor, decommissioningPlannedForYearMonth)

Property	Type	Description
releaseState OPTIONAL	@API.element.releaseState	The annotation describes the release state of the annotated element.
successor OPTIONAL	Element Reference	Defines the name of a released successor element/association which replaces an element/association with release state #DEPRECATED or #DECOMMISSIONED.
decommissioningPlannedForYearMonth OPTIONAL	string	The annotation describes the planned decommissioning date of the annotated element. Use ISO format for YearMonth: YYYY-MM (e.g. 2024-08)

@API.element.releaseState

The annotation describes the release state of the annotated element.

Scope: Type, Entity
Extending: BooleanType, StringType, LargeStringType, IntegerType, Int16Type, Integer64Type, UInt8Type, DecimalType, DoubleType, DateType, TimeType, DateTimeType, TimestampType, UUIDType, BinaryType, LargeBinaryType, AssociationType, CompositionType, CustomType, TypeDefinition, BooleanTypeDefinition, StringTypeDefinition, LargeStringTypeDefinition, IntegerTypeDefinition, Int16TypeDefinition, Integer64TypeDefinition, UInt8TypeDefinition, DecimalTypeDefinition, DoubleTypeDefinition, DateTypeDefinition, TimeTypeDefinition, DateTimeTypeDefinition, TimestampTypeDefinition, UUIDTypeDefinition, BinaryTypeDefinition, LargeBinaryTypeDefinition, AssociationTypeDefinition, CompositionTypeDefinition, EntityDefinition
Type: Object(#)

Property	Type	Description
# OPTIONAL	string	Provide the value in { "#": "<value>" } enum notation. Allowed Values: "DEPRECATED": Formerly released element/association is not to be used anymore. At runtime, the element/association must work as before. Together with this value a successors of the element/association should be defined using annotation @API.element.successor. "DECOMMISSIONED": Formerly released element/association not to be used anymore. At runtime, the element/association returns null values. Together with this value a successors of the element/association should be defined using annotation @API.element.successor.