> For the complete documentation index, see [llms.txt](https://docs.therisk.global/nexus-paradigm/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.therisk.global/nexus-paradigm/global-risks-index-grix/common-data-model/projection/add-supporting-attribute.md).

# Add Supporting Attribute

### Overview

#### What is `AddSupportingAttribute`?

The `AddSupportingAttribute` operation is a projection operation in CDM that adds a user-specified supporting attribute to the final resolved entity. As the name suggests, the newly created supporting attribute is designed to support another attribute, providing additional context, metadata, or derived information. The relationship between the supporting attribute and the primary attribute is established through the `is.addedInSupportOf` trait.

**Key Characteristics:**

* **Supporting Attribute Creation:** Introduces a new attribute that supports an existing attribute by providing supplementary information.
* **Trait Assignment:** The supporting attribute is assigned the `is.virtual.attribute` trait, indicating its virtual nature, and the `is.addedInSupportOf` trait to establish its relationship with the primary attribute.
* **Virtual Attribute:** Being virtual means that the supporting attribute might not have corresponding data values in the entity's partition unless explicitly generated or manifested.
* **Conditional Inclusion:** A new directive `virtual` allows for scenarios where virtual attributes are not desired. It is recommended to add a condition to filter out virtual attributes when they are not needed.

#### Purpose in GRIx

Within GRIx, the `AddSupportingAttribute` operation serves to:

* **Enhance Data Context:** Provide additional context or metadata to existing attributes, enriching the data model.
* **Facilitate Data Integration:** Support integration with other data sources or systems by adding necessary supporting information.
* **Improve Data Analysis:** Enable more comprehensive data analysis by linking primary attributes with their supporting attributes.
* **Maintain Data Integrity:** Ensure that supporting attributes are clearly associated with their primary attributes, promoting data consistency and integrity.

By incorporating `AddSupportingAttribute`, GRIx data models become more informative and analytically robust, supporting comprehensive risk assessments and decision-making processes.

***

### Functionality and Behavior

#### How `AddSupportingAttribute` Works

The `AddSupportingAttribute` operation modifies the attribute list of an entity during the resolution process by adding a new supporting attribute. Below is a detailed breakdown of its functionality:

1. **Input Attributes:** The operation accesses the current list of resolved attributes from the source entity or previous operations in the projection pipeline.
2. **Defining the Supporting Attribute:** Users specify the supporting attribute, including its name, data type, and additional properties such as description and purpose.
3. **Trait Assignment:**
   * **`is.virtual.attribute`:** Indicates that the supporting attribute is virtual and may not have corresponding data values unless explicitly generated.
   * **`is.addedInSupportOf`:** Establishes the relationship between the supporting attribute and the primary attribute it supports. Currently, this trait points to the last attribute that came from the source of the projections, mimicking CDM's resolution guidance.
4. **Insertion Point:** Based on the `insertAtTop` flag, the supporting attribute is either added at the beginning or the end of the attribute list.
5. **Virtual Directive:** The `virtual` directive can be used in conjunction with the `condition` property to control the inclusion of virtual attributes based on specific scenarios or requirements.
6. **Resulting Attributes:** The final resolved entity includes the newly added supporting attribute alongside the original attributes, maintaining the specified order.

#### Default Behavior

* **Virtual Attribute Creation:** The supporting attribute is created as a virtual attribute by default, assigned the `is.virtual.attribute` trait.
* **Trait Linking:** The supporting attribute is linked to the primary attribute using the `is.addedInSupportOf` trait, pointing to the last attribute from the projection source.
* **Conditional Inclusion:** If the `virtual` directive is used, the supporting attribute can be conditionally included or excluded based on specified criteria.
* **Non-Destructive:** The operation does not remove or alter the original attributes; it merely adds a new supporting attribute to the entity.

#### API Reference

For detailed technical specifications and additional configuration options, refer to the [AddSupportingAttribute API Documentation](https://docs.microsoft.com/en-us/common-data-model/api-reference/addsupportingattribute).

***

### Configuration Options

The `AddSupportingAttribute` operation can be customized using several properties to control its behavior during the projection process.

#### Mandatory Properties

* **`$type`:** Specifies the operation type. For `AddSupportingAttribute`, this should be set to `"addSupportingAttribute"`.
* **`supportingAttribute`:** An object defining the supporting attribute to be added. It must include:
  * **`name`:** The name of the new supporting attribute.
  * **`dataType`:** The data type of the new supporting attribute.
  * **`purpose`:** The purpose of the supporting attribute (e.g., `"hasA"`).
  * **`isReadOnly`:** (Optional) Indicates whether the supporting attribute is read-only.

#### Optional Properties

* **`insertAtTop`:** A boolean flag that determines the insertion point of the supporting attribute.
  * **`true`:** Inserts the supporting attribute at the beginning of the attribute list.
  * **`false` or omitted:** Appends the supporting attribute to the end of the attribute list.
* **`description`:** Provides a description of the supporting attribute, offering context for its purpose.
* **`condition`:** A logical expression that determines whether the operation should execute based on predefined tokens and operators. It is recommended to include conditions to filter out virtual attributes when they are not needed.
* **`explanation`:** Provides a description of what the operation does. Useful for documentation and maintenance purposes.

#### Property Breakdown

| **Property**          | **Type**  | **Description**                                                                                                | **Required** |
| --------------------- | --------- | -------------------------------------------------------------------------------------------------------------- | ------------ |
| `$type`               | `string`  | Specifies the operation type. Must be `"addSupportingAttribute"`.                                              | Yes          |
| `supportingAttribute` | `object`  | Defines the supporting attribute to add, including `name`, `dataType`, `purpose`, and optionally `isReadOnly`. | Yes          |
| `insertAtTop`         | `boolean` | Determines where to insert the supporting attribute. Defaults to `false` if not specified.                     | No           |
| `description`         | `string`  | Provides a description of the supporting attribute for additional context.                                     | No           |
| `condition`           | `string`  | A logical expression that determines whether the operation should execute.                                     | No           |
| `explanation`         | `string`  | Describes the purpose of the operation for future reference.                                                   | No           |

#### Example Configuration

```json
{
    "$type": "addSupportingAttribute",
    "supportingAttribute": {
        "name": "priorityCode_display",
        "dataType": "localizedDisplayText",
        "purpose": "hasA",
        "isReadOnly": true,
        "description": "This attribute 'priorityCode_display' holds the localized display text for the 'priorityCode' attribute."
    },
    "insertAtTop": false,
    "condition": "virtual",
    "explanation": "Adding priorityCode_display to provide the display text for the priorityCode attribute."
}
```

**Explanation:**

* **`$type`:** Identifies the operation as `addSupportingAttribute`.
* **`supportingAttribute`:** Defines a supporting attribute named `priorityCode_display` of type `localizedDisplayText`, with a clear purpose and description.
* **`insertAtTop`:** Specifies that the `priorityCode_display` attribute should be appended to the end of the attribute list.
* **`condition`:** The operation includes a condition `virtual` to allow filtering of virtual attributes when they are not needed.
* **`explanation`:** Documents the purpose of the operation for future reference.

***

### Detailed Examples

To provide a clearer understanding of how the `AddSupportingAttribute` operation functions within GRIx, the following examples illustrate its application in various contexts relevant to GRIx’s areas of focus and targets.

#### Example 1: Using `AddSupportingAttribute` on a Data Typed Attribute

**Scenario:**\
In certain scenarios, a data-typed attribute may hold a list of constant values to which the attribute's value is constrained. For instance, an attribute like `priorityCode` may reference a list of predefined priority levels. To provide additional context, such as localized display text for each priority level, a supporting attribute can be added.

**GRIx Area of Focus:**\
Risk Assessment and Prioritization

**Target:**\
Enhance the usability and readability of risk attributes by providing descriptive and localized information.

**Base Entity Definition:**

```json
{
    "entityName": "Person",
    "hasAttributes": [
        {
            "name": "name",
            "dataType": "string"
        },
        {
            "name": "dateOfBirth",
            "dataType": "integer"
        },
        {
            "name": "address",
            "dataType": "string"
        },
        {
            "name": "phoneNumber",
            "dataType": "string"
        },
        {
            "name": "email",
            "dataType": "string"
        }
    ]
}
```

**Attribute with List Constraint:**

```json
{
    "name": "priorityCode",
    "purpose": "hasA",
    "dataType": {
        "dataTypeReference": "listLookup",
        "appliedTraits": [
            {
                "traitReference": "does.haveDefault",
                "arguments": [
                    {
                        "entityReference": {
                            "explanation": "The constantValues below correspond to the attributes of the 'listLookupValues' entityShape which are: {languageTag, displayText, attributeValue, displayOrder}",
                            "entityShape": "listLookupValues",
                            "constantValues": [
                                [
                                    "en",
                                    "Low",
                                    "0",
                                    "0"
                                ],
                                [
                                    "en",
                                    "Normal",
                                    "1",
                                    "1"
                                ],
                                [
                                    "en",
                                    "High",
                                    "2",
                                    "2"
                                ]
                            ]
                        }
                    }
                ]
            }
        ]
    },
    "projection": {
        "operations": [
            {
                "$type": "addSupportingAttribute",
                "supportingAttribute": {
                    "explanation": "This attribute 'priorityCode_display' is added to the entity to provide the localized display text for the value of the listLookup attribute 'priorityCode'",
                    "name": "priorityCode_display",
                    "purpose": "hasA",
                    "dataType": "localizedDisplayText",
                    "isReadOnly": true
                }
            }
        ]
    }
}
```

**Projection with `AddSupportingAttribute`:**

```json
{
    "name": "PriorityInfo",
    "entity": {
        "source": "Person",
        "operations": [
            {
                "$type": "addSupportingAttribute",
                "supportingAttribute": {
                    "name": "priorityCode_display",
                    "dataType": "localizedDisplayText",
                    "purpose": "hasA",
                    "isReadOnly": true,
                    "description": "Provides the localized display text for the priorityCode attribute."
                },
                "explanation": "Adding priorityCode_display to provide display text for priorityCode."
            }
        ]
    }
}
```

**Resulting Resolved `PriorityInfo` Entity:**

| **Attribute**         | **Data Type**        | **Description**                                        |
| --------------------- | -------------------- | ------------------------------------------------------ |
| name                  | string               | Name of the person.                                    |
| dateOfBirth           | integer              | Date of birth of the person.                           |
| address               | string               | Address of the person.                                 |
| phoneNumber           | string               | Phone number of the person.                            |
| email                 | string               | Email address of the person.                           |
| priorityCode          | listLookup           | Priority code constrained to predefined values.        |
| priorityCode\_display | localizedDisplayText | Localized display text for the priorityCode attribute. |

**Explanation:**

* The `AddSupportingAttribute` operation introduces a new supporting attribute named `priorityCode_display` of type `localizedDisplayText`.
* The `priorityCode_display` attribute provides a human-readable, localized description corresponding to each `priorityCode` value, enhancing data usability.
* This supporting attribute is read-only and contains descriptive information, making the `priorityCode` attribute more informative.

**Concrete Relation to GRIx:**\
By adding `priorityCode_display`, GRIx enhances the clarity and usability of risk-related attributes. This allows analysts to easily interpret the severity of risks without needing to reference external lookup tables, thereby streamlining risk assessment processes.

***

#### Example 2: Using `AddSupportingAttribute` on an Entity Attribute

**Scenario:**\
In certain scenarios, a data-typed attribute can hold a list of constant values to which the attribute's value is constrained. For example, an attribute like `priorityCode` may have corresponding display text values. To store the display text alongside the code, a supporting attribute can be added.

**GRIx Area of Focus:**\
Risk Assessment and Prioritization

**Target:**\
Provide descriptive information for constrained attribute values to facilitate better understanding and analysis.

**Projection with `AddSupportingAttribute`:**

```json
{
    "name": "PersonInfo",
    "entity": {
        "source": "Person",
        "operations": [
            {
                "$type": "addSupportingAttribute",
                "supportingAttribute": {
                    "name": "age",
                    "dataType": "integer",
                    "purpose": "hasA",
                    "description": "Supporting attribute for the age of the person.",
                    "isReadOnly": true
                }
            }
        ]
    }
}
```

**Resulting Resolved `PersonInfo` Entity:**

| **Attribute** | **Data Type** | **Description**                   |
| ------------- | ------------- | --------------------------------- |
| name          | string        | Name of the person.               |
| dateOfBirth   | integer       | Date of birth of the person.      |
| address       | string        | Address of the person.            |
| phoneNumber   | string        | Phone number of the person.       |
| email         | string        | Email address of the person.      |
| age           | integer       | Supporting attribute for the age. |

**Explanation:**

* The `AddSupportingAttribute` operation adds a supporting attribute named `age` to the `PersonInfo` entity.
* This supporting attribute provides additional context or metadata for the `age` attribute, such as validation rules or derived information.
* Being a supporting attribute, `age` is marked as read-only and virtual, meaning it may not have corresponding data values unless explicitly generated.

**Concrete Relation to GRIx:**\
By adding supporting attributes like `age`, GRIx enhances the richness of its data models. This allows for more nuanced analyses, such as age-based risk assessments or demographic studies, by providing additional layers of information that support primary attributes.

***

#### Example 3: Using `AddSupportingAttribute` When Extending an Entity

**Scenario:**\
Creating a `Child` entity that extends the `Person` entity. The `AddSupportingAttribute` operation is used to add a supporting attribute named `age` to represent the age of the child. This supporting attribute provides additional context to the inherited attributes from the `Person` entity.

**GRIx Area of Focus:**\
Demographic Analysis and Risk Assessment

**Target:**\
Enhance extended entities with additional supporting information to facilitate detailed demographic and risk analyses.

**Base Entity Definition:**

```json
{
    "entityName": "Person",
    "hasAttributes": [
        {
            "name": "name",
            "dataType": "string"
        },
        {
            "name": "dateOfBirth",
            "dataType": "integer"
        },
        {
            "name": "address",
            "dataType": "string"
        },
        {
            "name": "phoneNumber",
            "dataType": "string"
        },
        {
            "name": "email",
            "dataType": "string"
        }
    ]
}
```

**Child Entity Definition with `AddSupportingAttribute`:**

```json
{
    "entityName": "Child",
    "extendsEntity": {
        "source": "Person",
        "operations": [
            {
                "$type": "addSupportingAttribute",
                "supportingAttribute": {
                    "name": "age",
                    "dataType": "integer",
                    "purpose": "hasA",
                    "description": "Supporting attribute for the age of the child.",
                    "isReadOnly": true
                }
            }
        ]
    },
    "hasAttributes": []
}
```

**Resulting Resolved `Child` Entity:**

| **Attribute** | **Data Type** | **Description**                                |
| ------------- | ------------- | ---------------------------------------------- |
| name          | string        | Name of the child.                             |
| dateOfBirth   | integer       | Date of birth of the child.                    |
| address       | string        | Address of the child.                          |
| phoneNumber   | string        | Phone number of the child.                     |
| email         | string        | Email address of the child.                    |
| age           | integer       | Supporting attribute for the age of the child. |

**Explanation:**

* The `Child` entity extends the `Person` entity, inheriting all its attributes.
* The `AddSupportingAttribute` operation adds a new supporting attribute named `age` specifically for the `Child` entity.
* This supporting attribute provides additional context for the child's age, which may be used for age-specific risk assessments or demographic analyses.

**Concrete Relation to GRIx:**\
By extending entities and adding supporting attributes, GRIx allows for more specialized and detailed data models. In this case, adding `age` to the `Child` entity supports targeted analyses that consider age-related risk factors, enhancing the precision and relevance of risk assessments.

***

#### Example 4: Using `AddSupportingAttribute` with ArrayExpansion

**Scenario:**\
Enhancing the `ClimateImpactAssessment` entity by using both the `ArrayExpansion` and `AddSupportingAttribute` operations. The `ArrayExpansion` operation expands an array of `Person` entities, and the `AddSupportingAttribute` operation adds a count attribute named `personCount` to represent the total number of expanded `Person` elements. This combination supports comprehensive climate impact analysis by providing detailed and aggregated data on affected individuals.

**GRIx Area of Focus:**\
Climate Impact Assessment and Environmental Risk

**Target:**\
Facilitate detailed and organized climate impact analysis through comprehensive data expansion and aggregation.

**Base Entity Definition:**

```json
{
    "entityName": "ClimateImpactAssessment",
    "hasAttributes": [
        {
            "name": "assessmentId",
            "dataType": "string"
        },
        {
            "name": "assessmentDate",
            "dataType": "date"
        },
        {
            "name": "temperatureChange",
            "dataType": "float"
        },
        {
            "name": "seaLevelRise",
            "dataType": "float"
        },
        {
            "name": "carbonEmissions",
            "dataType": "float"
        },
        {
            "name": "biodiversityLoss",
            "dataType": "float"
        },
        {
            "name": "affectedPersons",
            "dataType": "array",
            "elementType": "Person"
        }
    ]
}
```

**Projection with `AddSupportingAttribute` Combined with `ArrayExpansion`:**

```json
{
    "name": "ClimateImpactAssessmentInfo",
    "entity": {
        "source": {
            "source": "ClimateImpactAssessment",
            "operations": [
                {
                    "$type": "arrayExpansion",
                    "startOrdinal": 1,
                    "endOrdinal": 2
                },
                {
                    "$type": "renameAttributes",
                    "renameFormat": "{m}_{o}"
                }
            ]
        },
        "operations": [
            {
                "$type": "addSupportingAttribute",
                "supportingAttribute": {
                    "name": "personCount",
                    "dataType": "integer",
                    "purpose": "hasA",
                    "description": "Total number of expanded Person elements.",
                    "isReadOnly": true
                },
                "condition": "virtual",
                "explanation": "Adding personCount to represent the total number of expanded Person elements."
            }
        ]
    }
}
```

**Resulting Resolved `ClimateImpactAssessmentInfo` Entity:**

| **Attribute**     | **Data Type** | **Description**                             |
| ----------------- | ------------- | ------------------------------------------- |
| assessmentId      | string        | Unique identifier for the assessment.       |
| assessmentDate    | date          | Date of the climate impact assessment.      |
| temperatureChange | float         | Change in temperature measured.             |
| seaLevelRise      | float         | Rise in sea levels measured.                |
| carbonEmissions   | float         | Carbon emissions measured.                  |
| biodiversityLoss  | float         | Biodiversity loss measured.                 |
| name\_1           | string        | Name of the first person affected.          |
| age\_1            | integer       | Age of the first person affected.           |
| address\_1        | string        | Address of the first person affected.       |
| phoneNumber\_1    | string        | Phone number of the first person affected.  |
| email\_1          | string        | Email of the first person affected.         |
| name\_2           | string        | Name of the second person affected.         |
| age\_2            | integer       | Age of the second person affected.          |
| address\_2        | string        | Address of the second person affected.      |
| phoneNumber\_2    | string        | Phone number of the second person affected. |
| email\_2          | string        | Email of the second person affected.        |
| personCount       | integer       | Total number of expanded Person elements.   |

**Explanation:**

* The `ArrayExpansion` operation expands the `affectedPersons` array, creating individual attributes for each `Person` element (e.g., `name_1`, `age_1`, etc.).
* The `renameAttributes` operation formats the attribute names to include ordinal indicators, enhancing clarity and organization.
* The `AddSupportingAttribute` operation introduces the `personCount` attribute, representing the total number of expanded `Person` elements. This count attribute is essential for aggregating data and providing a summary of affected individuals.
* The `personCount` attribute is appended to the end of the attribute list, as `insertAtTop` is not specified.

**Concrete Relation to GRIx:**\
Combining `ArrayExpansion` with `AddSupportingAttribute` allows GRIx to handle complex data structures involving arrays of entities. In this example, it supports detailed climate impact analysis by both expanding individual affected persons and providing a count of these individuals. This dual approach facilitates comprehensive data analysis, enabling insights into both granular and aggregated data points related to climate impacts.

***

### Best Practices

To maximize the effectiveness of the `AddSupportingAttribute` operation within GRIx, adhere to the following best practices:

#### 1. **Consistent Naming Conventions**

* **Clarity:** Ensure that the names of supporting attributes clearly reflect their purpose and the nature of the attributes they support.
* **Avoid Conflicts:** Use unique and descriptive names to prevent conflicts with existing attributes or other supporting attributes.

**Example:**

Instead of naming the supporting attribute `displayText`, use a more descriptive name like `priorityCode_display` or `email_verified`.

#### 2. **Strategic Insertion**

* **Logical Placement:** Use the `insertAtTop` flag judiciously to position supporting attributes where they are most relevant and easily accessible.
* **Prioritization:** Place important supporting attributes at the top if they are critical for downstream processes or frequent analysis.

**Example:**

If the supporting attribute is a key metric, inserting it at the top enhances visibility and accessibility for analysts.

#### 3. **Use Conditions Appropriately**

* **Contextual Addition:** Leverage the `condition` property to add supporting attributes only under specific circumstances, such as when dealing with arrays or certain data types.
* **Maintain Flexibility:** Avoid overly complex conditions that may hinder the operation's flexibility or lead to maintenance challenges.

**Example:**

```json
{
    "$type": "addSupportingAttribute",
    "supportingAttribute": {
        "name": "emergencyContact_display",
        "dataType": "localizedDisplayText",
        "purpose": "hasA",
        "description": "Provides the display text for the emergencyContact attribute.",
        "isReadOnly": true
    },
    "condition": "virtual",
    "explanation": "Adding emergencyContact_display to provide display text for emergencyContact."
}
```

#### 4. **Documentation and Explanation**

* **Provide Clear Explanations:** Utilize the `explanation` property to document the purpose and reasoning behind each supporting attribute.
* **Maintain Up-to-Date Documentation:** Ensure that explanations are kept current with any changes to the data model.

**Example:**

```json
{
    "$type": "addSupportingAttribute",
    "supportingAttribute": {
        "name": "email_verified",
        "dataType": "boolean",
        "purpose": "hasA",
        "description": "Indicates whether the email address has been verified.",
        "isReadOnly": true
    },
    "explanation": "Adding email_verified to track the verification status of email addresses."
}
```

#### 5. **Reuse Supporting Attributes Where Appropriate**

* **Promote Reusability:** Define standard supporting attributes for commonly used metrics and reuse them across multiple entities to maintain consistency.
* **Standardize Supporting Metrics:** Maintain a library of standard supporting attributes that can be referenced consistently throughout the data model.

**Example:**

Define a `commonSupportingAttributes` group containing attributes like `createdDate_display` and `modifiedDate_display` that can be reused in various entities.

#### 6. **Validate Resolved Entities**

* **Consistency Checks:** After applying projections, validate the resolved entity to ensure that supporting attributes are correctly added and that there are no naming conflicts or structural issues.
* **Automated Testing:** Incorporate automated tests to verify the integrity of resolved entities, especially after multiple projection operations.

**Example:**

Use CDM’s validation methods to check the integrity of the resolved `ClimateImpactAssessmentInfo` entity after adding the `personCount` attribute.

```csharp
codevar resolvedEntity = await corpus.CreateResolvedEntityAsync("ClimateImpactAssessmentInfo", "default", "addSupportingAttribute");
resolvedEntity.Validate();
```

#### 7. **Minimize Redundancy**

* **Avoid Duplicate Supporting Attributes:** Ensure that supporting attributes are not redundantly created or referenced multiple times within the same entity.
* **Efficient Use:** Add supporting attributes only when necessary to maintain a streamlined and efficient data model.

**Example:**

Before adding a `priorityCode_display` attribute, confirm that it doesn't already exist to prevent redundancy.

***

### Common Use Cases in GRIx

The `AddSupportingAttribute` operation is versatile and can be applied in various scenarios within GRIx to enhance data models. Below are some common use cases:

#### 1. **Providing Descriptive Metadata**

**Purpose:**\
To add descriptive metadata for attributes that use constrained values, enhancing readability and usability.

**Example:**

Adding a `priorityCode_display` attribute to provide a human-readable description for each `priorityCode` value.

```json
{
    "$type": "addSupportingAttribute",
    "supportingAttribute": {
        "name": "priorityCode_display",
        "dataType": "localizedDisplayText",
        "purpose": "hasA",
        "description": "Provides the localized display text for the priorityCode attribute.",
        "isReadOnly": true
    },
    "explanation": "Adding priorityCode_display to provide display text for priorityCode."
}
```

#### 2. **Enhancing Data Integration**

**Purpose:**\
To support data integration processes by adding attributes that link to external systems or provide additional context.

**Example:**

Adding a `sourceSystemId` attribute to link data with its originating system.

```json
{
    "$type": "addSupportingAttribute",
    "supportingAttribute": {
        "name": "sourceSystemId",
        "dataType": "string",
        "purpose": "hasA",
        "description": "Identifier linking the data to its source system.",
        "isReadOnly": true
    },
    "explanation": "Adding sourceSystemId to track the origin of the data."
}
```

#### 3. **Facilitating Advanced Analytics**

**Purpose:**\
To provide additional metrics or context required for advanced analytical operations, such as machine learning models or simulations.

**Example:**

Adding a `calculationTimestamp` attribute to store the time when a calculated metric was generated.

```json
{
    "$type": "addSupportingAttribute",
    "supportingAttribute": {
        "name": "calculationTimestamp",
        "dataType": "dateTime",
        "purpose": "hasA",
        "description": "Timestamp indicating when the calculation was performed.",
        "isReadOnly": true
    },
    "explanation": "Adding calculationTimestamp to record when the calculated metric was generated."
}
```

#### 4. **Tracking Data Provenance**

**Purpose:**\
To maintain data provenance by adding attributes that track the history and origin of data elements.

**Example:**

Adding a `dataSource` attribute to indicate the source from which the data was obtained.

```json
{
    "$type": "addSupportingAttribute",
    "supportingAttribute": {
        "name": "dataSource",
        "dataType": "string",
        "purpose": "hasA",
        "description": "Indicates the source of the data.",
        "isReadOnly": true
    },
    "explanation": "Adding dataSource to track the origin of data elements."
}
```

#### 5. **Enhancing User Interface Elements**

**Purpose:**\
To support user interface elements by providing additional attributes that facilitate better user interactions or display information.

**Example:**

Adding a `status_display` attribute to provide a user-friendly status message corresponding to a `statusCode`.

```json
{
    "$type": "addSupportingAttribute",
    "supportingAttribute": {
        "name": "status_display",
        "dataType": "localizedDisplayText",
        "purpose": "hasA",
        "description": "Provides a user-friendly display text for the statusCode attribute.",
        "isReadOnly": true
    },
    "explanation": "Adding status_display to enhance UI representation of statusCode."
}
```

***

### Impact on GRIx Areas of Focus and Targets

The `AddSupportingAttribute` operation significantly impacts various areas of focus and targets within GRIx by enhancing data model organization, promoting attribute reusability, and supporting comprehensive risk analysis. Below is an analysis of how this operation relates to specific GRIx areas and targets.

#### 1. **Risk Assessment and Prioritization**

**Relation:**\
Group and count risk-related attributes to enable focused analysis and prioritization based on the number and severity of identified risks.

**Impact on Targets:**

* **Enhanced Clarity:** Facilitates clearer understanding of the risk landscape by providing additional context through supporting attributes.
* **Improved Analysis:** Streamlines the process of risk scoring and prioritization by enriching primary risk attributes with descriptive metadata.

#### 2. **Mitigation Strategies and Implementation**

**Relation:**\
Add supporting attributes to mitigation measures to evaluate the breadth and effectiveness of risk reduction efforts.

**Impact on Targets:**

* **Strategic Planning:** Enhances the ability to plan and allocate resources for mitigation efforts by providing supporting metrics.
* **Efficiency:** Reduces redundancy and simplifies the management of mitigation measures through enriched data attributes.

#### 3. **Climate Impact Assessment and Environmental Risk**

**Relation:**\
Use supporting attributes to quantify and provide context for environmental impact metrics, supporting detailed demographic and resource allocation analyses.

**Impact on Targets:**

* **Comprehensive Analysis:** Enables multi-level environmental impact assessments by providing both primary and supporting data points.
* **Data Integrity:** Ensures that all relevant climate data is organized and accessible for thorough analysis through supporting attributes.

#### 4. **Data Governance and Compliance**

**Relation:**\
Add supporting attributes to track compliance checks, regulatory requirements, and data provenance, ensuring adherence to necessary standards.

**Impact on Targets:**

* **Regulatory Compliance:** Simplifies the process of ensuring that data models comply with relevant regulations by providing supporting compliance metrics.
* **Data Provenance:** Enhances the ability to track data origins and changes over time through supporting attributes, ensuring data integrity and traceability.

#### 5. **Operational Efficiency and Data Reusability**

**Relation:**\
Promote reusability of supporting attributes across multiple entities to maintain consistency and reduce redundancy in data models.

**Impact on Targets:**

* **Consistency:** Ensures uniformity in data models across different risk areas by standardizing supporting metrics.
* **Efficiency:** Reduces the time and effort required to manage repetitive attributes through reusable supporting attributes.

#### 6. **Advanced Analytical Capabilities**

**Relation:**\
Leverage supporting attributes to support advanced analytical operations, such as machine learning models and simulation techniques, by providing necessary context and metrics.

**Impact on Targets:**

* **Enhanced Analytics:** Facilitates the application of complex analytical methods by supplying essential supporting data.
* **Data Accessibility:** Improves the ease of accessing and processing enriched data for sophisticated analyses, enhancing the depth and accuracy of risk assessments.

#### 7. **Scalability and Maintainability**

**Relation:**\
Support scalable data models that can grow with GRIx’s expanding risk assessment needs by efficiently managing supporting attributes.

**Impact on Targets:**

* **Scalability:** Allows GRIx to handle increasing volumes and complexities of risk data through organized supporting metrics.
* **Maintainability:** Simplifies updates and modifications to data models by maintaining consistent and standardized supporting attributes.

***

### Troubleshooting

While the `AddSupportingAttribute` operation is straightforward, certain issues may arise during its implementation. Below are common challenges and their solutions:

#### 1. **Attribute Name Conflicts**

**Issue:**\
The specified `supportingAttribute` name conflicts with an existing attribute or another supporting attribute within the entity.

**Solution:**

* **Rename the Supporting Attribute:** Choose a unique and descriptive name that does not clash with existing attributes or supporting attributes.
* **Check Existing Attributes:** Review the entity to ensure that the chosen supporting attribute name is not already in use.

**Example:**

If attempting to create a supporting attribute named `age_display` but it already exists, rename it to `childAge_display`.

#### 2. **Unsupported Data Types for Supporting Attributes**

**Issue:**\
Attempting to add a supporting attribute with an unsupported data type or one that does not logically support additional context.

**Solution:**

* **Validate Data Types:** Ensure that the data type of the supporting attribute is compatible and suitable for providing additional context to the primary attribute.
* **Logical Consistency:** Confirm that the supporting attribute logically complements the primary attribute.

**Example:**

Avoid adding a supporting attribute of type `float` for a primary attribute that is inherently textual, such as adding a `priorityCode_score` to a `priorityCode_display` attribute.

#### 3. **Incorrect Configuration Syntax**

**Issue:**\
Misconfiguring the projection operation, such as incorrect property names, missing required properties, or invalid JSON syntax.

**Solution:**

* **Validate JSON Structure:** Ensure that the JSON is well-formed and adheres to the required schema.
* **Refer to API Documentation:** Cross-check configurations with the [AddSupportingAttribute API Documentation](https://docs.microsoft.com/en-us/common-data-model/api-reference/addsupportingattribute).

**Example:**

Ensure that `$type` is correctly set to `"addSupportingAttribute"` and that `supportingAttribute` includes all required properties.

```json
{
    "$type": "addSupportingAttribute",
    "supportingAttribute": {
        "name": "email_verified",
        "dataType": "boolean",
        "purpose": "hasA",
        "description": "Indicates whether the email address has been verified.",
        "isReadOnly": true
    },
    "condition": "virtual",
    "explanation": "Adding email_verified to track the verification status of email addresses."
}
```

#### 4. **Supporting Attribute Not Appearing as Expected**

**Issue:**\
After applying the `AddSupportingAttribute` operation, the supporting attribute does not appear in the resolved entity as intended.

**Solution:**

* **Check Operation Order:** Ensure that the `AddSupportingAttribute` operation is applied at the correct stage in the projection pipeline.
* **Verify Conditions:** If a condition is set, confirm that it evaluates to `true` under the current resolution context.
* **Review Trait Assignments:** Ensure that the supporting attribute has been correctly assigned the `is.virtual.attribute` and `is.addedInSupportOf` traits.

**Example:**

If the supporting attribute does not appear, verify that the condition `virtual` is correctly applied and that the supporting attribute's traits are properly assigned.

#### 5. **Conflicting Trait Assignments**

**Issue:**\
The supporting attribute does not properly receive the `is.addedInSupportOf` trait, affecting its recognition and usage in analytical operations.

**Solution:**

* **Verify Trait Assignment:** Ensure that the operation correctly assigns the `is.addedInSupportOf` trait to the supporting attribute.
* **Manual Trait Assignment:** If necessary, manually assign the trait to ensure proper functionality.

**Example:**

```json
{
    "$type": "addSupportingAttribute",
    "supportingAttribute": {
        "name": "projectStatus_display",
        "dataType": "localizedDisplayText",
        "purpose": "hasA",
        "description": "Provides the display text for the projectStatus attribute.",
        "isReadOnly": true
    },
    "explanation": "Adding projectStatus_display to provide display text for projectStatus."
}
```

Ensure that during resolution, the `is.addedInSupportOf` trait correctly points to the `projectStatus` attribute.

#### 6. **Virtual Attributes Causing Performance Issues**

**Issue:**\
Virtual supporting attributes may impact performance if not managed correctly, especially when dealing with large datasets.

**Solution:**

* **Optimize Conditions:** Use the `condition` property to limit the creation of virtual attributes only when necessary.
* **Evaluate Necessity:** Assess whether the supporting attribute provides sufficient value to warrant its inclusion, considering potential performance implications.

**Example:**

```json
{
    "$type": "addSupportingAttribute",
    "supportingAttribute": {
        "name": "email_verified",
        "dataType": "boolean",
        "purpose": "hasA",
        "description": "Indicates whether the email address has been verified.",
        "isReadOnly": true
    },
    "condition": "isEmailVerificationEnabled",
    "explanation": "Adding email_verified only if email verification is enabled."
}
```

***

### Impact on GRIx Areas of Focus and Targets

The `AddSupportingAttribute` operation significantly impacts various areas of focus and targets within GRIx by enhancing data model organization, promoting attribute reusability, and supporting comprehensive risk analysis. Below is an analysis of how this operation relates to specific GRIx areas and targets.

#### 1. **Risk Assessment and Prioritization**

**Relation:**\
Group and count risk-related attributes to enable focused analysis and prioritization based on the number and severity of identified risks.

**Impact on Targets:**

* **Enhanced Clarity:** Facilitates clearer understanding of the risk landscape by providing additional context through supporting attributes.
* **Improved Analysis:** Streamlines the process of risk scoring and prioritization by enriching primary risk attributes with descriptive metadata.

#### 2. **Mitigation Strategies and Implementation**

**Relation:**\
Add supporting attributes to mitigation measures to evaluate the breadth and effectiveness of risk reduction efforts.

**Impact on Targets:**

* **Strategic Planning:** Enhances the ability to plan and allocate resources for mitigation efforts by providing supporting metrics.
* **Efficiency:** Reduces redundancy and simplifies the management of mitigation measures through enriched data attributes.

#### 3. **Climate Impact Assessment and Environmental Risk**

**Relation:**\
Use supporting attributes to quantify and provide context for environmental impact metrics, supporting detailed demographic and resource allocation analyses.

**Impact on Targets:**

* **Comprehensive Analysis:** Enables multi-level environmental impact assessments by providing both primary and supporting data points.
* **Data Integrity:** Ensures that all relevant climate data is organized and accessible for thorough analysis through supporting attributes.

#### 4. **Data Governance and Compliance**

**Relation:**\
Add supporting attributes to track compliance checks, regulatory requirements, and data provenance, ensuring adherence to necessary standards.

**Impact on Targets:**

* **Regulatory Compliance:** Simplifies the process of ensuring that data models comply with relevant regulations by providing supporting compliance metrics.
* **Data Provenance:** Enhances the ability to track data origins and changes over time through supporting attributes, ensuring data integrity and traceability.

#### 5. **Operational Efficiency and Data Reusability**

**Relation:**\
Promote reusability of supporting attributes across multiple entities to maintain consistency and reduce redundancy in data models.

**Impact on Targets:**

* **Consistency:** Ensures uniformity in data models across different risk areas by standardizing supporting metrics.
* **Efficiency:** Reduces the time and effort required to manage repetitive attributes through reusable supporting attributes.

#### 6. **Advanced Analytical Capabilities**

**Relation:**\
Leverage supporting attributes to support advanced analytical operations, such as machine learning models and simulation techniques, by providing necessary context and metrics.

**Impact on Targets:**

* **Enhanced Analytics:** Facilitates the application of complex analytical methods by supplying essential supporting data.
* **Data Accessibility:** Improves the ease of accessing and processing enriched data for sophisticated analyses, enhancing the depth and accuracy of risk assessments.

#### 7. **Scalability and Maintainability**

**Relation:**\
Support scalable data models that can grow with GRIx’s expanding risk assessment needs by efficiently managing supporting attributes.

**Impact on Targets:**

* **Scalability:** Allows GRIx to handle increasing volumes and complexities of risk data through organized supporting metrics.
* **Maintainability:** Simplifies updates and modifications to data models by maintaining consistent and standardized supporting attributes.

***

The `AddSupportingAttribute` operation is a powerful feature within GRIx that enhances data model organization, promotes attribute reusability, and enriches primary attributes with additional context and metadata. By intelligently adding supporting attributes, data architects and risk analysts can create more maintainable, scalable, and insightful data models, which are essential for effective global risk assessment and management.

Adhering to best practices such as consistent naming conventions, strategic insertion, appropriate use of conditions, and thorough documentation ensures that the use of `AddSupportingAttribute` contributes positively to the overall integrity and efficiency of the GRIx data ecosystem. As GRIx continues to evolve, leveraging such projection operations will be crucial in adapting to increasingly complex risk scenarios and data requirements.

***

### Further Reading and Resources

* [Microsoft Common Data Model Documentation](https://docs.microsoft.com/en-us/common-data-model/)
* [Common Data Model Repository on GitHub](https://github.com/microsoft/CommonDataModel)
* [CDM Resolution Guidance](https://docs.microsoft.com/en-us/common-data-model/resolution-guidance)
* [AddSupportingAttribute API Reference](https://docs.microsoft.com/en-us/common-data-model/api-reference/addsupportingattribute)
* [Explainable AI (XAI) Best Practices](https://www.microsoft.com/en-us/research/project/explainable-ai/)
* [High-Performance Computing with Azure](https://docs.microsoft.com/en-us/azure/architecture/hpc/)
* [Azure Machine Learning Documentation](https://docs.microsoft.com/en-us/azure/machine-learning/)
* [SHAP Documentation](https://shap.readthedocs.io/en/latest/)
* [LIME Documentation](https://lime-ml.readthedocs.io/en/latest/)
* [Monte Carlo Simulation Techniques](https://en.wikipedia.org/wiki/Monte_Carlo_method)
* [Granger Causality](https://en.wikipedia.org/wiki/Granger_causality)
* [Azure Purview Documentation](https://docs.microsoft.com/en-us/azure/purview/)
* [Power BI Documentation](https://docs.microsoft.com/en-us/power-bi/)
* [Azure Data Factory Documentation](https://docs.microsoft.com/en-us/azure/data-factory/)
* Qiskit Documentation
* HashiCorp Sentinel Documentation
* AnyLogic Documentation
* MATLAB Documentation
* Simulink Documentation


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.therisk.global/nexus-paradigm/global-risks-index-grix/common-data-model/projection/add-supporting-attribute.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.