[7 dev] JEAN BAPTISTE ZIADE update initial PR cf Comments in PR 3366 #3637

[PayalKhanna]

Supersedes #3637

[netlify]

✅ Deploy Preview for finos-cdm ready!

Name	Link
🔨 Latest commit	fa9bcf6
🔍 Latest deploy log	https://app.netlify.com/projects/finos-cdm/deploys/68397e1af5d52c0008d04e14
😎 Deploy Preview	https://deploy-preview-3642--finos-cdm.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[PayalKhanna]

@JBZ-Fragmos the Release notes in #3637
doesn't really explain whet is the change in the PR and reasoning behind

can you please add a proper release note as a comment in this PR

[JBZ-Fragmos]

Background

This releases enrich the description of Corporate Action, mainly used in Event model (in root path ObservationInstruction)

• by adding new optional attributes to existing type CorporateAction, among which an important one from business standpoint, based on new type AdjustmentFactor
• also by completing existing type CorporateActionTypeEnum with values that were missing in the list

What is being released ?

• a set of attributes is added to CorporateAction ; all of them have optional cardinality (0..1) :

  • recordDate date (existing type)
  • annoucementDate date (existing type)
  • informationSource InformationSource (existing type)
  • dividendObservation PriceSchedule (existing type)
  • bespokeEventDescription string (existing type)
  • adjustmentFactor AdjustmentFactor (new type) : see details below

• new type AdjustmentFactor : for specifying any additional details e.g. further descriptions depending on the particular type of Corporate Action, adjustment factor and calculations terms to resolve for calculating the adjustment factor - hencing coming with two attributes :

  • value number (existing type) : to represent the multipler value applied to the price of the underlier impacted by a Corporate Action.
  • calculation PriceAdjustmentFactorCalculationTerms (new type) : see details below

• new type PriceAdjustmentFactorCalculationTerms : to represent the input terms involved in the calculation of the adjustment factor applied to the price of the underlier impacted by a Corporate Action. All of them are optional, given that need for populating depends on the event type of the Corporate Action. Accordingly, new conditions are also added to ensure consistency in the choices that can be made :

  • some attributes are existing types number (example shareForShareRatio, shareForRightsRatio, dividendRatio) or Price (example rightsSubscriptionPrice) or string (example bespokeCalculationFormula)
  • other ones are new types to enrich description of particular event type, such as SpinOff, Merger, AccrualFactor (example of attributes for SpinOff, logic being similar for other attributes : parentCompany Security, parentPriceObservation Price, childCompany Security and childPriceObservation Price)

• as regards particular type AccrualFactor, it is notably re-using existing type StubValue as optional attribute, that is when the accrual factor is an interpolation rate ; which notably lead to an enrichment of StubValue with new optional attribute stubPeriod of type Period

• four new values are added in the list of existing type CorporateActionTypeEnum :

  • BankruptcyOrInsolvency
  • IssuerNationalization
  • Relisting
  • BespokeEvent

Review Directions

Changes can be reviewed in PR #3642

[JBZ-Fragmos]

@PayalKhanna
have drafted Release Note above, as requested

[PayalKhanna]

@JBZ-Fragmos can you add the Tittle for the Release note as well please

[JayasriR]

@JBZ-Fragmos Please find comments on release notes below. Can you please update it accordingly.

[eacunaISDA]

Hi @JBZ-Fragmos thanks for submitting your PR!
Please update the title to specify context / model affected. For example "Event Model -....".
The "Background" section should provide rationale as to WHY we need this update , the problem statement; and the following section "What is being released?" would then elaborate on the HOW this is being addressed. These release notes seem to have the second section divided up across these two sections.
For more detail on content please also review https://cdm.finos.org/docs/dev-guidelines#content-of-release-notes
Thank you

[JBZ-Fragmos]

done in accordance with your request --> see last 'Comment' below

if not yet as expected, in order to avoid to many back&forth, do not hesitate to propose directly in the text some modifications, and I will review your proposals

[eacunaISDA]

Hi @JBZ-Fragmos I don't see an updated title as in request above "Please update the title to specify context / model affected. For example "Event Model -....". Please advise

[JBZ-Fragmos]

done !

[JBZ-Fragmos]

sorry but I do not understand...
what do you want me to say more in 'background' ? what is missing ?

please see below : it is clarified "why" we want to do an "enrichement" ; by definition, an enrichement is made to complete "missing information"

what could i add more than what is highlighted below for explaining why we want to enrich a component ?

in my view, this Release Note is exhaustive, kindly re-check and validate it please

[JBZ-Fragmos]

Event Model - Enrichment of Corporate Action

Background

This releases enrich the description of Corporate Action, mainly used in Event model (in root path ObservationInstruction), with new attributes to represent some information that has been missing so far to ensure exhaustive description of such event from business standpoint.

What is being released ?

• four new values are added in the list of existing type CorporateActionTypeEnum :

  • BankruptcyOrInsolvency
  • IssuerNationalization
  • Relisting
  • BespokeEvent

• a set of attributes is added to CorporateAction ; all of them have optional cardinality (0..1) :

  • recordDate date (existing type)
  • annoucementDate date (existing type)
  • informationSource InformationSource (existing type)
  • dividendObservation PriceSchedule (existing type)
  • bespokeEventDescription string (existing type)
  • adjustmentFactor AdjustmentFactor (new type : see details below)

• new type AdjustmentFactor : to populate the adjustment factor value, as well as to describe the resolvable terms required when calculating an adjustment factor, depending the type of Corporate Action at stake (merger, split, etc.) :

  • compulsory attribute : value number (existing type) : to represent the multipler value applied to the price of the underlier impacted by a Corporate Action. this attribute is compulsory
  • optional attribute : calculation PriceAdjustmentFactorCalculationTerms (new type : see details below)

• new type PriceAdjustmentFactorCalculationTerms : to represent the input terms involved in the calculation of the adjustment factor applied to the price of the underlier impacted by a Corporate Action ; all attributes are optional, given that the need for populating such terms, depends on the event type of the Corporate Action, and new conditions are added to ensure consistency in the choices that can be made :

  • some attributes re-use existing types :
    • number (examples: shareForShareRatio, shareForRightsRatio, dividendRatio)
    • or Price (example: rightsSubscriptionPrice)
    • or string (example: bespokeCalculationFormula)
  • other ones are using new type, such as SpinOff, Merger and AccrualFactor which in turn are-use existing types:
    • example with SpinOff attributes : Security is re-used by both parentCompany and childCompany
    • Price is re-used by both parentPriceObservation and childPriceObservation

Review Directions

Changes can be reviewed in PR #3642

[JayasriR]

@eacunaISDA Can you please review release notes. They have been updated now

[PayalKhanna]

@JBZ-Fragmos You have updated the Title but not the background please can you edit the Release note directly here

[llynhiavu]

Reviewed.

[eacunaISDA]

What is this sentence supposed to be: "This releases enrich the description of Corporate Action" - is it supposed to say 'this release' (singular) enriches? or 'these releases enrich' (is there a related PR ?).

As for the background section, this is found to be unchanged and has not been improved following suggestions in previous reviews.

For reference:
A recent example of a well-written "background" section that explains the problem statement, followed by the changes made to resolve these in the "What is being released" section can be found in this example:

Concentration Limit Release Notes

In this example, the Background section sets the scene, explains what is currently the case, the 'AS-IS' state, and what is not possible to do. In the following section, the 'TO-BE' state is described, the changes the release provides.

[JayasriR]

@JBZ-Fragmos Can you please update release notes as per the review comments. thanks

[PayalKhanna]

@JBZ-Fragmos Can you please update release notes as per the review comments. thanks

[JBZ-Fragmos]

Event Model - Enrichment of Corporate Action

Background

As of today there is already an existing component in CDM to describe Corporate Action under Event model, that is CorporateAction.
However, the current list of attributes is quite poor with regards to business expectation, meaning that some information is currently missing, when making a gap analysis between CorporateAction and the set of information being actually required e.g. "record date", "adjustment factor", "bespoke description", and other ones.

What is being released ?

This release enriches the description of Corporate Action with new attributes to represent the missing information, in order to ensure that CorporateAction provides an exhaustive representation, in line with the business expectations

• four new values are added in the list of existing type CorporateActionTypeEnum :

  • BankruptcyOrInsolvency
  • IssuerNationalization
  • Relisting
  • BespokeEvent

• a set of attributes is added to CorporateAction ; all of them have optional cardinality (0..1) :

  • recordDate date (existing type)
  • annoucementDate date (existing type)
  • informationSource InformationSource (existing type)
  • dividendObservation PriceSchedule (existing type)
  • bespokeEventDescription string (existing type)
  • adjustmentFactor AdjustmentFactor (new type : see details below)

• new type AdjustmentFactor : to populate the adjustment factor value, as well as to describe the resolvable terms required when calculating an adjustment factor, depending the type of Corporate Action at stake (merger, split, etc.) :

  • compulsory attribute : value number (existing type) : to represent the multipler value applied to the price of the underlier impacted by a Corporate Action. this attribute is compulsory
  • optional attribute : calculation PriceAdjustmentFactorCalculationTerms (new type : see details below)

• new type PriceAdjustmentFactorCalculationTerms : to represent the input terms involved in the calculation of the adjustment factor applied to the price of the underlier impacted by a Corporate Action ; all attributes are optional, given that the need for populating such terms, depends on the event type of the Corporate Action, and new conditions are added to ensure consistency in the choices that can be made :

  • some attributes re-use existing types :
    • number (examples: shareForShareRatio, shareForRightsRatio, dividendRatio)
    • or Price (example: rightsSubscriptionPrice)
    • or string (example: bespokeCalculationFormula)
  • other ones are using new type, such as SpinOff, Merger and AccrualFactor which in turn are-use existing types:
    • example with SpinOff attributes : Security is re-used by both parentCompany and childCompany
    • Price is re-used by both parentPriceObservation and childPriceObservation

Review Directions

Changes can be reviewed in PR #3642

[JBZ-Fragmos]

hi @eacunaISDA
hi @PayalKhanna

have update Release Note above, with an intent to comply with your expectations

is that OK now ? please let me know

regards

JB