Header 📝
Official URL: https://bcgov.github.io/nr-pies/docs/spec/element/data/header
JSON Schema URL: https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/data/header.schema.json
Represents the standard message tracking envelope, incorporating specific asset attributes for system and record identification. All defined attributes are needed for asset identification and attribution and are present for all PIES message data types.
Scope
This data type is intended to define all expected attributes that a message datatype must contain at minimum. This data structure is not intended for standalone use.
Structure
A Header extends the following data types and inherits all of their declared attributes:
The table below identifies the inherited data types (in parentheses) and lists the properties declared directly by Header.
| Name | Cardinality | Type | Description & Constraints |
|---|---|---|---|
| (Asset) | 1..1 | Asset | Standard message asset attributes present for all PIES message data types. |
| transaction_id | 1..1 | string | A unique UUIDv7 assigned for this specific message. |
| version | 1..1 | string | The PIES specification version this message complies to. Value shall be a valid semantic version formatted string. |
| kind | 1..1 | Code | A valid Message Kind code which identifies the specific kind of PIES message data type this message represents. |
Specification
- Schema
- Source
- Example
{
"$id": "https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/data/header.schema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Header",
"description": "Represents the standard message tracking envelope, incorporating specific asset attributes for system and record identification.",
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "A unique UUIDv7 assigned for this specific message.",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
},
"version": {
"type": "string",
"description": "The PIES specification version this message complies to. Value shall be a valid semantic version formatted string.",
"pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$"
},
"kind": {
"type": "string",
"description": "The specific kind of PIES message data type this message represents.",
"enum": [
"GROUP",
"LINKAGE",
"RECORD"
]
}
},
"allOf": [
{
"$ref": "https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/data/asset.schema.json"
}
],
"required": [
"transaction_id",
"version",
"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"
}
Implementation Guidance
All header and asset attributes are mandatory. A valid PIES message datagram must define all of the header and asset attributes.