Overview 🔬
This article outlines PIES specification maturity, type hierarchy, and formatting used by PIES. Topics covered include the terminology, syntax, encoding and the file format used by PIES, as well as how our type categories relate to each other.
Ontology
The PIES specification module provides an overview and guide to the resources, operations, coded datatypes and externally-defined standards used. Collectively, these resources provide the underlying functionality to support the use of coded data in PIES throughout the specification.
The primary specification-related structures and their relationships are shown below:
Inspired by HL7, each PIES resource serves a specific function:
| Resource | Description |
|---|---|
| Code System | A Code System defines a set of codes and their meanings. It serves as the authoritative source for a particular set of concepts. |
| Concept Map | A Concept Map is a resource that defines relationships between concepts in different code systems or value sets. It facilitates interoperability by mapping equivalent or related concepts across various terminologies, enabling systems to understand and process each other's data accurately. |
| Element Definition | An Element refers to a data type definition containing one or a set of values. When this value is coded, it is typically represented as a Coding data type, which is associated with a Code System. |
| Element Instance | A specific implementation or occurrence of a data element that adheres to its corresponding definition. It represents a concrete instance of the abstract structure defined by the Element Definition. |
| Naming System | A NamingSystem defines the unique identifiers (namespaces) used for codes. It provides metadata about the identifier system, such as its purpose and usage. |
| Value Set | A ValueSet is a collection of codes from one or more CodeSystems. It specifies which codes are allowed or required in a particular context. |
Maturity
The PIES specification is still actively being developed. While it has been developed to a point where it may be used for practical purposes, some areas of the specification will not be as fully defined or have not yet been tested. Refer to the following table for a description of each maturity level.
| Maturity Level | Emoji | Badge | Description |
|---|---|---|---|
| Deprecated | ⚠️ |  | This artifact is no longer recommended for use and may be removed in a future release. |
| Planning | 🚧 |  | This artifact is still in the early stages, where brainstorming, research, and organization are taking place. It is not yet ready for use yet. |
| Draft | 📝 |  | This artifact has a preliminary structure and is being reviewed for accuracy, completeness, and usability. It could be used, but some areas may still need improvement and may have major changes over time. |
| Trial | 🔬 |  | This artifact has been developed to a point where it may be used for practical purposes. It may be used, but some areas may still need refinement and may have minor changes over time. |
| Standard | None |  | This artifact has been fully developed and has been ratified as a part of the standard. It can be used in production environments. |
Each artifact in the specification may potentially be suffixed by an emoji indicating their maturity level. In addition, each artifact's page will also contain a maturity level badge.
Hierarchy
The PIES specification is organized into a hierarchy of artifacts, each with its own purpose and functionality. The following table provides an overview of the hierarchy:
| Type Class | Description |
|---|---|
| Data | Represents core, atomic data structures and their inherent attributes or properties. |
| Resource | Represents a composed or combined set of data types. The composition defines higher order relational concepts between the data types. |
| Message | Represents a composition of resource and data types. Message types are normally used for API based communication between systems or applications. |
Type Hierarchy
The fundamental idea of the PIES hierarchy is that the fundamental data types can be grouped together into resources which explain more complex ideas or topics. The resources can then be used to create more complex resource types or messages. Messages will consist of a mixture of resource and/or data types, and the set of all types within their definition should create a cohesive chunk of information that can be used for interchange and communication purposes. The following diagram shows how these types are related to each other:
Formatting
Every data standard must have a core set of fundamental data types that content will be transmitted in. Since the
Permitting Interoperability Exchange Specification is built on top of the JSON Schema
standard, it will leverage the conventions specified in that standard, including
RFC 8259 which defines JSON. The PIES specification will be compliant
to the draft 07 specification of the JSON Schema standard. While there exists more recent draft versions, notably the
draft 2020-12 standard, features that were introduced after draft 07 will not be defined and used at this time in
order to maximize compatibility with implementor systems.
JSON Schema Primer
A JSON Schema is commonly used to define, annotate and verify JSON structured documents and content. It serves as a way to explicitly define the structural expectations for a specific type of document. While JSON Schema is good for describing expected structures, describing conceptual relationships between related topics and domains
A JSON Schema will typically contain the following attributes:
$schema- This describes the draft level this JSON Schema complies to.- This property value SHALL be
http://json-schema.org/draft-07/schema#. - This must be verbatim, with
httpand the trailing#. Any deviations will cause certain parsers like AJV to fail to parse correctly.
- This property value SHALL be
$id- The unique URI for this schema. The path should ideally contain an obvious versioning nomenclature.$comment- A free text field for conveying out of band information about the schema. Comments are useful for specification readers and editors to understand further nuances for certain properties and structures, but should not be relied upon for implementation as they may be skipped over or stripped when parsed by machines.title- The intent of the schema. This should be brief and concise.description- A brief description about the schema. This should provide a quick overview for the context of usage.properties- A set of attributes that are expected to show up in this document type.required- An array defining the set ofpropertiesthat must be present for the document to be considered valid. Anything defined that is not in this array is implied to be optional.type- The type primitive constraint for the property.