Incomplete PM Identity Coverage in YANG Augmentations

[roshan-joyce-fujitsu]

Note: This document was partly generated by an AI assistant to analyze TAPI YANG model PM augmentation coverage.

Issue Summary

This issue identifies gaps in the TAPI YANG model where PM (Performance Monitoring) identities currently defined in tapi-common.yang lack corresponding augmentation fields in the layer-specific YANG modules (tapi-photonic-media.yang, tapi-digital-otn.yang, tapi-eth.yang).

This is also related to the analysis we're currently doing to identify missing PM parameters and fields in TAPI, when comparing it with the union of all optical performance parameters being identified by IETF CCAMP.

Impact: Implementations cannot properly map vendor PM data to TAPI history-data structures for PM identities that lack augmentations.

Scope: 29 PM identities defined in tapi-common.yang (all extending base PM)

Coverage Status: 17 fully covered (59%), 2 partially covered (7%), 10 not covered (34%)

Proposed Solutions:

• Approach 1: Extend layer-specific augmentations (e.g., add missing FEC fields to otu-fec-performance-data)
• Approach 2: Add generic pm-parameter list to history-data using existing tapi-common:pm-parameter grouping

---

Background: TAPI YANG PM Augmentations

Current Augmentations

tapi-photonic-media.yang

Augmentation: photonic-performance-data

Covers:

1. optical-input-power (with power-properties)
   • total-power
   • power-spectral-density
2. optical-output-power (with power-properties)
   • total-power
   • power-spectral-density
3. input-voa (Variable Optical Attenuator)
4. output-voa
5. optical-gain
6. optical-tilt
7. amplification-performance-data (list)
   • optical-input-power
   • optical-output-power
   • input-voa
   • output-voa
   • optical-gain
   • optical-tilt
8. otsi-monitoring-pac (OTSi monitoring)
   • polarization-mode-dispersion
   • chromatic-dispersion
   • diff-group-delay
   • frequency-offset
9. osc-monitoring-pac (Optical Supervisory Channel)
   • optical-input-power
   • optical-output-power

tapi-digital-otn.yang

Augmentation 1: otn-error-performance-data

Covers:

• near-end-otn-counters
  • sm-bip-errors
  • pm-bip-errors
  • sm-bei-errors
  • pm-bei-errors
  • sm-biae-errors
  • pm-biae-errors
  • es-count
  • ses-count
  • uas-count
• far-end-otn-counters (same structure)
• bidirectional-uas
• codirectional flag
• otn-cn-error-performance-data (list for TCM levels)

Augmentation 2: otu-fec-performance-data

Covers:

• fec-corrected-errors-count
• pre-fec-ber
• post-fec-ber
• uncorrectable-bytes

Augmentation 3: odu-delay-performance-data

Covers:

• delay-frame-count
• delay-measure-success

tapi-eth.yang

Multiple Augmentations for Ethernet PM:

1. eth-pro-active-dm-performance-data (Delay Measurement - DMM/DMR)

   • statistical-bi-dir-dm-parameters
   • statistical-near-end-dm-parameters
   • statistical-far-end-dm-parameters

2. eth-pro-active-lm-performance-data (Loss Measurement - LMM/LMR)

   • statistical-far-end-lm-parameters
   • statistical-near-end-lm-parameters
   • statistical-bi-dir-lm-parameters

3. eth-pro-active-1-dm-performance-data (1-way DM - 1DM)

   • statistical-near-end-1-dm-parameters

4. eth-pro-active-1-lm-performance-data (1-way LM - 1SL)

   • statistical-near-end-1-lm-parameters
   • availability-flr-parameters

5. eth-on-demand-1-dm-performance-data

6. eth-on-demand-1-lm-performance-data

7. eth-on-demand-dm-performance-data

8. eth-on-demand-lm-performance-data

9. eth-pro-active-1-dm-source-performance-data

10. eth-pro-active-1-lm-source-performance-data

11. eth-on-demand-1-dm-source-performance-data

12. eth-on-demand-1-lm-source-performance-data

---

Detailed Coverage Analysis

PM Identities in tapi-common.yang

Total: 29 PM identities (all extending base PM)

Photonic Layer (10 identities) - 100% Coverage ✅

1. PM_CHROM_DISP ✅ → photonic-performance-data.otsi-monitoring-pac.chromatic-dispersion
2. PM_DIFF_GROUP_DELAY ✅ → photonic-performance-data.otsi-monitoring-pac.diff-group-delay
3. PM_FREQ_OFFS ✅ → photonic-performance-data.otsi-monitoring-pac.frequency-offset
4. PM_OPT_GAIN ✅ → photonic-performance-data.optical-gain
5. PM_OPT_PWR_SPECTR_DENS_INPUT ✅ → photonic-performance-data.optical-input-power.power-spectral-density
6. PM_OPT_PWR_SPECTR_DENS_OUTPUT ✅ → photonic-performance-data.optical-output-power.power-spectral-density
7. PM_OPT_TOTAL_PWR_INPUT ✅ → photonic-performance-data.optical-input-power.total-power
8. PM_OPT_TOTAL_PWR_OUTPUT ✅ → photonic-performance-data.optical-output-power.total-power
9. PM_OPT_TILT ✅ → photonic-performance-data.optical-tilt
10. PM_POL_MODE_DISP ✅ → photonic-performance-data.otsi-monitoring-pac.polarization-mode-dispersion
11. PM_VOA_INPUT ✅ → photonic-performance-data.input-voa
12. PM_VOA_OUTPUT ✅ → photonic-performance-data.output-voa

OTN Error Counters (3 identities) - 100% Coverage ✅

1. PM_BBE ✅ → otn-error-performance-data.near-end-otn-counters.sm-bip-errors (or pm-bip-errors)
2. PM_SES ✅ → otn-error-performance-data.near-end-otn-counters.ses-count
3. PM_UAS ✅ → otn-error-performance-data.near-end-otn-counters.uas-count

OTN Delay (1 identity) - 100% Coverage ✅

1. PM_DELAY_FRAME_COUNT ✅ → odu-delay-performance-data.delay-frame-count

FEC Metrics (15 identities) - 20% Coverage ❌

Fully Covered (3):

1. PM_FEC_CORRECTED_ERRORS ✅ → otu-fec-performance-data.fec-corrected-errors-count
2. PM_FEC_PRE_FEC_BER ✅ → otu-fec-performance-data.pre-fec-ber
3. PM_FEC_POST_FEC_BER ✅ → otu-fec-performance-data.post-fec-ber

Partially Covered (2):
4. PM_FEC_UNCORRECTABLE_BITS ⚠️ → Only uncorrectable-bytes exists (wrong granularity)
5. PM_FEC_UNCORRECTABLE_BLOCKS ⚠️ → Only uncorrectable-bytes exists (wrong granularity)

Not Covered (10):
6. PM_FEC_CORRECTABLE_BLOCKS ❌ → No augmentation field
7. PM_FEC_CORRECTED_BITS ❌ → No augmentation field (only fec-corrected-errors-count)
8. PM_FEC_CORRECTED_BYTES ❌ → No augmentation field
9. PM_FEC_CORRECTED_CODEWORDS ❌ → No augmentation field
10. PM_FEC_SYMBOL_ERRORS ❌ → No augmentation field
11. PM_FEC_UNCORRECTABLE_BYTES ✅ → otu-fec-performance-data.uncorrectable-bytes
12. PM_FEC_UNCORRECTABLE_WORDS ❌ → No augmentation field
13. PM_FEC_UNCORRECTED_CODEWORDS ❌ → No augmentation field

---

Problem Statement

The current tapi-digital-otn.yang module defines only 4 FEC-related fields in the otu-fec-performance-data grouping:

• fec-corrected-errors-count
• pre-fec-ber
• post-fec-ber
• uncorrectable-bytes

However, tapi-common.yang defines 15 FEC-related PM identities based on industry standards (OpenROADM, OpenConfig, IEEE 802.3). This creates a 67% gap in FEC PM coverage.

Impact:

• Implementations cannot map vendor FEC PM data to TAPI for 10 out of 15 FEC PM types
• Historical PM data retrieval via OAM Job Service is incomplete
• Cross-vendor PM data normalization is not possible for missing FEC types

---

Proposed Solutions

Approach 1: Extend Layer-Specific Augmentations

Recommendation: Add missing fields to existing layer-specific performance data groupings to achieve complete coverage of all 29 PM identities.

Specific Actions:

1. tapi-digital-otn.yang: Extend grouping otu-fec-performance-data to include fields for all 15 FEC-related PM identities:

   • Add fields for FEC correctable/corrected blocks, bytes, bits, codewords
   • Add fields for FEC symbol errors
   • Add fields for FEC uncorrectable/uncorrected blocks, words, codewords
   • Align with OpenROADM, OpenConfig, and IEEE 802.3 standards

2. Benefits:

   • Minimal model changes (only FEC grouping affected)
   • Maintains existing augmentation structure
   • Backward compatible (new fields are optional)
   • Direct 1:1 mapping from PM identities to augmentation fields

3. Drawbacks:

   • Requires updating specific groupings for each missing/new PM type
   • Less flexible for future PM types
   • Tightly coupled to current PM identity definitions

---

Approach 2: Generic PM Parameter List (Flexible)

Recommendation: Add a generic PM parameter list to both current-data and history-data that can accommodate any PM identity using the existing tapi-common:pm-parameter grouping.

Proposed YANG Structure:

// In tapi-oam.yang, extend both current-data and history-data groupings:

grouping current-data {
    // Existing fields
    leaf period-start-time { ... }
    container elapsed-time { ... }
    container pm-data-pac { ... }
    
    // PROPOSED NEW FIELD:
    list pm-parameter {
        key 'pm-parameter-name';
        config false;
        uses tapi-common:pm-parameter;
        description "Generic PM parameters using PM identities from tapi-common.
            This list can accommodate any PM identity defined in tapi-common:pm,
            providing a flexible mechanism for current PM data that doesn't have 
            specific augmentation fields.";
    }
    
    // Existing fields
    container mep { ... }
    container mip { ... }
    container connection-end-point { ... }
    list history-data { ... }
    uses tapi-common:local-class;
}

grouping history-data {
    // Existing fields
    leaf period-start-time { ... }
    leaf period-end-time { ... }
    container pm-data-pac { ... }
    
    // PROPOSED NEW FIELD:
    list pm-parameter {
        key 'pm-parameter-name';
        uses tapi-common:pm-parameter;
        description "Generic PM parameters using PM identities from tapi-common.
            This list can accommodate any PM identity defined in tapi-common:pm,
            providing a flexible mechanism for historical PM data that doesn't have 
            specific augmentation fields.";
    }
    
    // Existing fields
    uses tapi-common:local-class;
}

How it works:

The tapi-common:pm-parameter grouping already exists and contains:

grouping pm-parameter {
    leaf pm-parameter-name {
        type pm;  // identityref to PM identities
        description "The name of the PM metric.";
    }
    list pm-parameter-value {
        key 'pm-parameter-value-type';
        uses pm-parameter-value;
        description "The value of the PM metric.";
    }
}

Example Usage:

{
  "tapi-oam:cep-pm-data": [{
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "tapi-oam:history-data": [{
      "local-id": "1234567890000",
      "period-start-time": "20260728T030000.0Z",
      "period-end-time": "20260728T031500.0Z",
      "pm-data-pac": {
        "granularity-period": {
          "period": [{
            "value": "15",
            "unit": "tapi-common:TIME_UNIT_MINUTE"
          }]
        },
        "suspect-interval-flag": false
      },
      "tapi-common:pm-parameter": [
        {
          "pm-parameter-name": "tapi-common:PM_FEC_CORRECTED_CODEWORDS",
          "pm-parameter-value": [{
            "pm-parameter-value-type": "tapi-common:METRIC_VALUE_TYPE",
            "pm-parameter-value": "12345.0"
          }]
        },
        {
          "pm-parameter-name": "tapi-common:PM_FEC_SYMBOL_ERRORS",
          "pm-parameter-value": [{
            "pm-parameter-value-type": "tapi-common:METRIC_VALUE_TYPE",
            "pm-parameter-value": "67.0"
          }]
        },
        {
          "pm-parameter-name": "tapi-common:PM_FEC_PRE_FEC_BER",
          "pm-parameter-value": [
            {
              "pm-parameter-value-type": "tapi-common:METRIC_VALUE_TYPE_AVERAGE",
              "pm-parameter-value": "0.0000123"
            },
            {
              "pm-parameter-value-type": "tapi-common:METRIC_VALUE_TYPE_MIN",
              "pm-parameter-value": "0.0000089"
            },
            {
              "pm-parameter-value-type": "tapi-common:METRIC_VALUE_TYPE_MAX",
              "pm-parameter-value": "0.0000156"
            }
          ]
        }
      ]
    }]
  }]
}

Benefits:

1. Complete Flexibility: Can accommodate any PM identity without model changes
2. Future-Proof: New PM identities automatically supported
3. Unified Approach: Same mechanism works for all layers (photonic, OTN, Ethernet)
4. No Augmentation Gaps: Every PM identity in tapi-common.yang is usable
5. Backward Compatible: Existing layer-specific augmentations remain unchanged
6. Faster/easier Processing: Creating a list entry for each monitored PM type and its value fits well with the way most Network Elements report PM and the way controllers process them. It is also expected that this will be easier for a TAPI client to process as well, since it does not need to extract specific JSON objects and their property values under history-data.

Drawbacks:

1. Less Type-Safe: Values are decimal64, not strongly typed per PM metric
2. More Generic: Loses layer-specific semantic structure
3. Dual Mechanism: Both specific augmentations and generic list coexist

Use Cases:

• Primary: Use for PM identities that lack specific augmentation fields (e.g., FEC codewords, symbol errors)
• Fallback: Use when vendor PM data doesn't map cleanly to existing augmentations
• Extension: Use for vendor-specific or experimental PM types

---

Submitted by: [Roshan Joyce/1FINITY]
Date: 2026-07-28
TAPI Version: v2.4.1+

CC: @nigel-r-davis @kgkishore @bcjohnso99 @arthurMll