Permit 📝

Official URL: https://bcgov.github.io/nr-pies/docs/spec/element/resource/permit

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

Represents a permit. A permit may capture both on hold period information and process event history throughout an application process.

Scope

This resource type is intended to represent the set of properties associated with a permit record. A permit captures both on hold period information and process event history throughout the application process.

This resource type is transmitted within a Record message by setting asset_kind to PERMIT. A Permit is defined as an independent, composable resource type and may be used in other message contexts.

Refer to Record for details on the message envelope pattern and how resource types are selected.

Structure

Name	Cardinality	Type	Description & Constraints
on_hold_event_set	0..1	CodingEvent	A set of CodingEvents. Represents a set of on hold concepts at a specific event in time.
process_event_set	0..1	ProcessEvent	A set of ProcessEvents. Represents a set of unique process concepts at a specific event in time.

Specification

Schema

Loading ....

Source

{
  "$id": "https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/resource/permit.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Permit",
  "description": "Represents a permit.",
  "type": "object",
  "properties": {
    "on_hold_event_set": {
      "type": "array",
      "items": {
        "$ref": "https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/resource/coding_event.schema.json"
      },
      "uniqueItems": true
    },
    "process_event_set": {
      "type": "array",
      "items": {
        "$ref": "https://raw.githubusercontent.com/bcgov/nr-pies/refs/heads/main/docs/spec/element/resource/process_event.schema.json"
      },
      "uniqueItems": true
    }
  },
  "required": [
    "on_hold_event_set",
    "process_event_set"
  ]
}

Example

{
  "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_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."
      }
    }
  ]
}

Implementation Guidance

The Permit resource type defines specific constraints for maintaining reliable process history within the Application Process and On Hold Process workflows. It is designed to aggregate CodingEvent and ProcessEvent resources respectively.

When a Permit resource is aggregated and transmitted, the following constraints apply to maintain reliable process history:

Temporal Integrity and Workflow

The process_event_set represents the lifecycle of a record. To ensure this history is actionable for auditing and reporting, implementations should follow these constraints:

Implicit Linear Flow

The application process follows an implicit chronological progression (such as from SUBMITTED to TECHNICAL_REVIEW to ALLOWED).

• While the message may represent a subset of data, the events within the set should be sequence-aware.
• "Backward" jumps in state are strongly discouraged in the Application Process workflow.

Reference the Canonical Flow in the Application Process code system for specific details.

Uniqueness of Event Sets

To maintain a clean parsable process event sequence, all process_event_set elements must have unique codes.

• Systems shall not emit or repeat multiple active process_event entries with the same code for the same record.
• Map business domain transitions directly to the Application Process code system. Avoid intermediary code transformations that alias or misrepresent the source event.

Handling Holds and Overlaps

When a process is put on hold (such as waiting for applicant information during a technical review), use the on_hold_event_set to provide additional context.

• A process event that is stalled should remain open while its associated on hold events explain the delay.
• Populate the on_hold_event_set with granular events to explain the delay. This enables recipient systems to calculate the "net time" by subtracting on hold duration from total process_event duration.

The Permit resource type is intended to represent a permit record and its full lifecycle across the Application Process. In addition, it also provides tracking capabilities for On Hold Process.

It provides dual tracking capabilities for both on hold events and process events, allowing systems to maintain a complete history of the permit's journey:

• on_hold_event_set: Captures any periods when permit processing was suspended or placed on hold, typically due to missing information or other blockers.
• process_event_set: Documents the progression through defined process stages (e.g., APPLICATION, TECH_REVIEW_COMMENT, REFERRAL) with associated status information.

Systems managing permit records should maintain both event histories as necessary.

References

• Coding Event
• Coding
• Event
• Process Event
• Process