Record 📝

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

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

Represents a message envelope for transmitting asset records.

Scope

This message type serves as a transport envelope for transmitting records between systems. A Record message combines Header metadata (transaction tracking, asset identification) with a resource payload selected via asset_kind.

The Record message can be composed of either an Anchor, Permit, or Project resource type defined in the specification. Refer to the Type Hierarchy for how messages, resources and data types compose together.

Structure

A Record message shall contain all flattened Header properties.

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

Records shall declare an asset_kind property value as defined in Asset Kind:

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

Name	Cardinality	Type	Description & Constraints
(header fields)	(varies)	Header	Standard Header properties, including the asset_kind selector (see below)

Bindings

The asset_kind field acts as a type selector, binding and identifying which resource type this message contains:

• asset_kind: ANCHOR - Message payload conforms to Anchor resource schema
• asset_kind: PERMIT - Message payload conforms to Permit resource schema
• asset_kind: PROJECT - Message payload conforms to Project resource schema

This selection is enforced at the schema level via conditional if/then logic.

Specification

Schema

Loading ....

Source

{
  "$id": "https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/message/record.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Record",
  "description": "Represents a message envelope for transmitting asset records.",
  "type": "object",
  "allOf": [
    {
      "$ref": "https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/data/header.schema.json"
    },
    {
      "title": "Permit",
      "description": "Represents a permit via asset_kind.",
      "type": "object",
      "if": {
        "properties": {
          "asset_kind": {
            "const": "PERMIT"
          }
        }
      },
      "then": {
        "$ref": "https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/resource/permit.schema.json"
      }
    },
    {
      "title": "Permit (Legacy)",
      "description": "Represents a permit via record_kind.",
      "type": "object",
      "if": {
        "properties": {
          "record_kind": {
            "const": "Permit"
          }
        }
      },
      "then": {
        "$ref": "https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/resource/permit.schema.json"
      }
    },
    {
      "title": "Anchor",
      "description": "Represents an anchor via asset_kind.",
      "type": "object",
      "if": {
        "properties": {
          "asset_kind": {
            "const": "ANCHOR"
          }
        }
      },
      "then": {
        "$ref": "https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/resource/anchor.schema.json"
      }
    },
    {
      "title": "Project",
      "description": "Represents a project via asset_kind.",
      "type": "object",
      "if": {
        "properties": {
          "asset_kind": {
            "const": "PROJECT"
          }
        }
      },
      "then": {
        "$ref": "https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/resource/project.schema.json"
      }
    }
  ]
}

Example

Anchor kind

{
  "transaction_id": "019f43ca-81cd-750e-a910-a7ab29d5205b",
  "version": "0.1.0",
  "kind": "RECORD",
  "asset_id": "12345678",
  "asset_kind": "ANCHOR",
  "system_id": "ITSM-5816"
}

Permit kind

{
  "transaction_id": "01950719-b154-72f5-8437-5572df032a69",
  "version": "0.1.0",
  "kind": "RECORD",
  "asset_id": "06bc53dc-3e4f-420b-801c-bd9cc0ea01b2",
  "asset_kind": "PERMIT",
  "system_id": "ITSM-5917",
  "on_hold_event_set": [
    {
      "event": {
        "start_date": "2024-12-10",
        "end_date": "2024-12-20"
      },
      "coding": {
        "code": "MISSING_INFORMATION",
        "code_set": [
          "MISSING_INFORMATION"
        ],
        "code_system": "https://bcgov.github.io/nr-pies/docs/spec/code_system/on_hold_process"
      }
    }
  ],
  "process_event_set": [
    {
      "event": {
        "start_datetime": "2024-11-30T00:21:20.575Z"
      },
      "process": {
        "code": "PRE_APPLICATION",
        "code_display": "Pre-Application",
        "code_set": [
          "APPLICATION",
          "PRE_APPLICATION"
        ],
        "code_system": "https://bcgov.github.io/nr-pies/docs/spec/code_system/application_process"
      }
    },
    {
      "event": {
        "start_date": "2024-12-01",
        "end_date": "2024-12-31"
      },
      "process": {
        "code": "REFERRAL",
        "code_set": [
          "APPLICATION",
          "TECH_REVIEW_COMMENT",
          "REFERRAL"
        ],
        "code_system": "https://bcgov.github.io/nr-pies/docs/spec/code_system/application_process",
        "status": "Auditing",
        "status_code": "AU",
        "status_description": "The authorization request is under review by subject matter expert."
      }
    },
    {
      "event": {
        "start_date": "2025-01-01"
      },
      "process": {
        "code": "DISALLOWED",
        "code_set": [
          "APPLICATION",
          "DECISION",
          "DISALLOWED"
        ],
        "code_system": "https://bcgov.github.io/nr-pies/docs/spec/code_system/application_process",
        "status": "DeclinedConflict",
        "status_description": "The authorization request has not been allowed due to a conflict of interest."
      }
    }
  ]
}

Implementation Guidance

Type Selection Pattern

The Record message uses a type selector pattern:

-- The asset_kind field declares which resource type the payload contains -- Systems generating records must declare a valid Asset Kind type -- The values must match the actual resource schema of the message payload -- Schema validation uses if/then logic to enforce the match

Resource-Specific Constraints

Each resource type that can be composed with Record defines its own constraints. Refer to the appropriate resource documentation:

• Anchor - Foundational reference point
• Permit - A permit record
• Project - A grouping of related records

Systems should provide all known element definitions whenever available. Recipient systems must not assume a single message provides the full transactional state. Recipient systems should request additional Records if needed.

Choosing a Resource Type

When generating a Record message, use asset_kind to select the appropriate resource type:

Use asset_kind ANCHOR when the message is a reference point without state, for instance:

• Establishing a baseline or foundational record
• Registering a record for future association
• Signaling record existence without process or hold context

Use asset_kind PERMIT when the message carries a permit's state, for instance:

• Sharing a permit's journey through an application workflow
• Conveying hold periods and reasons for review delays
• Providing an auditable event history

Use asset_kind PROJECT when the message is describing a grouping of related assets, for instance:

• Defining a project that encompasses multiple related assets

References

Message Structure

• Asset
• Header

Composable Resource Types

• Anchor
• Permit
• Project

Design Principles

• Guidelines
• Type Hierarchy