Entity

Understanding Logical Entity Definitions

A Logical Entity Definition in CDM represents an abstract blueprint of real-world entities, encapsulating their attributes, relationships, and inherent semantics without being tied to any specific data storage format or schema. Within GCRIx, logical entities serve as the foundation for modeling complex climate risk factors and their interdependencies.

Key Components of Logical Entity Definitions:

  • Entity Inheritance: Allows entities to extend other entities, inheriting their attributes and behaviors. This promotes logical grouping and lineage.

  • Entity-Typed Attributes: Attributes that are themselves entities, enabling the modeling of complex, nested data structures.

  • Attribute Groups: Collections of common attributes that can be reused across multiple entities, ensuring consistency and reducing redundancy.

  • Custom Data Types: Define bespoke data types that extend existing types with additional traits or constraints specific to climate risk modeling.

Understanding how to define and resolve these logical entities is crucial for maintaining a robust and flexible data model within GCRIx.

The Default Resolution Behavior

When a logical entity definition references other object definitions, the resolution process in CDM examines and inlines these references to produce a Resolved Entity Definition. In GCRIx, this process ensures that all dependencies are appropriately handled, resulting in a concrete entity definition optimized for specific storage schemas and analytical purposes.

Steps in the Default Resolution Process:

  1. Inlining References: Replace references to other entities, attribute groups, or data types with actual attribute definitions using primitive data formats and trait references.

  2. Handling Inheritance: Incorporate attributes from base entities when an entity extends another, maintaining the inheritance hierarchy.

  3. Processing Attribute Groups: Expand attribute groups by inserting their constituent attributes into the entity.

  4. Renaming Attributes: Prevent naming conflicts by renaming attributes from referenced entities or groups using a predefined naming convention (e.g., {attributeName}{EntityName}).

Key Points of Default Resolution:

  • Sequential Attribute Processing: Attributes are processed in the order they are defined within the entity, including those from inheritance and attribute groups.

  • Attribute Merging: Duplicate attributes (by name) are merged, combining or replacing traits as necessary to reflect the most recent definitions.

  • Complex Types Handling: Entity-typed attributes are treated as complex data types, with their sub-attributes appropriately renamed and inlined to avoid collisions.

Example:

Consider a Student entity that extends a Person entity and includes an attribute group ContactInfo. During resolution:

  • Attributes from Person are inherited and inlined.

  • Attributes from ContactInfo are expanded and added to Student.

  • Any naming conflicts are resolved by renaming attributes (e.g., email becomes ContactInfoEmail).

The resolved Student entity will contain a comprehensive set of attributes without external dependencies, ensuring it can be programmatically utilized or persisted independently within GCRIx.

The Three Flavors of Entity Definitions

Within GCRIx, logical entities can be categorized into three distinct types, each serving a unique purpose in the data modeling process:

  1. Purely Logical Entities

  2. Resolved (Data Layout–Specific) Entities

  3. Guidance Entities

1. Purely Logical Entities

Definition: Abstract representations focused on conveying the semantic meaning of data without constraints related to storage or schema.

Characteristics:

  • Entity Inheritance: Utilize the extends property to inherit attributes from base entities, enabling logical grouping and lineage.

  • Semantic Richness: Employ semantically meaningful data types and purposes to encode the meanings, structures, and constraints of attributes.

  • Attribute Groups: Reference attribute groups to include common sets of attributes, promoting reusability.

  • Entity-Typed Attributes: Include attributes that are themselves entities, allowing for complex, nested data structures.

  • No Resolution Guidance: Do not contain sections or instructions related to data resolution or storage schema.

Use Case: Defining a Vehicle entity that extends Asset and includes a Specifications attribute group to encapsulate common specification attributes like EngineType, Horsepower, etc.

2. Resolved (Data Layout–Specific) Entities

Definition: Concrete entities tailored to specific data storage schemas or formats, designed to be directly understood and utilized without requiring further resolution.

Characteristics:

  • No Inheritance: Do not inherit attributes from other entities; all attributes are explicitly defined.

  • No Complex Types: Avoid using entity-typed attributes; instead, all attributes use primitive data types.

  • No Attribute Groups: Do not reference attribute groups; all attributes are directly included in the entity.

  • Explicit Traits: All traits are explicitly listed on the entity and its attributes without relying on inherited or referenced traits.

  • AttributeContext Section: May include an AttributeContext graph that explains the resolution process, attribute sources, and trait applications.

Use Case: Defining a ResolvedVehicle entity optimized for SQL storage, with all attributes explicitly listed and no dependencies on external definitions or attribute groups.

3. Guidance Entities

Definition: Entities that act as templates or instructions, guiding the resolution process of logical entities into specific physical schemas.

Characteristics:

  • Inheritance from Logical Entities: Extend purely logical entities to inherit their semantic definitions.

  • Resolution Guidance Sections: Contain sections that offer instructions on how to resolve attributes, handle inheritance, and apply specific resolution behaviors.

  • Combined Semantics and Guidance: Merge the semantic definitions of logical entities with resolution instructions, potentially limiting flexibility.

  • Resolution Behavior Control: Provide explicit directives to control how logical definitions are transformed into resolved entities.

Use Case: Creating a FinancialEntityGuidance entity that extends FinancialEntity and includes resolution instructions to flatten certain attributes and rename others for a denormalized storage schema.

Note: While guidance entities provide a way to embed resolution instructions within entity definitions, they can sometimes lead to rigid or obscure behaviors. It's generally recommended to keep logical and guidance aspects separate to maintain flexibility and clarity.

Directives, Guidance, and Resolved Shapes

A fundamental requirement in GCRIx is the ability to represent different optimal storage layouts from a single semantic, logical model. Depending on the storage system—whether relational databases (e.g., SQL), flat files for machine learning, or big data systems using JSON or Parquet—the resolved entity definitions need to adapt accordingly.

Objectives:

  • Multiple Storage Layouts: Support various data storage schemas while maintaining a single logical entity definition.

  • Shared Semantic Definitions: Preserve the semantic meaning of entities across different storage schemas.

  • Transformable Resolutions: Enable transformations from one storage layout to another based on specific directives or instructions.

How Directives Influence Resolution

Directives are instructions passed to the CreateResolvedEntityAsync API that modify the default resolution behavior. They influence how entity-typed attributes are handled, whether attributes are embedded or referenced, and how relationships are represented.

Common Directives:

  1. None (Default):

    • Behavior: Treats entity types as complex data types.

    • Resolution: Inlines sub-attributes with renamed identifiers to prevent collisions. If marked as an array, attributes are repeated accordingly.

  2. ReferenceOnly:

    • Behavior: Attributes are referenced via foreign keys instead of being fully inlined.

    • Resolution: Only primary key attributes are included, renamed to indicate foreign key relationships.

  3. Normalized:

    • Behavior: Assumes one-to-many or many-to-many relationships are handled via separate linked entities.

    • Resolution: Avoids adding foreign keys directly and relies on correlation entities for many-to-many relationships.

  4. Structured:

    • Behavior: Embeds attributes into grouped structures to maintain complex or nested data.

    • Resolution: Attributes are organized into groups, avoiding name conflicts and supporting hierarchical data representations.

Default Resolution Behavior:

When no directives are provided, the default behavior typically aligns with a relational schema, applying ReferenceOnly and Normalized directives to maintain data normalization and avoid redundancy.

Example: Representing a Business and Its Owner

Consider the relationship between a SmallBusiness entity and its Owner, who is a Person. There are multiple ways to resolve this relationship based on the directives:

  1. Default (ReferenceOnly + Normalized):

    • Resolution: Include a OwnerId foreign key in the SmallBusiness entity, referencing the Person entity.

    • Outcome:

      {
  "entityName": "SmallBusiness",
  "attributes": [
    {
      "name": "BusinessId",
      "dataType": "string"
    },
    {
      "name": "BusinessName",
      "dataType": "string"
    },
    {
      "name": "OwnerId",
      "dataType": "string"
    }
  ]
}

  2. Inline Attributes (No Directives or Structured):

    • Resolution: Embed Person attributes directly within SmallBusiness, renaming them to avoid conflicts.

    • Outcome:

      {
  "entityName": "SmallBusiness",
  "attributes": [
    {
      "name": "BusinessId",
      "dataType": "string"
    },
    {
      "name": "BusinessName",
      "dataType": "string"
    },
    {
      "name": "OwnerName",
      "dataType": "string"
    },
    {
      "name": "OwnerBirthdate",
      "dataType": "date"
    }
  ]
}

  3. Nested Object (Structured):

    • Resolution: Embed Person as a nested object within SmallBusiness.

    • Outcome:

      {
  "entityName": "SmallBusiness",
  "attributes": [
    {
      "name": "BusinessId",
      "dataType": "string"
    },
    {
      "name": "BusinessName",
      "dataType": "string"
    },
    {
      "name": "Owner",
      "dataType": "Person",
      "attributes": [
        {
          "name": "PersonId",
          "dataType": "string"
        },
        {
          "name": "Name",
          "dataType": "string"
        },
        {
          "name": "Birthdate",
          "dataType": "date"
        }
      ]
    }
  ]
}

Conclusion:

Directives provide the flexibility to adapt logical entity definitions to various storage schemas without altering the underlying semantic model. By carefully selecting and applying directives, GCRIx ensures that data models are both semantically rich and optimized for their intended storage and analytical environments.

Projections Overview

Projections in CDM offer a mechanism to customize how logical entity definitions are resolved into physical schemas. They enable selective inclusion or exclusion of attributes, control over how entity-typed attributes are handled, and the ability to define derived data shapes from a common logical model.

Purpose of Projections

  • Selective Attribute Inclusion: Choose which attributes from a base entity or attribute group to include or exclude.

  • Attribute Manipulation: Rename, reorder, or group attributes to fit specific storage or analytical requirements.

  • Complex Resolutions: Control how entity-typed or polymorphic attributes are resolved, either by inlining, referencing, or structuring them.

  • Derived Schemas: Create multiple resolved schemas from a single logical entity definition, tailored to different use cases or storage systems.

Structure of a Projection Object

A projection object is defined using JSON and consists of the following components:

{
  "source": <string> | <Projection> | <EntityDefinition>,
  "condition": <string>,
  "runSequentially": <bool>,
  "operations": [<Operation1>, <Operation2>, ...]
}

  • source: Specifies the origin of attributes, which can be:

    • A string referencing an existing entity.

    • Another projection object, enabling nested projections.

    • An inline entity definition.

  • condition: A logical expression determining whether the projection should be executed based on predefined tokens and operators.

  • runSequentially: A boolean indicating whether operations should be executed in sequence, affecting how each operation processes attributes.

  • operations: A list of operations that manipulate the attribute set, such as renaming, excluding, or combining attributes.

Applying Projections

Projections can be applied in various contexts within an entity definition:

  1. Extending an Entity:

    • Customize how attributes are inherited and resolved when an entity extends another.

    • Example:

      {
  "entityName": "Child",
  "extendsEntity": {
    "source": "Person",
    "operations": [ /* Operations */ ]
  }
}

  2. Entity-Typed Attribute:

    • Define how an attribute that references another entity should be resolved.

    • Example:

      {
  "name": "child",
  "entity": {
    "source": "Parent",
    "operations": [ /* Operations */ ]
  }
}

  3. Data-Typed Attribute:

    • Customize the resolution of attributes that use data types, potentially altering their format or constraints.

    • Example:

      {
  "name": "name",
  "dataType": "string",
  "projection": {
    "operations": [ /* Operations */ ]
  }
}

Note: Using projections allows for granular control over the resolution process, enabling the creation of tailored schemas that meet specific storage or analytical needs without duplicating or altering the original logical entity definitions.

Operations in Projections

Operations are the core components of projections, defining how attributes are manipulated during the resolution process. Each operation performs a specific transformation or action on the attribute set, allowing for complex and customizable resolutions.

Common Operation Properties

All operations share some fundamental properties:

{
  "$type": <string>,          // The type of operation (e.g., "renameAttributes")
  "condition": <string>,     // Optional: Condition under which the operation should execute
  "explanation": <string>,   // Optional: Description of what the operation does
  "sourceInput": <bool>      // Optional: If true, the operation receives the original input attributes
}

  • $type: Specifies the operation type, determining its behavior.

  • condition: A logical expression that dictates whether the operation should be executed.

  • explanation: Provides context or rationale for the operation.

  • sourceInput: Controls whether the operation uses the initial attribute set or the output from the previous operation in the sequence.

Supported Operations

Below is a table summarizing the supported operations, along with brief descriptions. Each operation type can be explored in more detail through the respective documentation links.

Operation Type ($type)

Description

addAttributeGroup

Wraps a set of input attributes into a named attribute group.

addCountAttribute

Adds a count attribute with a trait indicating the number of array members expected.

addSupportingAttribute

Introduces a virtual attribute that supports another attribute, often used for metadata purposes.

addTypeAttribute

Adds a type indicator for polymorphic entity-typed attributes to specify the type of each record.

arrayExpansion

Creates multiple copies of input attributes, each marked with an ordinal for array handling.

combineAttributes

Merges multiple attributes into a single attribute based on a defined format or rule.

excludeAttributes

Removes specified attributes from the input set, filtering out unwanted data.

includeAttributes

Selectively includes only the specified attributes from the input set, ignoring others.

renameAttributes

Renames attributes based on a provided format string, allowing for dynamic naming conventions.

replaceAsForeignKey

Replaces input attributes with a single foreign key attribute, linking to a related entity.

Detailed Operation Examples

1. Rename Attributes

Purpose: Change the names of attributes to fit specific naming conventions or to avoid conflicts.

Example:

{
  "$type": "renameAttributes",
  "renameFormat": "{a}{M}", 
  "applyTo": ["age", "address"],
  "explanation": "Renaming age to ageM and address to addressM to avoid naming conflicts."
}

Explanation: This operation renames the age attribute to ageM and address to addressM, following the {a}{M} format where {a} is the original attribute name and {M} is an additional modifier. This helps in avoiding naming conflicts when attributes are inherited or merged from multiple sources.

2. Exclude Attributes

Purpose: Remove unwanted attributes from the entity during resolution.

Example:

{
  "$type": "excludeAttributes",
  "excludeAttributes": ["middleName", "nickname"],
  "explanation": "Excluding middleName and nickname as they are not relevant for the resolved entity."
}

Explanation: This operation removes the middleName and nickname attributes from the entity, ensuring they are not included in the resolved entity definition. This streamlines the entity by omitting unnecessary or sensitive information.

3. Combine Attributes

Purpose: Merge multiple attributes into a single attribute, often to create composite fields.

Example:

{
  "$type": "combineAttributes",
  "combineFormat": "{firstName} {lastName}",
  "combineFrom": ["firstName", "lastName"],
  "combineTo": "fullName",
  "explanation": "Combining firstName and lastName into a single fullName attribute for simplicity."
}

Explanation: This operation combines firstName and lastName into a new attribute called fullName, concatenating their values with a space in between. This reduces the number of attributes and simplifies data representation.

4. Replace As Foreign Key

Purpose: Replace a set of attributes with a single foreign key reference to another entity.

Example:

{
  "$type": "replaceAsForeignKey",
  "reference": "manager",
  "replaceWith": {
    "name": "managerId",
    "dataType": "entityId"
  },
  "explanation": "Replacing manager details with a managerId foreign key to reference the Person entity."
}

Explanation: This operation replaces the manager attribute with a managerId foreign key, linking to the related Person entity's entityId. This maintains referential integrity while simplifying the entity structure.

Condition Handling in Projections

Conditions in projections determine whether specific operations should be executed based on predefined tokens and logical expressions. This conditional execution allows for dynamic and context-sensitive transformations during entity resolution.

Condition Properties

  • condition: A logical expression evaluated against a set of tokens and operators.

  • Tokens: Predefined variables representing certain states or properties (e.g., isArray, depth).

  • Operators: Logical (&&, ||), comparison (==, !=, <, >, <=, >=), and negation (!).

Available Tokens

Token Name

Type

Description

always

Bool

Equivalent to true.

cardinality.maximum

Integer

The maximum cardinality set on the attribute; null if not set.

cardinality.minimum

Integer

The minimum cardinality set on the attribute; null if not set.

depth

Integer

The current depth of the entity; increments when following an entity attribute.

false

Bool

Equivalent to false.

isArray

Bool (directive)

true if the isArray directive is present in the resolution directives.

maxDepth

Integer

The maximum depth specified in the ResolveOptions object.

noMaxDepth

Bool (directive)

true if the noMaxDepth directive is present in the resolution directives.

normalized

Bool (directive)

true if the normalized directive is present in the resolution directives.

referenceOnly

Bool (directive)

true if the referenceOnly directive is present in the resolution directives.

structured

Bool (directive)

true if the structured directive is present in the resolution directives.

true

Bool

Equivalent to true.

virtual

Bool (directive)

true if the virtual directive is present in the resolution directives.

Available Operators

Operator Name

Symbol

Example Expression

And

&&

normalized && referenceOnly

Equal

==

depth == 1

Not Equal

!=

structured != true

Greater Than

>

cardinality.maximum > 1

Greater Than or Equal

>=

cardinality.maximum >= 2

Less Than

<

depth < 3

Less Than or Equal

<=

depth <= 2

Or

`

Not

!

!referenceOnly

Example Condition Expressions

  1. Simple Condition:

    "condition": "isArray && depth < maxDepth"

    Explanation: Executes the operation only if the attribute is an array and the current depth is less than the maximum allowed depth.

  2. Complex Condition:

    "condition": "(!normalized || cardinality.maximum <= 1) && (referenceOnly || noMaxDepth || (depth > maxDepth))"

    Explanation: The operation runs if either the entity is not normalized or the maximum cardinality is less than or equal to one, and either it is reference-only, has no maximum depth, or the current depth exceeds the maximum allowed depth.

Practical Example

Scenario: Rename the age attribute to yearsOld only if the attribute is not part of a normalized schema.

Projection Operation:

{
  "$type": "renameAttributes",
  "renameFormat": "yearsOld",
  "applyTo": ["age"],
  "condition": "!normalized",
  "explanation": "Renaming age to yearsOld when not in a normalized schema."
}

Explanation: This operation will rename the age attribute to yearsOld only if the normalized directive is not present during the resolution process. This allows for dynamic adjustment based on the context of the resolution.

Best Practices for Resolving Logical Entities

Effective resolution of logical entities in CDM is crucial for maintaining data integrity, scalability, and interoperability within GCRIx. Adhering to best practices ensures that resolved entities are optimized for their intended storage schemas and analytical purposes.

1. Maintain Clear Separation Between Logical and Physical Models

  • Logical Entities: Focus on semantic definitions without tying them to specific storage schemas.

  • Resolved Entities: Tailor to specific storage requirements using projections and directives.

Benefit: Ensures flexibility in adapting to different storage systems without altering the core semantic definitions.

2. Leverage Attribute Groups for Reusability

  • Define Common Attributes: Use attribute groups to encapsulate sets of commonly used attributes.

  • Reference Attribute Groups: Include attribute groups in multiple entities to promote consistency and reduce redundancy.

Example:

{
  "attributeGroupName": "ContactInfo",
  "attributes": [
    {
      "name": "email",
      "dataType": "string"
    },
    {
      "name": "phoneNumber",
      "dataType": "string"
    }
  ]
}

Usage:

{
  "entityName": "Person",
  "hasAttributes": [
    {
      "attributeGroup": "ContactInfo"
    },
    {
      "name": "firstName",
      "dataType": "string"
    },
    {
      "name": "lastName",
      "dataType": "string"
    }
  ]
}

3. Utilize Projections for Custom Resolutions

  • Selective Inclusion/Exclusion: Use projections to include only relevant attributes or exclude unnecessary ones.

  • Attribute Manipulation: Rename, combine, or group attributes to fit specific storage or analytical needs.

  • Complex Resolutions: Handle entity-typed or polymorphic attributes with tailored operations.

Example:

{
  "name": "PersonInfo",
  "entity": {
    "source": "Person",
    "runSequentially": true,
    "operations": [
      {
        "$type": "renameAttributes",
        "renameFormat": "yearsOld", 
        "applyTo": ["age"],
        "explanation": "Renaming age to yearsOld for clarity."
      },
      {
        "$type": "renameAttributes",
        "renameFormat": "homePlace", 
        "applyTo": ["address"],
        "explanation": "Renaming address to homePlace to avoid naming conflicts."
      }
    ]
  }
}

4. Apply Conditional Operations Thoughtfully

  • Contextual Transformations: Use conditions to apply operations only in relevant contexts, enhancing flexibility.

  • Avoid Overcomplicating Conditions: Keep conditions as simple as possible to maintain readability and reduce potential errors.

Example:

{
  "$type": "excludeAttributes",
  "excludeAttributes": ["temporaryField"],
  "condition": "depth < maxDepth",
  "explanation": "Excluding temporaryField when depth is less than maxDepth."
}

5. Document Projections and Operations

  • Comprehensive Documentation: Clearly document each projection and its associated operations to facilitate maintenance and onboarding.

  • Use explanation Fields: Provide descriptions within operations to explain their purpose and expected outcomes.

Example:

{
  "$type": "renameAttributes",
  "renameFormat": "fullName",
  "applyTo": ["firstName", "lastName"],
  "explanation": "Combining firstName and lastName into a single fullName attribute for simplicity."
}

6. Optimize for Performance and Scalability

  • Efficient Operations: Use operations that minimize computational overhead, especially when dealing with large datasets.

  • Limit Depth Levels: Control the depth of nested entities to prevent excessive complexity and potential performance degradation.

Example: Set a maximum depth to prevent deep nesting:

{
  "condition": "depth <= 3",
  "explanation": "Ensuring that the depth does not exceed 3 to maintain performance."
}

7. Test Resolved Entities Thoroughly

  • Validation: Use CDM’s Validate() method to ensure that resolved entities are structurally sound and free of inconsistencies.

  • Sample Data Testing: Apply projections to sample data to verify that resolutions behave as expected.

Example:

var resolvedEntity = await corpus.CreateResolvedEntityAsync("SmallBusiness", "default", "referenceOnly");
resolvedEntity.Validate();

8. Avoid Redundant or Conflicting Operations

  • Order Matters: When running operations sequentially, ensure that each operation's output is compatible with the next.

  • Conflict Resolution: Design projections to prevent operations from conflicting, which can lead to errors or unintended data transformations.

Example: Avoid replacing an attribute before it’s renamed:

{
  "$type": "renameAttributes",
  "renameFormat": "ageInYears",
  "applyTo": ["age"],
  "explanation": "Renaming age to ageInYears for clarity."
},
{
  "$type": "replaceAsForeignKey",
  "reference": "ageInYears",
  "replaceWith": {
    "name": "ageId",
    "dataType": "entityId"
  },
  "explanation": "Replacing ageInYears with a foreign key ageId."
}

9. Maintain Consistent Naming Conventions

  • Standardized Formats: Adopt a consistent naming convention (e.g., {a}{M}) to ensure clarity and prevent conflicts.

  • Avoid Ambiguity: Ensure that attribute names clearly reflect their purpose and origin.

Example:

{
  "$type": "renameAttributes",
  "renameFormat": "{a}{M}",
  "applyTo": ["age", "address"],
  "explanation": "Appending 'M' to attribute names to denote membership."
}

10. Utilize Advanced Traits and Metadata

  • Enrich Attributes: Use traits to add semantic meaning and constraints to attributes, enhancing data quality and interpretability.

  • Leverage Metadata: Incorporate metadata attributes to provide additional context and support advanced analytical capabilities.

Example:

{
  "name": "ImpactValue",
  "dataType": "impact",
  "traits": [
    {
      "traitReference": "means.risk.impact.financial",
      "arguments": [
        {
          "name": "currency",
          "value": "EUR"
        }
      ]
    },
    {
      "traitReference": "is.required"
    },
    {
      "traitReference": "means.metadata.source",
      "arguments": [
        {
          "name": "sourceName",
          "value": "Annual Report 2023"
        }
      ]
    }
  ],
  "explanation": "Measuring the financial impact in Euros, sourced from the Annual Report 2023."
}

Case Studies and Examples

To illustrate the practical application of resolving logical entities using CDM’s resolution features within GCRIx, consider the following case studies:

Case Study 1: Modeling Climate Risk Impact

Scenario: An organization within GCRIx aims to model the impact of climate-related risks, capturing both monetary and environmental impacts with specific measurement units and constraints.

Trait Definitions:

{
  "traitName": "means.measurement.impact",
  "explanation": "A measurement representing the impact of a risk event.",
  "extendsTrait": "means.measurement",
  "hasParameters": [
    {
      "name": "impactType",
      "explanation": "The type of impact (e.g., Financial, Environmental).",
      "required": true,
      "dataType": "string"
    }
  ]
},
{
  "traitName": "means.risk.impact.financial",
  "explanation": "Specifies that the impact is financial in nature.",
  "extendsTrait": "means.measurement.impact",
  "hasParameters": [
    {
      "name": "currency",
      "explanation": "The currency of the financial impact.",
      "required": true,
      "dataType": "string",
      "defaultValue": "USD",
      "validationRules": [
        {
          "type": "enum",
          "values": ["USD", "EUR", "GBP"],
          "errorMessage": "Currency must be USD, EUR, or GBP."
        }
      ]
    },
    {
      "name": "precision",
      "explanation": "Number of decimal places.",
      "required": true,
      "dataType": "integer",
      "defaultValue": 2
    }
  ],
  "exhibitsTraits": [
    {
      "traitReference": "means.currency.USD",
      "arguments": []
    }
  ]
},
{
  "traitName": "means.risk.impact.environmental",
  "explanation": "Specifies that the impact is environmental in nature.",
  "extendsTrait": "means.measurement.impact",
  "hasParameters": [
    {
      "name": "units",
      "explanation": "The unit of measure for environmental impact.",
      "required": true,
      "dataType": "string",
      "defaultValue": "MetricTon",
      "validationRules": [
        {
          "type": "enum",
          "values": ["MetricTon", "Kilogram", "Pound"],
          "errorMessage": "Units must be MetricTon, Kilogram, or Pound."
        }
      ]
    }
  ]
}

Entity Definition:

{
  "entityName": "ClimateRiskImpact",
  "hasAttributes": [
    {
      "name": "ImpactID",
      "dataType": "entityId",
      "purpose": "identifiedBy",
      "traits": [
        {
          "traitReference": "means.identity.entityId",
          "arguments": []
        },
        {
          "traitReference": "is.required",
          "arguments": []
        }
      ],
      "explanation": "Unique identifier for the ClimateRiskImpact record."
    },
    {
      "name": "ImpactType",
      "dataType": "string",
      "purpose": "definesImpactType",
      "traits": [
        {
          "traitReference": "means.measurement.impact",
          "arguments": [
            {
              "name": "impactType",
              "value": "Financial"
            }
          ]
        },
        {
          "traitReference": "is.required",
          "arguments": []
        }
      ],
      "explanation": "Defines whether the impact is financial or environmental."
    },
    {
      "name": "ImpactValue",
      "dataType": "impact",
      "purpose": "measuresImpactValue",
      "traits": [
        {
          "traitReference": "means.risk.impact.financial",
          "arguments": [
            {
              "name": "currency",
              "value": "EUR"
            }
          ]
        },
        {
          "traitReference": "is.required",
          "arguments": []
        }
      ],
      "explanation": "Measures the financial impact in Euros."
    },
    {
      "name": "EnvironmentalImpact",
      "dataType": "impact",
      "purpose": "measuresEnvironmentalImpact",
      "traits": [
        {
          "traitReference": "means.risk.impact.environmental",
          "arguments": [
            {
              "name": "units",
              "value": "MetricTon"
            }
          ]
        },
        {
          "traitReference": "is.required",
          "arguments": []
        }
      ],
      "explanation": "Measures the environmental impact in Metric Tons."
    }
  ],
  "exhibitsTraits": [
    {
      "traitReference": "is.cdm.entityVersion",
      "arguments": [
        {
          "name": "version",
          "value": "1.0"
        }
      ],
      "explanation": "Specifies the version of the ClimateRiskImpact entity schema."
    },
    {
      "traitReference": "means.category.standard",
      "arguments": [],
      "explanation": "Classifies the entity into a standard risk impact category."
    }
  ],
  "explanation": "Entity representing both financial and environmental impacts of climate-related risks."
}

Resolved Entity Example:

{
  "entityName": "ClimateRiskImpact",
  "attributes": [
    {
      "name": "ImpactID",
      "dataType": "entityId",
      "traits": [
        {
          "traitReference": "means.identity.entityId"
        },
        {
          "traitReference": "is.required"
        }
      ],
      "explanation": "Unique identifier for the ClimateRiskImpact record."
    },
    {
      "name": "ImpactType",
      "dataType": "string",
      "traits": [
        {
          "traitReference": "means.measurement.impact",
          "arguments": [
            {
              "name": "impactType",
              "value": "Financial"
            }
          ]
        },
        {
          "traitReference": "is.required"
        }
      ],
      "explanation": "Defines whether the impact is financial or environmental."
    },
    {
      "name": "ImpactValue",
      "dataType": "impact",
      "traits": [
        {
          "traitReference": "means.risk.impact.financial",
          "arguments": [
            {
              "name": "currency",
              "value": "EUR"
            }
          ]
        },
        {
          "traitReference": "is.required"
        }
      ],
      "explanation": "Measures the financial impact in Euros."
    },
    {
      "name": "EnvironmentalImpact",
      "dataType": "impact",
      "traits": [
        {
          "traitReference": "means.risk.impact.environmental",
          "arguments": [
            {
              "name": "units",
              "value": "MetricTon"
            }
          ]
        },
        {
          "traitReference": "is.required"
        }
      ],
      "explanation": "Measures the environmental impact in Metric Tons."
    }
  ],
  "exhibitsTraits": [
    {
      "traitReference": "is.cdm.entityVersion",
      "arguments": [
        {
          "name": "version",
          "value": "1.0"
        }
      ],
      "explanation": "Specifies the version of the ClimateRiskImpact entity schema."
    },
    {
      "traitReference": "means.category.standard",
      "arguments": [],
      "explanation": "Classifies the entity into a standard risk impact category."
    }
  ],
  "explanation": "Resolved entity definition for ClimateRiskImpact, consolidating financial and environmental impact metrics."
}

Outcome: The ClimateRiskImpact entity now includes both financial and environmental impact measurements, each with their respective units and constraints, ready for integration into GCRIx’s analytical processes.

Case Study 2: Enhancing Risk Relationships with Traits

Scenario: Modeling the relationship between RiskEntity and MitigationMeasure entities, capturing the nature and strength of their association within GCRIx.

Trait Definitions:

{
  "traitName": "means.relationship.associates",
  "explanation": "Indicates an associative relationship between entities.",
  "hasParameters": [
    {
      "name": "associationStrength",
      "explanation": "The strength of the association (e.g., Strong, Moderate, Weak).",
      "required": false,
      "dataType": "string",
      "defaultValue": "Moderate",
      "validationRules": [
        {
          "type": "enum",
          "values": ["Strong", "Moderate", "Weak"],
          "errorMessage": "Association strength must be Strong, Moderate, or Weak."
        }
      ]
    }
  ]
},
{
  "traitName": "means.relationship.inverseAssociates",
  "explanation": "Defines the inverse nature of an associative relationship.",
  "hasParameters": [
    {
      "name": "inverseAssociationStrength",
      "explanation": "The strength of the inverse association.",
      "required": false,
      "dataType": "string",
      "defaultValue": "Moderate",
      "validationRules": [
        {
          "type": "enum",
          "values": ["Strong", "Moderate", "Weak"],
          "errorMessage": "Inverse association strength must be Strong, Moderate, or Weak."
        }
      ]
    }
  ]
}

Entity Definitions:

{
  "entityName": "RiskEntity",
  "hasAttributes": [
    {
      "name": "RiskID",
      "dataType": "entityId",
      "purpose": "identifiedBy",
      "traits": [
        {
          "traitReference": "means.identity.entityId",
          "arguments": []
        },
        {
          "traitReference": "is.required",
          "arguments": []
        }
      ],
      "explanation": "Unique identifier for the RiskEntity record."
    },
    {
      "name": "RiskName",
      "dataType": "string",
      "purpose": "namedBy",
      "traits": [
        {
          "traitReference": "is.required",
          "arguments": []
        },
        {
          "traitReference": "means.text.name",
          "arguments": []
        }
      ],
      "explanation": "Name of the risk entity."
    }
  ],
  "exhibitsTraits": [
    {
      "traitReference": "is.cdm.entityVersion",
      "arguments": [
        {
          "name": "version",
          "value": "1.0"
        }
      ],
      "explanation": "Specifies the version of the RiskEntity schema."
    },
    {
      "traitReference": "means.category.standard",
      "arguments": [],
      "explanation": "Classifies the entity into a standard risk category."
    }
  ],
  "explanation": "Entity representing a specific risk within GCRIx."
},
{
  "entityName": "MitigationMeasure",
  "hasAttributes": [
    {
      "name": "MitigationID",
      "dataType": "entityId",
      "purpose": "identifiedBy",
      "traits": [
        {
          "traitReference": "means.identity.entityId",
          "arguments": []
        },
        {
          "traitReference": "is.required",
          "arguments": []
        }
      ],
      "explanation": "Unique identifier for the MitigationMeasure record."
    },
    {
      "name": "MitigationName",
      "dataType": "string",
      "purpose": "namedBy",
      "traits": [
        {
          "traitReference": "is.required",
          "arguments": []
        },
        {
          "traitReference": "means.text.name",
          "arguments": []
        }
      ],
      "explanation": "Name of the mitigation measure."
    }
  ],
  "exhibitsTraits": [
    {
      "traitReference": "is.cdm.entityVersion",
      "arguments": [
        {
          "name": "version",
          "value": "1.0"
        }
      ],
      "explanation": "Specifies the version of the MitigationMeasure schema."
    },
    {
      "traitReference": "means.category.standard",
      "arguments": [],
      "explanation": "Classifies the entity into a standard mitigation measure category."
    }
  ],
  "explanation": "Entity representing a mitigation measure within GCRIx."
}

Intersection Entity Definition:

{
  "entityName": "RiskMitigation",
  "hasAttributes": [
    {
      "name": "RiskID",
      "dataType": "entityId",
      "purpose": "identifiedBy",
      "traits": [
        {
          "traitReference": "means.identity.entityId",
          "arguments": []
        },
        {
          "traitReference": "is.required",
          "arguments": []
        }
      ],
      "explanation": "Foreign key linking to the RiskEntity."
    },
    {
      "name": "MitigationID",
      "dataType": "entityId",
      "purpose": "identifiedBy",
      "traits": [
        {
          "traitReference": "means.identity.entityId",
          "arguments": []
        },
        {
          "traitReference": "is.required",
          "arguments": []
        }
      ],
      "explanation": "Foreign key linking to the MitigationMeasure."
    },
    {
      "name": "AssociationStrength",
      "dataType": "string",
      "purpose": "definesAssociationStrength",
      "traits": [
        {
          "traitReference": "means.relationship.associates",
          "arguments": [
            {
              "name": "associationStrength",
              "value": "Strong"
            }
          ]
        }
      ],
      "explanation": "Indicates the strength of the association between RiskEntity and MitigationMeasure."
    }
  ],
  "exhibitsTraits": [
    {
      "traitReference": "is.intersection.entity",
      "arguments": [],
      "explanation": "Marks this entity as an intersection entity for many-to-many relationships."
    },
    {
      "traitReference": "means.category.standard",
      "arguments": [],
      "explanation": "Classifies the entity into a standard risk mitigation association category."
    }
  ],
  "explanation": "Intersection entity modeling the many-to-many relationship between RiskEntity and MitigationMeasure with defined association strength."
}

Relationship Definitions:

{
  "relationships": [
    {
      "name": "RiskEntity_RiskMitigation",
      "fromEntity": "local:/RiskEntity.cdm.json/RiskEntity",
      "fromEntityAttribute": "RiskID",
      "toEntity": "local:/RiskMitigation.cdm.json/RiskMitigation",
      "toEntityAttribute": "RiskID",
      "exhibitsTraits": [
        {
          "traitReference": "means.relationship.associates",
          "arguments": [
            {
              "name": "associationStrength",
              "value": "Strong"
            }
          ],
          "explanation": "Defines a strong associative relationship from RiskEntity to RiskMitigation."
        }
      ],
      "explanation": "Defines the relationship between RiskEntity and RiskMitigation with strong association strength."
    },
    {
      "name": "MitigationMeasure_RiskMitigation",
      "fromEntity": "local:/MitigationMeasure.cdm.json/MitigationMeasure",
      "fromEntityAttribute": "MitigationID",
      "toEntity": "local:/RiskMitigation.cdm.json/RiskMitigation",
      "toEntityAttribute": "MitigationID",
      "exhibitsTraits": [
        {
          "traitReference": "means.relationship.associates",
          "arguments": [
            {
              "name": "associationStrength",
              "value": "Strong"
            }
          ],
          "explanation": "Defines a strong associative relationship from MitigationMeasure to RiskMitigation."
        }
      ],
      "explanation": "Defines the relationship between MitigationMeasure and RiskMitigation with strong association strength."
    }
  ],
  "explanation": "Relationships defining the links between RiskEntity, MitigationMeasure, and their intersection entity RiskMitigation with specified association strengths."
}

Resolved Entity Example:

{
  "entityName": "RiskMitigation",
  "attributes": [
    {
      "name": "RiskID",
      "dataType": "entityId",
      "traits": [
        {
          "traitReference": "means.identity.entityId"
        },
        {
          "traitReference": "is.required"
        }
      ],
      "explanation": "Foreign key linking to the RiskEntity."
    },
    {
      "name": "MitigationID",
      "dataType": "entityId",
      "traits": [
        {
          "traitReference": "means.identity.entityId"
        },
        {
          "traitReference": "is.required"
        }
      ],
      "explanation": "Foreign key linking to the MitigationMeasure."
    },
    {
      "name": "AssociationStrength",
      "dataType": "string",
      "traits": [
        {
          "traitReference": "means.relationship.associates",
          "arguments": [
            {
              "name": "associationStrength",
              "value": "Strong"
            }
          ]
        }
      ],
      "explanation": "Indicates the strength of the association between RiskEntity and MitigationMeasure."
    }
  ],
  "exhibitsTraits": [
    {
      "traitReference": "is.intersection.entity",
      "arguments": [],
      "explanation": "Marks this entity as an intersection entity for many-to-many relationships."
    },
    {
      "traitReference": "means.category.standard",
      "arguments": [],
      "explanation": "Classifies the entity into a standard risk mitigation association category."
    }
  ],
  "explanation": "Resolved entity definition for RiskMitigation, modeling the many-to-many relationship between RiskEntity and MitigationMeasure with a strong association strength."
}

Outcome: The RiskMitigation entity effectively captures the associative relationship between RiskEntity and MitigationMeasure, with a clear indication of the association strength, facilitating comprehensive risk management and analysis within GCRIx.

Resolving logical entity definitions in CDM is a critical process within the GCRIx framework, enabling the transformation of abstract semantic models into concrete, storage-optimized schemas. By understanding and applying the principles of default resolution behavior, leveraging directives and projections, and adhering to best practices, organizations can ensure that their data models are both semantically rich and tailored to their specific storage and analytical needs.

Effective entity resolution fosters data integrity, scalability, and interoperability, empowering GCRIx to deliver precise and actionable climate risk assessments. As data landscapes evolve, maintaining a robust approach to entity resolution will be paramount in sustaining the relevance and effectiveness of GCRIx’s risk management capabilities.

Further Reading and Resources

PreviousTraitNextProjection

Last updated

Was this helpful?