@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	Specifies the release state of an element which is part of an API. > ⚠️ Deprecated since 1.2.5 — prefer @API.element.releaseState, @API.element.successor, @API.element.decommissioningPlannedForYearMonth.
@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.successor	Type	Defines the name of a released successor element/association which replaces an element/association with release state #DEPRECATED or #DECOMMISSIONED.
@API.element.releaseState	Type	The annotation describes the release state of the annotated element.
@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.successor	Entity	Defines the name of a released successor entity which replaces an entity with release state #DEPRECATED or #DECOMMISSIONED.
@API.entity.releaseState	Entity	The annotation describes the release state of the annotated entity.

@API.element

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

⚠️ Deprecated since 1.2.5 — prefer @API.element.releaseState, @API.element.successor, @API.element.decommissioningPlannedForYearMonth.

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(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.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
Introduced in Version: 1.2.5

@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
Introduced in Version: 1.2.5
External Type: Element Reference

@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
# MANDATORY	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.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
Introduced in Version: 1.2.5

@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
Introduced in Version: 1.2.5

@API.entity.releaseState

The annotation describes the release state of the annotated entity.

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

Property	Type	Description
# MANDATORY	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.