# Standards References for SHACL Validation Rules

**Environment:** abp-dev
**Date Created:** 2026-02-17
**Purpose:** Document the mapping between SHACL validation rules and their source standards (ENS, NORSOK Z-DP-002, ISO 14224:2016)

---

## Standards Documents

### 1. NORSOK Z-DP-002 Rev.3 (October 1996)
**Title:** Coding System
**Purpose:** Defines tag coding and equipment identification standards for offshore installations
**Key Sections:**
- Section 6: TAG CODING
- Annex A: System codes
- Annex B.1: Function and type codes for equipment
- Annex C: Discipline codes

**Source File:** `rule_input/NORSOK Z-DP-002, Rev.3 Oct. 1996.pdf`

### 2. General Engineering Numbering System (ENS) 2018
**Title:** General Engineering Numbering System
**Purpose:** Standardized equipment numbering and system identification
**Key Sections:**
- Appendix C: System codes (ranges 01-99)
- Appendix D: Function codes

**Source File:** `rule_input/General Engineering Numbering System (ENS).pdf`

### 3. ISO 14224:2016
**Title:** Petroleum, petrochemical and natural gas industries — Collection and exchange of reliability and maintenance data for equipment
**Purpose:** International standard for equipment classification, reliability data, and failure mode taxonomy
**Key Sections:**
- Section 5.2: Equipment taxonomy structure
- Table A.4: Equipment Class codes (Level 6)
- Table A.8: Compressor equipment type codes
- Section 7: Failure data requirements

**Source File:** `rule_input/ISO 14224 2016.pdf`

---

## Implemented SHACL Rules by Standard

### NORSOK Z-DP-002 Rev.3 Rules

#### NOR-001: Function Code Vocabulary (P0 - Critical)
**SHACL Shape:** `dm:TagFunctionCodeVocabularyShape`
**File:** [`tag_shacl_rules.ttl`](tag_shacl_rules.ttl#L236-L263)
**Standard Reference:** NORSOK Z-DP-002 Rev.3 October 1996, Annex B.1
**Requirement:** Function code SHALL be from approved NORSOK equipment list
**Property:** `dm:functionCode`
**Constraint Type:** `sh:in` (controlled vocabulary)
**Severity:** `sh:Violation`

**Valid Function Codes:**
- **PA-PX**: Pumps (PA=Centrifugal, PB=Reciprocating, PC=Rotary, PD=Special Metering, PE=Gear, PF=Diaphragm, PG=Screw, PH=Submerged with Non-Submerged Motors, PS=Submerged with Submerged Motors, PX=Other Pumps)
- **KA-KX**: Compressors/Blowers/Fans (KA=Centrifugal, KB=Reciprocating, KC=Screw/Rotary, KD=Axial, KE=Fans, KF=Blowers, KH=Expanders, KX=Other)
- **DA-DT**: Drivers (DA=Gas Engines, DB=Gearboxes/Couplings, DC=Steam Turbines, DD=Diesel Engines, DE=Electrical Motors, DT=Gas Turbines)
- **HA-HX**: Heat Transfer Equipment (HA=Shell and Tube, HB=Plate, HC=Air Cooled, HD=Quench Coolers, HE=Misc. Coolers, HF=Double Pipe, HG=Core Type, HH=Liquefaction, HI=Reboilers/Evaporators, HW=Waste Heat Recovery, HX=Other)
- **VA-VX**: Vessels and Columns (VA=Separators, VB=Contractors, VC=Regenerators, VD=Settling/Knock-Out/Flash Drums, VE=Columns/Towers, VF=Reactors, VG=Scrubbers, VH=Deaerators, VJ=Coalescers, VK=Dryers, VL=Receiver/Surge Drums, VX=Other)

**Applies To:** All Tag instances (inherited by Pump, Compressor, HeatExchanger, ElectricMotor, etc.)

---

#### NOR-002: Discipline Vocabulary (P0 - Critical)
**SHACL Shape:** `dm:TagDisciplineVocabularyShape`
**File:** [`tag_shacl_rules.ttl`](tag_shacl_rules.ttl#L265-L291)
**Standard Reference:** NORSOK Z-DP-002 Rev.3 October 1996, Annex C
**Requirement:** Tag discipline SHALL be from approved NORSOK discipline list
**Property:** `dm:tagDiscipline`
**Constraint Type:** `sh:in` (controlled vocabulary)
**Severity:** `sh:Violation`

**Valid Disciplines:**
- Administration
- Civil
- Architectural
- Electrical
- HVAC
- Instrumentation
- Piping
- Process
- Mechanical
- Telecommunication

**Applies To:** All Tag instances

---

#### NOR-003: Pump Discipline Consistency (P0 - Critical)
**SHACL Shape:** `dm:PumpDisciplineConsistencyShape`
**File:** [`pump_shacl_rules.ttl`](pump_shacl_rules.ttl#L136-L162)
**Standard Reference:** NORSOK Z-DP-002 Rev.3 October 1996, Annex B.1 (PA-PX codes) and Annex C
**Requirement:** Pumps SHALL have discipline "Mechanical" or "Process"
**Property:** `dm:tagDiscipline`
**Constraint Type:** `sh:sparql` (SPARQL constraint)
**Severity:** `sh:Violation`

**Business Rule:** Equipment with pump function codes (PA-PX) must be tagged with either "Mechanical" or "Process" discipline per NORSOK standards.

**Applies To:** Pump instances only

---

#### NOR-004: ElectricMotor Discipline Consistency (P0 - Critical)
**SHACL Shape:** `dm:ElectricMotorDisciplineConsistencyShape`
**File:** [`electricmotor_shacl_rules.ttl`](electricmotor_shacl_rules.ttl#L64-L91)
**Standard Reference:** NORSOK Z-DP-002 Rev.3 October 1996, Annex B.1 (DE code) and Annex C
**Requirement:** Electric motors SHALL have discipline "Electrical"
**Property:** `dm:tagDiscipline`
**Constraint Type:** `sh:sparql` (SPARQL constraint)
**Severity:** `sh:Violation`

**Business Rule:** Equipment with electric motor function code (DE) must be tagged with "Electrical" discipline per NORSOK standards.

**Applies To:** ElectricMotor instances only

---

#### NOR-005: Compressor Discipline Consistency (P0 - Critical)
**SHACL Shape:** `dm:CompressorDisciplineConsistencyShape`
**File:** [`compressor_shacl_rules.ttl`](compressor_shacl_rules.ttl#L153-L179)
**Standard Reference:** NORSOK Z-DP-002 Rev.3 October 1996, Annex B.1 (KA-KX codes) and Annex C
**Requirement:** Compressors SHALL have discipline "Mechanical"
**Property:** `dm:tagDiscipline`
**Constraint Type:** `sh:sparql` (SPARQL constraint)
**Severity:** `sh:Violation`

**Business Rule:** Equipment with compressor function codes (KA-KX) must be tagged with "Mechanical" discipline per NORSOK standards.

**Applies To:** Compressor instances only

---

#### NOR-006: HeatExchanger Discipline Consistency (P0 - Critical)
**SHACL Shape:** `dm:HeatExchangerDisciplineConsistencyShape`
**File:** [`heatexchanger_shacl_rules.ttl`](heatexchanger_shacl_rules.ttl#L251-L277)
**Standard Reference:** NORSOK Z-DP-002 Rev.3 October 1996, Annex B.1 (HA-HX codes) and Annex C
**Requirement:** Heat Exchangers SHALL have discipline "Mechanical" or "Process"
**Property:** `dm:tagDiscipline`
**Constraint Type:** `sh:sparql` (SPARQL constraint)
**Severity:** `sh:Violation`

**Business Rule:** Equipment with heat exchanger function codes (HA-HX) must be tagged with either "Mechanical" or "Process" discipline per NORSOK standards.

**Applies To:** HeatExchanger instances only

#### NOR-DOC-001: Document Identification Code Format (P1 - High)
**SHACL Shape:** `dm:DocumentIdentificationCodeFormatShape`
**File:** [`document_shacl_rules.ttl`](document_shacl_rules.ttl#L82-L101)
**Standard Reference:** NORSOK Z-DP-002 Rev.3 October 1996, Section 5.2
**Requirement:** Document identification code SHOULD follow standard format
**Property:** `dm:name`
**Constraint Type:** `sh:pattern` (regex validation)
**Severity:** `sh:Warning`

**Document Identification Format:**
```
ZZZZ-ZZZZZ-A-NNNN
```
Where:
- **ZZZZ**: Project/facility code (1-4 alphanumeric characters)
- **ZZZZZ**: Originator code (1-5 alphanumeric, Achilles code recommended)
- **A**: Discipline code (1 alphabetic character from Annex C)
- **NNNN**: Sequential number (4 digits)

**Examples:**
- `S5-10696-P-0001` - Saga Petroleum project, Aker Engineering, Process discipline, document #1
- `C010-KE-I-0001` - Phillips Petroleum project, Kværner Engineering, Instrumentation discipline, document #1

**Pattern:** `^[A-Z0-9]{1,4}-[A-Z0-9]{1,5}-[A-Z]-[0-9]{4}$`

**Applies To:** All Document instances

---

#### NOR-DOC-002: Document Type Code Vocabulary (P0 - Critical)
**SHACL Shape:** `dm:DocumentTypeCodeVocabularyShape`
**File:** [`document_shacl_rules.ttl`](document_shacl_rules.ttl#L103-L199)
**Standard Reference:** NORSOK Z-DP-002 Rev.3 October 1996, Annex D (NORMATIVE)
**Requirement:** Document Type SHALL be from NORSOK Annex D controlled vocabulary
**Property:** `dm:documentType`
**Constraint Type:** `sh:in` (controlled vocabulary)
**Severity:** `sh:Violation`

**Valid Document Type Codes (NORSOK Annex D):**

**Administrative and Financial:**
- **AA**: Accounting/Budget

**Analysis and Calculations:**
- **CA**: Analysis, test and calculation

**Data and Design:**
- **DS**: Data sheets
- **FD**: Project design criteria and philosophies

**Procedures and Lists:**
- **KA**: Procedures
- **LA**: List / Registers

**Manuals and Instructions:**
- **MA**: Equipment user manual (ref. NS5820)
- **MB**: Operating and maintenance instructions
- **MC**: Spare parts list

**Procurement:**
- **PA**: Purchase orders
- **PB**: Blanket order/frame agreement
- **PD**: Contract

**Reports and Documentation:**
- **RA**: Reports
- **RD**: System design reports and system user manuals
- **RE**: DFI (Design - Fabrication - Installation) resumes

**Specifications and Standards:**
- **SA**: Specifications & Standards

**Planning and Scheduling:**
- **TA**: Plans/schedules
- **TB**: Work plan
- **TE**: Estimates
- **TF**: Work package

**Verification and Certificates:**
- **VA**: Manufacturing/Fabrication and verifying documentation
- **VB**: Certificates

**Drawings - Process and Piping:**
- **XA**: Flow diagrams
- **XB**: Pipe and instrument diagram (P&ID)
- **XC**: Duct and instrument diagrams (D&ID)
- **XD**: General arrangement
- **XE**: Layout drawings
- **XF**: Location drawings (plot plans)
- **XN**: Isometric drawings (fabrication, heat tracing, stress, pressure testing)
- **XO**: Piping supports

**Drawings - Structural:**
- **XG**: Structural information (main/secondary steel, fire protection, insulation)
- **XH**: Free span calculation
- **XS**: Detail cross sectional drawings

**Drawings - Electrical and Control:**
- **XI**: System topology and block diagrams
- **XJ**: Single line diagrams
- **XK**: Circuit diagrams
- **XL**: Logic diagrams
- **XM**: Level diagrams
- **XQ**: Pneumatic/hydraulic connection drawings
- **XR**: Cause and effect
- **XT**: Wiring diagrams
- **XU**: Loop diagram

**Miscellaneous:**
- **XX**: Drawings - miscellaneous
- **ZA**: EDP documentation

**Mandatory Attribute:** Per NORSOK Z-DP-002 Section 5.3, Document Type is a mandatory attribute that must be registered in the document information system.

**Applies To:** All Document instances

---

#### NOR-DOC-003: Document Discipline Code Vocabulary (P0 - Critical)
**SHACL Shape:** `dm:DocumentDisciplineVocabularyShape`
**File:** [`document_shacl_rules.ttl`](document_shacl_rules.ttl#L201-L225)
**Standard Reference:** NORSOK Z-DP-002 Rev.3 October 1996, Annex C
**Requirement:** Document discipline SHALL be from NORSOK Annex C controlled vocabulary
**Property:** `dm:discipline`
**Constraint Type:** `sh:in` (controlled vocabulary)
**Severity:** `sh:Violation`

**Valid Disciplines:** Same as Tag disciplines (Administration, Civil, Architectural, Electrical, HVAC, Instrumentation, Piping, Process, Mechanical, Telecommunication)

**Note:** The discipline code in the document identification format (position 3, single letter A) maps to these discipline names. For example:
- A = Administration
- C = Civil/Architectural
- E = Electrical
- H = HVAC
- I = Instrumentation
- L = Piping/Layout
- P = Process
- R = Mechanical (Rotating)
- T = Telecommunication

**Applies To:** All Document instances

---

### ENS (General Engineering Numbering System) Rules

#### ENS-001: System Number Range (P1 - High)
**SHACL Shape:** `dm:TagSystemNumberRangeShape`
**File:** [`tag_shacl_rules.ttl`](tag_shacl_rules.ttl#L293-L310)
**Standard Reference:** ENS 2018, Appendix C
**Requirement:** System number SHOULD be in valid range 01-99
**Property:** `dm:system`
**Constraint Type:** `sh:pattern` (regex validation)
**Severity:** `sh:Warning`

**Valid System Number Ranges:**
- **00-09**: Reserved for plant-specific systems
- **10-19**: Drilling, well and subsea related (10=Drilling, 11=Drilling Process, 18=Well and riser subsea)
- **20-29**: Main process systems (20=Separation, 21=Crude handling, 27=Gas export)
- **30-39**: Export and by-product handling (30=Oil export, 32=Gas export pipeline)
- **40-69**: Process support and utility (40=Cooling, 50=Sea water, 63=Compressed air, 65=Hydraulic power)
- **70-79**: Safety systems (70=Fire/gas detection, 71=Fire water, 79=ESD)
- **80-89**: Electrical, automation, telecom (80-82=Main power, 83-84=Emergency power, 87=Control)
- **90-99**: Structural, civil, marine, architectural (90=Topside, 93=Architectural, 97=Accommodation)

**Pattern:** `^(0[1-9]|[1-9][0-9])$` (01-99)

**Applies To:** All Tag instances

---

### ISO 14224:2016 Rules

#### ISO-001: Equipment Class Code Vocabulary (P0 - Critical)
**SHACL Shape:** `dm:EquipmentClassCodeVocabularyShape`
**File:** [`equipmentclass_shacl_rules.ttl`](equipmentclass_shacl_rules.ttl#L77-L116)
**Standard Reference:** ISO 14224:2016, Table A.4 (Level 6 - Equipment Class)
**Requirement:** EquipmentClass code SHALL be from ISO 14224 controlled vocabulary
**Property:** `dm:code`
**Constraint Type:** `sh:in` (controlled vocabulary)
**Severity:** `sh:Violation`

**Valid Equipment Class Codes:**
- **BL**: Blowers and fans (API 673, API 560)
- **CF**: Centrifuges
- **CE**: Combustion engines (ISO 8528, API 7C-11F)
- **CO**: Compressors (ISO 10439, API 617/618/619)
- **EG**: Electric generators (BS 4999-140, IEEE C37)
- **EM**: Electric motors (IEC 60034-12, API 541/547)
- **GT**: Gas turbines (ISO 3977, API 616)
- **HE**: Heat exchangers
- **LE**: Liquid expanders
- **MI**: Mixers
- **PU**: Pumps (ISO 13709/13710, API 610/674/676)
- **ST**: Steam turbines (ISO 10437, API 611/612)
- **TE**: Turboexpanders (API 617)
- **VA**: Valves
- **VE**: Vessels

**Applies To:** EquipmentClass instances

---

#### ISO-002: Equipment Type Code Vocabulary (P0 - Critical)
**SHACL Shape:** `dm:EquipmentTypeCodeVocabularyShape`
**File:** [`equipmenttype_shacl_rules.ttl`](equipmenttype_shacl_rules.ttl#L97-L137)
**Standard Reference:** ISO 14224:2016, Table A.8 and other equipment-specific tables
**Requirement:** EquipmentType code SHALL be from ISO 14224 controlled vocabulary
**Property:** `dm:code`
**Constraint Type:** `sh:in` (controlled vocabulary)
**Severity:** `sh:Violation`

**Valid Equipment Type Codes (Common):**
- **CE**: Centrifugal
- **RE**: Reciprocating
- **SC**: Screw
- **AX**: Axial
- **RO**: Rotary
- **PD**: Positive Displacement
- **GE**: Gear
- **DI**: Diaphragm
- **PE**: Peristaltic
- **PR**: Progressive cavity

**Note:** This list should be expanded with additional type codes from ISO 14224:2016 Tables A.7-A.15 as they are extracted from the standard.

**Applies To:** EquipmentType instances

---

#### ISO-003: Tag-Level Class-Type Consistency (P0 - Critical)
**SHACL Shape:** `dm:TagISO14224ClassTypeConsistencyShape`
**File:** [`tag_shacl_rules.ttl`](tag_shacl_rules.ttl#L312-L341)
**Standard Reference:** ISO 14224:2016, Section 5.2 and Table A.4
**Requirement:** Tag's ISOEquipmentClass must match EquipmentType's equipmentClass
**Properties:** `dm:ISOEquipmentClass`, `dm:ISOEquipmentType`
**Constraint Type:** `sh:sparql` (SPARQL constraint)
**Severity:** `sh:Violation`

**Business Rule:** Validates ISO 14224 taxonomy hierarchy - the equipment class referenced by a Tag must be the same as the equipment class referenced by the Tag's equipment type. This ensures consistency in the ISO 14224 classification hierarchy.

**Example:** If a Tag has:
- `ISOEquipmentClass` → EquipmentClass with code "PU" (Pumps)
- `ISOEquipmentType` → EquipmentType with code "CE" (Centrifugal)

Then the EquipmentType "CE" must also reference the same EquipmentClass "PU".

**Applies To:** All Tag instances

---

#### ISO-004: EquipmentType-Class Standard Consistency (P1 - High)
**SHACL Shape:** `dm:EquipmentTypeStandardConsistencyShape`
**File:** [`equipmenttype_shacl_rules.ttl`](equipmenttype_shacl_rules.ttl#L161-L185)
**Standard Reference:** ISO 14224:2016, Section 5.2
**Requirement:** EquipmentType standard SHOULD match EquipmentClass standard
**Property:** `dm:standard` (on both EquipmentType and EquipmentClass)
**Constraint Type:** `sh:sparql` (SPARQL constraint)
**Severity:** `sh:Warning`

**Business Rule:** For taxonomy consistency, the standard identifier on an EquipmentType should match the standard identifier on its referenced EquipmentClass. This prevents mixing taxonomies from different standards.

**Applies To:** EquipmentType instances

---

## Rule Implementation Summary

### By Priority

#### P0 (Critical) - sh:Violation
These rules MUST pass for data to be considered valid:

1. **NOR-001**: Function Code Vocabulary (Tag)
2. **NOR-002**: Discipline Vocabulary (Tag)
3. **NOR-003**: Pump Discipline Consistency
4. **NOR-004**: ElectricMotor Discipline Consistency
5. **NOR-005**: Compressor Discipline Consistency
6. **NOR-006**: HeatExchanger Discipline Consistency
7. **NOR-DOC-002**: Document Type Code Vocabulary (Document)
8. **NOR-DOC-003**: Document Discipline Code Vocabulary (Document)
9. **ISO-001**: Equipment Class Code Vocabulary
10. **ISO-002**: Equipment Type Code Vocabulary
11. **ISO-003**: Tag-Level Class-Type Consistency

**Total P0 Rules:** 11

#### P1 (High) - sh:Warning
These rules SHOULD pass for optimal data quality:

1. **ENS-001**: System Number Range (Tag)
2. **NOR-DOC-001**: Document Identification Code Format (Document)
3. **ISO-004**: EquipmentType-Class Standard Consistency

**Total P1 Rules:** 3

**Grand Total Implemented Rules:** 14

---

## Equipment Type Coverage

### Fully Validated Equipment Types
1. **Tag** (base interface)
   - Function code vocabulary (NORSOK)
   - Discipline vocabulary (NORSOK)
   - System number range (ENS)
   - ISO 14224 class-type consistency

2. **Pump**
   - Inherits all Tag rules
   - Discipline consistency (must be Mechanical/Process)

3. **Compressor**
   - Inherits all Tag rules
   - Discipline consistency (must be Mechanical)

4. **ElectricMotor**
   - Inherits all Tag rules
   - Discipline consistency (must be Electrical)

5. **HeatExchanger**
   - Inherits all Tag rules
   - Discipline consistency (must be Mechanical/Process)

6. **EquipmentClass**
   - ISO 14224 code vocabulary
   - Standard vocabulary

7. **EquipmentType**
   - ISO 14224 code vocabulary
   - Standard vocabulary
   - Type-Class standard consistency

8. **Document**
   - Document identification code format (NORSOK Section 5.2)
   - Document type code vocabulary (NORSOK Annex D - 40+ document types)
   - Document discipline vocabulary (NORSOK Annex C)
   - Required properties (name, description, sourceId)

---

## Future Enhancements

### Pending Rules from Standards (Not Yet Implemented)

#### From NORSOK Z-DP-002
- **NOR-007**: HVAC equipment discipline consistency (HVAC equipment must have "HVAC" discipline)
- **NOR-008**: Instrumentation discipline consistency (Instruments must have "Instrumentation" discipline)
- **NOR-009**: Equipment type code validation (extract equipment code from tag name, validate against function code)
- **NOR-010**: Pump type vocabulary (if `pumpType` property exists)
- **NOR-011**: Compressor type vocabulary (if `compressorType` property exists)
- **NOR-012**: Motor voltage standards (if `ratedVoltage` property exists)

#### From ENS
- **ENS-002**: Equipment class code validation from tag name
- **ENS-003**: Sequence number format validation

#### From ISO 14224:2016
- **ISO-005**: Failure mode taxonomy validation (Section 7, requires code extraction)
- **ISO-006**: Failure mechanism taxonomy validation (Section 7, requires code extraction)
- **ISO-007**: Maintenance data completeness (Section 6)
- **ISO-008**: Expand Equipment Type code list with codes from Tables A.7-A.15

### Implementation Considerations
1. Some rules depend on properties not yet in the data model (e.g., `pumpType`, `maintenanceStrategy`)
2. Failure mode/mechanism codes need to be extracted from ISO 14224 Section 7
3. Additional equipment types (Valve, Vessel, etc.) need discipline consistency rules

---

## Maintenance Notes

### When to Update These Rules

1. **New Equipment Type Added:**
   - Create new SHACL file following pattern: `{equipment}_shacl_rules.ttl`
   - Add `sh:node tag:TagShape` to inherit Tag validation
   - Add discipline consistency rule based on NORSOK Annex B.1 function code

2. **New Property Added to Data Model:**
   - Check if property is mentioned in ENS, NORSOK, or ISO 14224
   - Add validation rules from standard to appropriate SHACL file
   - Update this documentation with new rule

3. **Standard Updated (New Version Released):**
   - Review changes in new standard version
   - Update controlled vocabularies (codes, disciplines, etc.)
   - Update documentation with new standard version reference

4. **Validation Failures Indicate Missing Code:**
   - Check if code is valid per standard but missing from SHACL vocabulary
   - Extract code from standard document
   - Add to appropriate `sh:in` list in SHACL file
   - Document source in this file

### Validation Rule Versioning
- SHACL rules are versioned with the environment configuration
- Current environment: **abp-dev**
- Data model: **sp_yggdrasil-twin-commissioning-types** version **6**
- Workflow version: **1**

---

## Contact and Support

For questions about:
- **SHACL rule implementation**: Check `cognite_data_quality/_neat/_validate_instances.py`
- **Standard interpretation**: Refer to original PDF documents in `rule_input/`
- **Data model schema**: Check data model definition in CDF
- **Rule failures**: Review validation records in CDF Records API

---

**Document Version:** 1.0
**Last Updated:** 2026-02-17
**Author:** Claude Code (Data Quality Implementation)
