@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.decommissioningPlannedForYearMonth	Type	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	Type	The annotation describes the release state of the annotated element.
@API.element.successor	Type	Defines the name of a released successor element/association which replaces an element/association with release state #DEPRECATED or #DECOMMISSIONED.
@API.entity.decommissioningPlannedForYearMonth	Entity	The annotation describes the planned decommissioning date of the annotated entity. Use ISO format for YearMonth: YYYY-MM (e.g. 2024-08)
@API.entity.releaseState	Entity	The annotation describes the release state of the annotated entity.
@API.entity.successor	Entity	Defines the name of a released successor entity which replaces an entity with release state #DEPRECATED or #DECOMMISSIONED.

@API.element.decommissioningPlannedForYearMonth

The annotation describes the planned decommissioning date of the annotated element. Use ISO format for YearMonth: YYYY-MM (e.g. 2024-08)

Scope: Type
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
Type: string

@API.element.releaseState

The annotation describes the release state of the annotated element.

Scope: Type
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
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.

@API.element.successor

Defines the name of a released successor element/association which replaces an element/association with release state #DEPRECATED or #DECOMMISSIONED.

Scope: Type
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
External Type: Element Reference

@API.entity.decommissioningPlannedForYearMonth

The annotation describes the planned decommissioning date of the annotated entity. Use ISO format for YearMonth: YYYY-MM (e.g. 2024-08)

Scope: Entity
Extending: EntityDefinition
Type: string

@API.entity.releaseState

The annotation describes the release state of the annotated entity.

Scope: Entity
Extending: EntityDefinition
Type: Object(#)

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

@API.entity.successor

Defines the name of a released successor entity which replaces an entity with release state #DEPRECATED or #DECOMMISSIONED.

Scope: Entity
Extending: EntityDefinition
Type: string