From caa79b52f0d32572f7215e323966e2ff7041d810 Mon Sep 17 00:00:00 2001 From: Dave Moreno Date: Mon, 11 May 2026 23:18:57 -0500 Subject: [PATCH] Add 12-month minimum deprecation cycle to @API element annotations Documents the SAP lifecycle policy requiring elements stay in DEPRECATED state for at least 12 months before DECOMMISSIONED, makes successor mandatory (with explicit justification if absent), and aligns decommissioningPlannedForYearMonth with the same 12-month constraint. Co-Authored-By: Claude Sonnet 4.6 --- spec/v1/annotations/api.yaml | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/spec/v1/annotations/api.yaml b/spec/v1/annotations/api.yaml index 559da8b..0bfd30f 100644 --- a/spec/v1/annotations/api.yaml +++ b/spec/v1/annotations/api.yaml @@ -14,12 +14,15 @@ definitions: successor: description: |- Defines the name of a released successor element/association which replaces an element/association with release state #DEPRECATED or #DECOMMISSIONED. + Providing a successor is mandatory when deprecating an element/association. + If no direct successor exists, this must be explicitly documented and justified (e.g., the business concept has been removed). x-ref-to-doc: title: Element Reference ref: "#/definitions/ElementReference" decommissioningPlannedForYearMonth: description: |- - The annotation describes the planned decommissioning date of the annotated element. Use ISO format for YearMonth: YYYY-MM (e.g. 2024-08) + The annotation describes the planned decommissioning date of the annotated element. Use ISO format for YearMonth: YYYY-MM (e.g. 2024-08). + The planned decommissioning date must be at least 12 months after the deprecation date, in alignment with SAP lifecycle policies. type: string x-extension-targets: - Type @@ -40,14 +43,19 @@ definitions: oneOf: - const: "DEPRECATED" description: |- - 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. + Formerly released element/association is no longer recommended but remains fully functional. + At runtime, the element/association must work as before and continues to deliver data. + The element/association must not be enhanced further and is not recommended for new consumers. + A successor element/association must be defined using the `successor` annotation. + If no direct successor exists, this must be explicitly documented and justified. + The element/association must remain in the DEPRECATED state for a minimum of 12 months before transitioning to DECOMMISSIONED, + in alignment with SAP lifecycle policies. - const: "DECOMMISSIONED" description: |- - Formerly released element/association not to be used anymore. + Formerly released element/association is no longer supported for productive use. 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. + A successor element/association must be defined using the `successor` annotation. + This state may only be applied after the element/association has been in the DEPRECATED state for a minimum of 12 months. x-extension-targets: - Type - Entity