Linkage 🚧

Official URL: https://bcgov.github.io/nr-pies/docs/spec/element/message/linkage

JSON Schema URL: https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/message/linkage.schema.json

Represents a message asserting a linkage between specific assets.

Scope

This message type allows systems to assert a relationship between two specific assets. The message represents an assertion from the originating system's perspective. Consuming systems must validate the relationship and implicitly trust the assertion source.

A Linkage message is scoped to a single pair of assets and captures the relationship between them, similar in structure to a group message but specific to asset pairs.

Structure

A linkage message shall contain all flattened Header properties.

All linkages shall be denoted with a kind property value of LINKAGE as defined in Message Kind.

Linkages shall declare the following properties in addition to flattened Header properties:

Name	Cardinality	Type	Description & Constraints
asset_group	1..1	Asset	A binding asset entity that tracks the relationship between a primary asset and a linked asset.
linked_asset_id	1..1	string	The unique identifier or primary key of the asset to be linked.
linked_asset_kind	1..1	string	The asset type or classification within the source system (for example, Anchor or Permit).
linked_system_id	1..1	string	A valid CSNR IT Service Management code identifying the originating source system, service, or asset.
relation_kind	1..1	Code	The kind of relation between the primary asset and the linked asset (for example, MERGES, RELATES, SELF, SPLITS).

Binding Constraints

The asset_group field binds the relationship and typically originates from the declaring system:

• The asset_group represents a classification or grouping for the relationship as defined by the asset-owning system
• The relation_kind specifies the nature of the link (MERGES, RELATES, SELF, SPLITS)
• A Linkage connects the primary asset (defined in Header) to a linked asset via this asset group

Specification

Schema

Loading ....

Source

{
  "$id": "https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/message/linkage.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Linkage",
  "description": "Represents a message asserting a linkage between specific assets.",
  "type": "object",
  "properties": {
    "asset_group": {
      "$ref": "https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/data/asset.schema.json"
    },
    "linked_asset_id": {
      "type": "string",
      "description": "The asset or primary key representing what asset is linked with the primary header asset."
    },
    "linked_asset_kind": {
      "type": "string",
      "description": "A valid Asset Kind code that specifies the precise type of asset is linked with the primary header asset.",
      "enum": [
        "ANCHOR",
        "PERMIT",
        "PROJECT"
      ]
    },
    "linked_system_id": {
      "type": "string",
      "description": "A valid CSNR IT Service Management code identifying the originating source system, service, or asset.",
      "pattern": "^ITSM-\\d{4,5}$"
    },
    "relation_kind": {
      "type": "string",
      "description": "The kind of relation between the primary asset and the linked asset (for example, MERGES, RELATES, SELF, SPLITS).",
      "enum": [
        "MERGES",
        "RELATES",
        "SELF",
        "SPLITS"
      ]
    }
  },
  "allOf": [
    {
      "$ref": "https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/data/header.schema.json"
    }
  ],
  "required": [
    "asset_group",
    "linked_asset_id",
    "linked_asset_kind",
    "linked_system_id",
    "relation_kind"
  ]
}

Example

{
  "transaction_id": "01950719-b154-72f5-8437-5572df032a69",
  "version": "0.1.0",
  "kind": "LINKAGE",
  "asset_id": "06bc53dc-3e4f-420b-801c-bd9cc0ea01b2",
  "asset_kind": "PERMIT",
  "system_id": "ITSM-5917",
  "linked_asset_id": "5d884469-d016-4b87-8d65-4a1520ae788b",
  "linked_asset_kind": "ANCHOR",
  "linked_system_id": "ITSM-10235",
  "relation_kind": "RELATES",
  "asset_group": {
    "system_id": "ITSM-5917",
    "asset_id": "13837ce4-1c93-4604-916f-777e33e8da0c",
    "asset_kind": "PROJECT"
  }
}

Implementation Guidance

Purpose

The Linkage message defines a specific relationship between a primary asset and a linked asset. Consuming systems may use this message to explicitly bind assets together.

Creating Linkage Messages

When generating a Linkage message:

• Include the linked_asset_id and linked_asset_kind of the asset being linked
• Specify the linked_system_id that owns the linked asset
• Provide the asset_group entity from the declaring system that describes or groups the relationship
• Declare the relation_kind to specify the nature of the link (MERGES, RELATES, SELF, SPLITS)
• Create separate messages for each unique asset pair or relationship type

Single-System Assertion

Each Linkage message must represent a single assertion from one system. Always create separate messages when an asset needs to assert multiple relationships.

Group Orthogonality

The Linkage message is orthogonal to the Group message, meaning that both can coexist and express the same relationships without conflict. While the Linkage message explicitly defines a relationship between an asset pair, the Group message implicitly binds a primary asset to a set of related assets. Systems may use both message types to represent different aspects of various asset relationships.

References

• Header