From 7e36bb602d2d9b7e7bc0cad5ca918fb225666d18 Mon Sep 17 00:00:00 2001 From: diegoalexdiaz <46930149+diegoalexdiaz@users.noreply.github.com> Date: Mon, 22 Jul 2024 10:35:13 -0400 Subject: [PATCH 1/3] Expanding example of CodeSpecs in guide to address issue Documentation Issue: Missing code examples #6966. --- docs/bis/guide/fundamentals/codes.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/bis/guide/fundamentals/codes.md b/docs/bis/guide/fundamentals/codes.md index f1b96311c92a..ef4d18b71719 100644 --- a/docs/bis/guide/fundamentals/codes.md +++ b/docs/bis/guide/fundamentals/codes.md @@ -45,13 +45,15 @@ When the identified entity is pure information in nature, it will often have its A `CodeSpec` (aka **Code Specification**) names and specifies a new *classification* for Codes. A `CodeSpec` also captures the rules for encoding and decoding significant business information into and from a Code. -For example, the Codes for ViewDefinitions and the Codes for Equipment have different *encoding* rules and uniqueness constraints, so would each have a separate `CodeSpec`. +For example, the Codes for software artifacts, like ViewDefinitions, and the Codes for Equipment, such as Piping Components, have different *encoding* rules and uniqueness constraints, so would each have a separate `CodeSpec`. -Typically, a `CodeSpec` has a strong correlation with a branch of the Element class hierarchy and is often named after an abstract base class that defines the starting point of that branch. It is common for all subclasses (direct or indirect) descending from that base class to share the same `CodeSpec`. +For instance, an Industrial Process Plant-focused implementation may require Codes for Piping Components to follow a Specification such as: [plant area code]-[equipment-type code]-[equipment number] (e.g. OIL-AAV-001, which *encodes* a Valve of a particular type "AAV" in an area known as "OIL" at a specific Industrial Plant). + +In many cases, a `CodeSpec` has a strong correlation with a branch of the Element class hierarchy and is often named after an abstract base class that defines the starting point of that branch. It is common for all subclasses (direct or indirect) descending from that base class to share the same `CodeSpec`. For example, the standard `CodeSpec` called "bis:ViewDefinition" helps ensure unique names for all subclasses of the `BisCore:ViewDefinition` Element class. -Configuration can define the association between Element class and CodeSpec so that a shared service (e.g. 'Identification Code Service') can be used to generate and validate Codes. +Additional Configuration in an application can define the association between Element class and CodeSpec so that a shared service (e.g. 'Identification Code Service') can be used to generate and validate Codes. The CodeSpec can also dictate that Codes for instances of the Element class should be null. This is appropriate when the modeled real-world entities don’t have a meaningful real-world identifier (e.g. a piece of baseboard, a pile of dirt, an average bolt). From 1f76a5ae0c777d5f569cdbf7325646bfe9743c68 Mon Sep 17 00:00:00 2001 From: Diego Diaz <46930149+diegoalexdiaz@users.noreply.github.com> Date: Wed, 31 Jul 2024 14:06:57 -0400 Subject: [PATCH 2/3] Update docs/bis/guide/fundamentals/codes.md Co-authored-by: Nam Le <50554904+hl662@users.noreply.github.com> --- docs/bis/guide/fundamentals/codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/bis/guide/fundamentals/codes.md b/docs/bis/guide/fundamentals/codes.md index ef4d18b71719..8a0c40952a5b 100644 --- a/docs/bis/guide/fundamentals/codes.md +++ b/docs/bis/guide/fundamentals/codes.md @@ -45,7 +45,7 @@ When the identified entity is pure information in nature, it will often have its A `CodeSpec` (aka **Code Specification**) names and specifies a new *classification* for Codes. A `CodeSpec` also captures the rules for encoding and decoding significant business information into and from a Code. -For example, the Codes for software artifacts, like ViewDefinitions, and the Codes for Equipment, such as Piping Components, have different *encoding* rules and uniqueness constraints, so would each have a separate `CodeSpec`. +For example, the Codes for software artifacts, like ViewDefinitions, and the Codes for Equipment, such as Piping Components, have different *encoding* rules and uniqueness constraints, so each would have a separate `CodeSpec`. For instance, an Industrial Process Plant-focused implementation may require Codes for Piping Components to follow a Specification such as: [plant area code]-[equipment-type code]-[equipment number] (e.g. OIL-AAV-001, which *encodes* a Valve of a particular type "AAV" in an area known as "OIL" at a specific Industrial Plant). From 77ae6961fbcd303fa2f657112130c70d28e6d1f1 Mon Sep 17 00:00:00 2001 From: Diego Diaz <46930149+diegoalexdiaz@users.noreply.github.com> Date: Wed, 31 Jul 2024 16:05:23 -0400 Subject: [PATCH 3/3] Update docs/bis/guide/fundamentals/codes.md Co-authored-by: Nam Le <50554904+hl662@users.noreply.github.com> --- docs/bis/guide/fundamentals/codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/bis/guide/fundamentals/codes.md b/docs/bis/guide/fundamentals/codes.md index 8a0c40952a5b..b8e67600af78 100644 --- a/docs/bis/guide/fundamentals/codes.md +++ b/docs/bis/guide/fundamentals/codes.md @@ -53,7 +53,7 @@ In many cases, a `CodeSpec` has a strong correlation with a branch of the Elemen For example, the standard `CodeSpec` called "bis:ViewDefinition" helps ensure unique names for all subclasses of the `BisCore:ViewDefinition` Element class. -Additional Configuration in an application can define the association between Element class and CodeSpec so that a shared service (e.g. 'Identification Code Service') can be used to generate and validate Codes. +Additional configuration in an application can define the association between Element class and CodeSpec, allowing a shared service (e.g., 'Identification Code Service') to generate and validate Codes. The CodeSpec can also dictate that Codes for instances of the Element class should be null. This is appropriate when the modeled real-world entities don’t have a meaningful real-world identifier (e.g. a piece of baseboard, a pile of dirt, an average bolt).