Group 🚧

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

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

Represents a message envelope for grouping related assets together.

Scope

This message type allows systems to group related assets together. The message represents an assertion from the originating system's perspective. Consuming systems must validate the grouping and implicitly trust the assertion source.

A Group message is scoped to a collection of related assets and captures the relationships between them, similar in structure to a linkage message but specific to asset groups.

Structure

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

info

A Group extends the following data types and inherits all of their declared attributes:

• Header

The table below identifies the inherited data types (in parentheses) and lists the properties declared directly by Group.

Name	Cardinality	Type	Description & Constraints
(Header)	1..1	Header	Represents the standard message tracking envelope, incorporating specific asset attributes for system and record identification.
asset_set	1..*	Asset[]	An array of assets that are grouped together with the primary header 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_set field expresses membership of assets within the group and typically originates from the declaring system:

• The asset_set 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 Group connects the primary asset (defined in Header) to related assets via this asset set

Specification

Schema

Loading ....

Source

{
  "$id": "https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/message/group.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Group",
  "description": "Represents a message envelope for grouping related assets together.",
  "type": "object",
  "properties": {
    "asset_set": {
      "type": "array",
      "description": "An array of assets that are grouped together with the primary header asset.",
      "minItems": 1,
      "items": {
        "$ref": "https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/data/asset.schema.json"
      }
    },
    "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_set",
    "relation_kind"
  ]
}

Example

{
  "transaction_id": "01950719-b154-72f5-8437-5572df032a69",
  "version": "0.1.0",
  "kind": "GROUP",
  "system_id": "ITSM-5917",
  "asset_id": "13837ce4-1c93-4604-916f-777e33e8da0c",
  "asset_kind": "PROJECT",
  "relation_kind": "RELATES",
  "asset_set": [
    {
      "asset_id": "06bc53dc-3e4f-420b-801c-bd9cc0ea01b2",
      "asset_kind": "PERMIT",
      "system_id": "ITSM-5917"
    },
    {
      "asset_id": "5d884469-d016-4b87-8d65-4a1520ae788b",
      "asset_kind": "ANCHOR",
      "system_id": "ITSM-10235"
    },
    {
      "asset_id": "bdb514d1-bb0d-49e3-b448-6b20e48d16e3",
      "asset_kind": "PERMIT",
      "system_id": "ITSM-6197"
    }
  ]
}

Implementation Guidance

Purpose

The Group message defines a specific relationship between a primary asset and a set of related assets. Consuming systems may use this message to implicitly bind assets together.

Creating Group Messages

When generating a Group message:

• Include the asset_set of assets being grouped
• Declare the relation_kind to specify the nature of the link (MERGES, RELATES, SELF, SPLITS)

Single-Relation Assertion

Each Group message must represent a single assertion from one system. Always create separate messages when an asset needs to assert different relationship kinds.

Linkage Orthogonality

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

References

• Header