Artifact Attribute

Understanding Projections

Projections in CDM are mechanisms that allow for the customization of how logical entity definitions are transformed into physical schemas. They enable selective manipulation of attributes, such as inclusion, exclusion, renaming, and adding new attributes. Projections are essential for adapting data models to various storage formats, analytical needs, and organizational standards without altering the underlying logical definitions.

In GRIx, projections facilitate the creation of multiple resolved schemas from a single logical entity, ensuring that data can be efficiently stored, processed, and analyzed across different platforms and use cases.

Overview of the AddArtifactAttribute Operation

What is AddArtifactAttribute?

The AddArtifactAttribute operation is a projection operation in CDM that allows users to add a custom attribute to the final resolved entity. This operation is particularly useful for inserting metadata or additional information that is not originally part of the base entity definition. Currently, AddArtifactAttribute supports adding type attributes, which can serve various purposes such as categorization, tagging, or defining relationships.

Purpose in GRIx

Within GRIx, the AddArtifactAttribute operation is leveraged to enhance entities by:

  • Introducing Metadata: Adding attributes that provide additional context or metadata about the entity.

  • Defining Relationships: Inserting type attributes that specify relationships between different entities, aiding in more complex risk modeling.

  • Customizing Schemas: Tailoring the resolved entity to include attributes that align with specific analytical or storage requirements.

By allowing the dynamic addition of attributes, AddArtifactAttribute contributes to the flexibility and extensibility of data models in GRIx.

Functionality and Behavior

How AddArtifactAttribute Works

The AddArtifactAttribute operation modifies the attribute list of an entity during the resolution process. It operates by appending or prepending a user-defined attribute to the existing set of resolved attributes based on configuration parameters. Here's a step-by-step breakdown of its functionality:

  1. Input Attributes: The operation receives the current list of resolved attributes from the source entity or previous operations in the projection pipeline.

  2. Defining the New Attribute: Users specify the new attribute to be added, including its name and data type. Currently, only type attributes are supported, which can be used to denote categorization or relationship types.

  3. Insertion Point: Based on the insertAtTop flag, the new attribute is either added at the beginning or the end of the attribute list.

  4. Resulting Attributes: The final resolved entity includes the newly added attribute alongside the original attributes, maintaining the specified order.

Default Behavior

  • Insertion Position: By default, if the insertAtTop property is not set or is false, the new attribute is appended to the end of the attribute list.

  • Type Enforcement: Only type attributes are supported, ensuring consistency in how additional attributes are utilized within the data model.

API Reference

For detailed technical specifications and additional configuration options, refer to the AddArtifactAttribute API Documentation.

Configuration Options

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

Mandatory Properties

  • $type: Specifies the operation type. For AddArtifactAttribute, this should be set to "addArtifactAttribute".

  • newAttribute: An object defining the attribute to be added. It must include:

    • name: The name of the new attribute.

    • dataType: The data type of the new attribute (currently, only type attributes are supported).

Optional Properties

  • insertAtTop: A boolean flag that determines the insertion point of the new attribute.

    • true: Inserts the new attribute at the beginning of the attribute list.

    • false or omitted: Appends the new attribute to the end of the attribute list.

  • condition: A logical expression that determines whether the operation should execute.

  • 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 "addArtifactAttribute".

Yes

newAttribute

object

Defines the new attribute to add, including name and dataType.

Yes

insertAtTop

boolean

Determines where to insert the new attribute. Defaults to false if not specified.

No

condition

string

A logical expression that determines whether the operation should execute.

No

explanation

string

Provides a description of what the operation does. Useful for documentation and maintenance purposes.

No

Example Configuration

{
    "$type": "addArtifactAttribute",
    "newAttribute": {
        "name": "additionalInfo",
        "dataType": "string"
    },
    "insertAtTop": true,
    "condition": "isArray",
    "explanation": "Adding additionalInfo attribute at the top when the entity is an array."
}

Explanation:

  • $type: Identifies the operation as addArtifactAttribute.

  • newAttribute: Defines an attribute named additionalInfo of type string.

  • insertAtTop: Indicates that the new attribute should be inserted at the beginning of the attribute list.

  • condition: Specifies that the operation should only execute if the entity is an array.

  • explanation: Describes the purpose of the operation for future reference.

Detailed Examples

To provide a clearer understanding of how the AddArtifactAttribute operation functions within GRIx, the following examples illustrate its application in various contexts.

Example 1: Using AddArtifactAttribute on an Entity Attribute

Scenario: Enhancing the Person entity by adding a newName type attribute to include additional identification information.

Base Entity Definition:

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

Projection with AddArtifactAttribute:

{
    "name": "PersonInfo",
    "entity": {
        "source": "Person",
        "operations": [
            {
                "$type": "addArtifactAttribute",
                "newAttribute": {
                    "name": "newName",
                    "dataType": "string"
                },
                "explanation": "Adding newName attribute for additional identification."
            }
        ]
    }
}

Resulting Resolved PersonInfo Entity:

Attribute Name

Data Type

name

string

age

integer

address

string

phoneNumber

string

email

string

newName

string

Explanation:

  • The AddArtifactAttribute operation adds a new attribute newName of type string to the PersonInfo entity.

  • Since insertAtTop is not specified, newName is appended to the end of the attribute list.

Example 2: Using AddArtifactAttribute When Extending an Entity

Scenario: Creating a Child entity that extends the Person entity and adds a newName type attribute for additional naming conventions.

Base Entity Definition:

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

Child Entity Definition with AddArtifactAttribute:

{
    "entityName": "Child",
    "extendsEntity": {
        "source": "Person",
        "operations": [
            {
                "$type": "addArtifactAttribute",
                "newAttribute": {
                    "name": "newName",
                    "dataType": "string"
                },
                "explanation": "Adding newName attribute inherited from Person."
            }
        ]
    },
    "hasAttributes": []
}

Resulting Resolved Child Entity:

Attribute Name

Data Type

name

string

age

integer

address

string

phoneNumber

string

email

string

newName

string

Explanation:

  • The Child entity inherits all attributes from the Person entity.

  • The AddArtifactAttribute operation adds the newName attribute to the inherited attribute list.

  • Since insertAtTop is not specified, newName is appended at the end.

Example 3: Using AddArtifactAttribute on a Type Attribute

Scenario: Enhancing the PersonInfo entity by adding a newNickname type attribute at the top of the attribute list to prioritize it.

Entity Definition with AddArtifactAttribute:

{
    "entityName": "PersonInfo",
    "extendsEntity": "CdmEntity",
    "hasAttributes": [
        {
            "name": "legalName",
            "dataType": "string"
        },
        {
            "name": "nickname",
            "dataType": "string",
            "projection": {
                "operations": [
                    {
                        "$type": "addArtifactAttribute",
                        "newAttribute": {
                            "name": "newNickname",
                            "dataType": "string"
                        },
                        "insertAtTop": true,
                        "explanation": "Adding newNickname attribute before nickname for prioritization."
                    }
                ]
            }
        }
    ]
}

Resulting Resolved PersonInfo Entity:

Attribute Name

Data Type

legalName

string

newNickname

string

nickname

string

Explanation:

  • The PersonInfo entity includes a nickname attribute.

  • The AddArtifactAttribute operation adds a newNickname attribute with insertAtTop set to true.

  • As a result, newNickname is inserted before nickname, becoming the new second attribute in the list.

Best Practices

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

1. Consistent Naming Conventions

  • Clarity: Ensure that the names of added attributes clearly reflect their purpose.

  • Avoid Conflicts: Use unique and descriptive names to prevent conflicts with existing attributes.

Example:

Instead of naming the new attribute newName, consider a more descriptive name like additionalIdentifier or secondaryName.

2. Strategic Insertion

  • Logical Ordering: Use the insertAtTop flag judiciously to maintain a logical flow of attributes, especially when the new attribute is critical for downstream processes.

  • Prioritization: Place important metadata attributes at the top to ensure they are easily accessible.

Example:

If an attribute provides essential classification information, inserting it at the top can enhance readability and usability.

3. Use Conditions Appropriately

  • Contextual Addition: Leverage the condition property to add 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:

{
    "$type": "addArtifactAttribute",
    "newAttribute": {
        "name": "status",
        "dataType": "string"
    },
    "condition": "isActive",
    "explanation": "Adding status attribute only if the entity is active."
}

4. Documentation and Explanation

  • Explain Purpose: Utilize the explanation property to document why an attribute is being added, aiding future maintenance and onboarding.

  • Maintain Clarity: Ensure that explanations are clear and concise, providing sufficient context without unnecessary verbosity.

Example:

{
    "$type": "addArtifactAttribute",
    "newAttribute": {
        "name": "dataSource",
        "dataType": "string"
    },
    "insertAtTop": true,
    "explanation": "Adding dataSource to track the origin of the data."
}

5. Validate Resolved Entities

  • Consistency Checks: After applying projections, validate the resolved entity to ensure that all 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 PersonInfo entity after adding newNickname.

var resolvedEntity = await corpus.CreateResolvedEntityAsync("PersonInfo", "default", "addArtifactAttribute");
resolvedEntity.Validate();

6. Minimize Redundancy

  • Avoid Duplicates: Ensure that added attributes do not duplicate existing attributes unless intentionally overriding or extending them.

  • Efficient Use: Add attributes only when necessary to maintain a streamlined and efficient data model.

Example:

Before adding newNickname, confirm that there isn't already an attribute serving a similar purpose to prevent redundancy.

Common Use Cases in GRIx

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

1. Adding Metadata Attributes

Purpose: To include additional information about the entity, such as data source, version, or timestamp.

Example:

{
    "$type": "addArtifactAttribute",
    "newAttribute": {
        "name": "dataSource",
        "dataType": "string"
    },
    "explanation": "Tracks the origin of the data."
}

2. Defining Relationship Types

Purpose: To specify the nature of relationships between entities, facilitating more nuanced risk modeling.

Example:

{
    "$type": "addArtifactAttribute",
    "newAttribute": {
        "name": "relationshipType",
        "dataType": "string"
    },
    "insertAtTop": true,
    "explanation": "Defines the type of relationship between RiskEntity and MitigationMeasure."
}

3. Categorization and Tagging

Purpose: To categorize entities into different classes or groups, aiding in segmented analysis.

Example:

{
    "$type": "addArtifactAttribute",
    "newAttribute": {
        "name": "category",
        "dataType": "string"
    },
    "explanation": "Categorizes the entity for segmented risk analysis."
}

4. Enhancing Analytical Capabilities

Purpose: To introduce attributes that support advanced analytical functions, such as flags or indicators used in machine learning models.

Example:

{
    "$type": "addArtifactAttribute",
    "newAttribute": {
        "name": "isHighRisk",
        "dataType": "boolean"
    },
    "explanation": "Flag indicating whether the entity is considered high risk."
}

Troubleshooting

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

1. Attribute Name Conflicts

Issue: The new attribute's name conflicts with an existing attribute in the entity.

Solution:

  • Rename the Attribute: Choose a unique name that does not clash with existing attributes.

  • Review Inheritance and Attribute Groups: Ensure that inherited attributes or those from attribute groups do not introduce naming conflicts.

Example:

If attempting to add an attribute named name which already exists, rename it to fullName or another distinctive identifier.

2. Unsupported Data Types

Issue: Specifying a data type that is not supported by the AddArtifactAttribute operation.

Solution:

  • Verify Supported Data Types: Ensure that only type attributes are being added as per current operation support.

  • Update CDM Definitions: If necessary, extend CDM to support additional data types in future releases.

Example:

Attempting to add a complex data type may result in errors. Stick to primitive or supported type attributes.

3. Incorrect Configuration

Issue: Misconfiguring the projection operation, such as incorrect property names or values.

Solution:

  • Validate JSON Structure: Ensure that all required properties are correctly named and appropriately valued.

  • Refer to API Documentation: Cross-check configurations with the AddArtifactAttribute API Documentation.

Example:

Ensure that the $type is correctly set to "addArtifactAttribute" and that newAttribute includes both name and dataType.

4. Conditional Execution Failures

Issue: The condition specified for the operation evaluates to false, preventing the attribute from being added.

Solution:

  • Review Condition Logic: Ensure that the condition accurately reflects when the attribute should be added.

  • Test Conditions Separately: Validate each part of the condition to identify which segment is causing the evaluation to fail.

Example:

If the condition is "isArray && depth < maxDepth", verify that both isArray is true and depth is indeed less than maxDepth during execution.

The AddArtifactAttribute operation is a powerful tool within GRIx, enabling the dynamic enhancement of entity definitions by adding custom attributes tailored to specific analytical and storage requirements. Data architects and risk analysts can leverage this operation to create more flexible, informative, and robust data models by understanding its functionality, configuration options, and best practices.

Effective use of AddArtifactAttribute contributes to the overall integrity and scalability of GRIx’s risk assessment capabilities, ensuring that data models remain adaptable to evolving analytical needs and storage technologies.

Further Reading and Resources

PreviousExclude Attributes

Last updated

Was this helpful?