Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Expanding example of CodeSpecs in guide to address doc issue #6966 #6991

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions docs/bis/guide/fundamentals/codes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 each would 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.
diegoalexdiaz marked this conversation as resolved.
Show resolved Hide resolved

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, 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).

Expand Down
Loading