https://docs.oasis-open.org/niemopen/niem-pubs/v1.0/pn01/niem-pubs-v1.0-pn01.md
(Authoritative)
https://docs.oasis-open.org/niemopen/niem-pubs/v1.0/pn01/niem-pubs-v1.0-pn01.html
https://docs.oasis-open.org/niemopen/niem-pubs/v1.0/pn01/niem-pubs-v1.0-pn01.pdf
N/A
https://docs.oasis-open.org/niemopen/niem-pubs/v1.0/niem-pubs-v1.0.md
(Authoritative)
https://docs.oasis-open.org/niemopen/niem-pubs/v1.0/niem-pubs-v1.0.html
https://docs.oasis-open.org/niemopen/niem-pubs/v1.0/niem-pubs-v1.0.pdf
NIEM Technical Architecture Committee (NTAC) of the OASIS NIEMOpen OP
Katherine Escobar (katherine.b.escobar.civ@mail.mil), Joint Staff J6
Jim Cabral (jim.cabral@infotrack.com), InfoTrack US
Scott Renner (sar@mitre.org), MITRE
Jim Cabral (jim.cabral@infotrack.com), InfoTrack
Christina Medlin (christina.medlin@gtri.gatech.edu),
GTRI
This document is related to:
This document describes the terminology, deliverables, versioning, stages and processes involved in publishing a NIEMOpen version, including the model, specifications and tools.
This is a Non-Standards Track Work Product. The patent provisions of the OASIS IPR Policy do not apply.
This document was last revised or approved by the Project Governing Board of the OASIS NIEMOpen OP on the above date. The level of approval is also listed above. Check the "Latest stage" location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Open Project (OP) are listed at http://www.niemopen.org/.
Comments on this work can be provided by opening issues in the project repository or by sending email to the project's public comment list: niemopen-comment@lists.oasis-open-projects.org. List information is available at https://lists.oasis-open-projects.org/g/niemopen-comment.
When referencing this document the following citation format should be used:
[NIEM-Publication-v1.0]
NIEMOpen Publication Process Version 1.0. Edited by Jim Cabral and Christina Medlin. 02 May 2023. OASIS Project Note 01. https://docs.oasis-open.org/niemopen/niem-pubs/v1.0/pn01/niem-pubs-v1.0-pn01.html. Latest stage: https://docs.oasis-open.org/niemopen/niem-pubs/v1.0/niem-pubs-v1.0.html.
Copyright © OASIS Open 2023. All Rights Reserved.
Distributed under the terms of the OASIS IPR Policy.
For complete copyright information please see the full Notices section in Appendix D.
This document describes the means by which the NIEM reference data model and technical specifications are updated and published. It identifies processes, artifacts, and responsibilities for new versions of NIEM. It also establishes a regular cycle for predictable and manageable NIEM updates.
The NBAC manages the content of the NIEM reference data model, which is made up of Core, domains, and other namespaces. The NTAC manages the NIEM technical specifications, which define the architecture of the reference data model and the community-built extension data models and message specifications. Both TSCs work together to manage domain and community needs, maintain coherence between the model and the specifications that govern it, and to update artifacts for new NIEM versions.
NIEMOpen (or NIEM) refers to the NIEM Open Project under OASIS.
The NIEM community refers to the organizations and people who use NIEM, which started in 2005.
NIEM includes a reference data model (or model) and technical specifications, which govern the architecture of the NIEM model.
NIEM followed by a version number (e.g., NIEM 6.0) refers to a specific version of the NIEM model and technical specifications.
The NTAC is a NIEMOpen Technical Steering Committee, responsible for the technical specifications that govern the NIEM technical architecture.
The NBAC is a NIEMOpen Technical Steering Committee, responsible for the NIEM business architecture, the management of the content in NIEM Core, and the support of NIEM domains. It includes representatives from NIEM domain subcommittees.
NIEM Core is a namespace in the model with content that is managed collaboratively by the NBAC. This content tends to be general-purpose, widely-used, and governance does not belong to any one authoritative source.
A NIEM domain refers to content in the model that is associated with and governed by a specific segment of government or industry. Its content is managed by its corresponding NBAC domain subcommittee, with oversight provided by the NBAC.
NIEM utility schemas are defined by the NDR and other technical specifications to support architectural requirements in the model. They are managed by the NTAC and are also included among the schemas representing the model.
The NBAC's Harmonization Subcommittee is responsible for reviewing Core and cross-domain content issues and provides recommendations for Core changes to the NBAC for approval.
Note: NIEM is no longer an acronym.
The NIEM Publication Process MUST comply with OP requirements (see sections 11-14) including:
NIEM versions are scheduled annually on a 3-year cycle. A NIEM major version one year will be followed by minor versions the next two years. Patch versions will be published as needed. The schedule can be delayed or adjusted, however, by the PGB.
NIEM technical specifications follow semantic versioning practices. They are typically only updated for major versions.
The NIEM data model follows a variation to semantic versioning practices. This versioning strategy attempts to balance stability vs flexibility for the community by treating Core and domain changes separately:
Core carries content that is often broadly reusable across the community. Changes to this namespace can have a greater impact on a wider range of users, so stability is more important here.
Domains carry content to represent their own communities of interest. Domain subcommittees are responsible for the needs of their communities, are closer to their user base, and are given greater flexibility in managing their content.
As such, the versioning strategy that the NIEM model employs is that only the Core namespace follows semantic versioning:
Major versions MAY include breaking changes to any content (including Core and domains) and the architecture (defined by the technical specifications).
Minor versions MAY only include non-breaking changes to Core and the architecture (e.g., additions, minor documentation edits); however, domains and other non-utility namespaces MAY include breaking changes.
Because older NIEM versions remain available and implementers are never required to migrate outside of their own and their data exchange partners' needs, this approach has provided a workable middle-ground to responsively meet community needs.
Patch versions MAY only include non-breaking changes. Additions and changes to existing NIEM content are published in separate namespaces that may be used in message model schemas alongside the original data model schemas.
Patch versions can be used for bug fixes, adding new content, and "updating" existing content. Since the breaking changes cannot be made to the original namespaces in a patch, alternate components can be published separately and can be used in message specifications as needed in place of the originals.
Note that:
Each NIEM major version:
MUST increment the first digit in the version number.
MAY include breaking changes to the model and technical specifications from their previous versions
SHOULD include a new major version of the data model, with content changes managed by the NBAC and architectural changes managed by the NTAC
MAY include major version updates to some or all of the technical specifications (e.g., Naming and Design Rules, Common Model Format), with changes managed by the NTAC
SHOULD include a release of any normative tools or code that is required for conforming or verifying conformance with the model or specifications (e.g., NDR Schematron rules)
SHOULD include a release of any tools or code that were instrumental to building the model or specifications
SHOULD include a public review of the updated model and technical specification as Project Specification Drafts (PSD) before moving to further publication stages
SHOULD progress to OASIS Project Specification(s) (PS)
MAY be submitted for an OASIS Standard(s) in the following year and later be submitted for ISO standard(s)
Each NIEM minor version:
MUST increment the second digit in the version number.
MAY include non-breaking changes to Core and to technical specifications from the previous versions
MAY include breaking changes to domains, code set namespaces, and other namespaces not imported by Core
MAY include updates to the normative or non-normative tools or code from previous versions
MAY address any defects in the model or technical specifications in errata
MAY include a public review of the updated model and any updated technical specifications as Project Specification Drafts
SHOULD progress to OASIS Project Specification(s)
Each NIEM patch version:
MUST increment the third digit in the version number.
MAY include only non-breaking updates to the model, with changes published in the original or in new namespaces as appropriate.
MAY include only non-breaking updates to the technical specifications, with changes that do not affect the conformance of the model or of NIEM community message specifications.
MAY include changes such as bug fixes, new domains or new content for existing domains or Core, and alternate representations of existing content as a means of making updates without affecting backwards compatibility.
SHOULD progress to OASIS Project Specification.
Specification version numbers SHOULD NOT be bumped to stay in sync with a NIEM major or minor version if the specification itself is unchanged.
Namespace version numbers in the model:
SHOULD NOT be bumped in sync with a NIEM minor version if the namespace itself and all namespaces it references are unchanged.
For example, a NIEM 6.2 minor version may contain namespaces with versions remaining at 6.0 and 6.1.
SHOULD be bumped in sync with a NIEM minor version if the namespace or any namespace it references is changed.
For example, the version of a namespace with new updates may be bumped directly from 6.0 to 6.2 if there were no changes to it in NIEM 6.1.
The NIEM model:
NIEM technical specifications:
Comment resolution logs:
Change comparison documents:
Approved project work products MUST be published at https://docs.oasis-open.org/niemopen, including:
NIEMOpen GitHub repositories:
The model specification and technical specification repositories are listed below:
| Specification | NIEMOpen repository |
|---|---|
| Model | https://github.com/niemopen/niem-model |
| Code Lists | pending |
| CMF | https://github.com/niemopen/common-model-format |
| Conformance | pending |
| CTAS | https://github.com/niemopen/niem-conformance-targets |
| NDR | https://github.com/niemopen/niem-naming-design-rules |
GitHub branches SHOULD be used to separate working contributions and drafts vs PGB-approved products, e.g.,
main: PGB-approved Project Specificationsdev: working drafts with incremental changes6.0-psd01Other OASIS resources may be used to support NIEM, including:
Prior to coming an OASIS Open Project, NIEM resources were managed and published at different locations.
The following is general information that will apply during the development and publication process of a NIEM version.
For each major or minor version, the NTAC, NBAC, and PGB SHOULD coordinate and prepare a schedule at the beginning of the year to include:
The schedule MAY continue to be adjusted throughout the year as needed.
Each domain in NIEM is governed by its own NBAC domain subcommittee, or is governed in conservatorship by the NBAC or an appointed steward. Each domain subcommittee SHOULD nominate a person or persons who are authorized to make domain content decisions and changes on their behalf.
Data stewards SHOULD also be appointed for code set namespaces and any other namespace in the model which has active representation from an authoritative source.
Before becoming approved by the NBAC, data stewards:
Public reviews are optional for OASIS Open Projects before the OASIS Standard approval stage.
Requirements for a Public Review of a NIEMOpen PSD include:
The following are the steps for a NIEM PSD Public Review:
If material changes result from a public review, then:
If only non-material changes results from a public review, then:
When submitting a draft to the PGB for approval as a PSD or PS:
Once issues targeted for the current version have been resolved or the schedule deadline has been reached and the artifacts have been updated:
6.0-psd01) to the commit once the draft has been finalized
and published by OASIS admin to ensure there are no non-material changes
required during the publication.dev branch
as a GitHub draft release.The PSD approval process will iterate until there are no further material changes left to be made to the draft.
Once the TSCs have resolved feedback on the PSD and have prepared the necessary artifacts:
Note that the date an approved vote closes is considered the specification publication date.
dev branch in to the
main branch.6.0-ps01) to the
new commit.NIEM major and minor versions follow a schedule. Patch versions are published on an ad hoc basis.
This section describes the stages in publishing a minor version and the steps during each stage of this process. As the technical specifications are typically not updated during minor versions, this section focuses on NBAC processes for updating the data model.
Domain subcommittees and their data stewards are responsible for leading the efforts to update their domains. The NBAC Harmonization Subcommittee and maintainers are responsible for managing updates to Core and other namespaces without data stewards, including many code set namespaces.
Domains MAY include breaking changes in a minor version.
Domain data stewards wishing to update their content SHOULD prepare changes in one of two ways, according to the data steward's preference:
dev branch and submitted
as a pull request.A maintainer SHOULD review the submitted changes and perform quality assurance (QA) checks and other model updates, which include:
A domain data steward and maintainer SHOULD collaborate on updating the initial change submission until quality assurance checks have passed.
For approved change requests submitted as updated XML schema in a pull request:
For approved change requests submitted as a change request spreadsheet:
Once changes are accepted, a maintainer SHOULD update the content in any tools needed to build reference schemas, subset schemas, and artifacts for the version.
Domain data stewards MAY repeat the process as needed within the permitted time frame for updates.
Other namespaces besides domains that do not impact Core MAY include breaking changes in a minor version. These other namespaces include code set namespaces, adapters and external standards, and auxiliary content.
Updates to these namespaces SHOULD follow a very similar process to the domain content update process described in Section 6.1.1 Domain content updates (breaking). The major difference is in the roles and responsibilities of the participants:
Some content will be actively managed by a participating authoritative source.
Some content will be managed by the NBAC.
Core and Core-dependent namespaces (primarily utility schemas) MAY only introduce non-breaking changes in minor versions.
Non-breaking changes include:
Breaking changes, which are not permitted, include:
Maintainers and the Harmonization Subcommittee SHOULD fulfill similar roles defined in 6.1.2 Other non-Core namespace content updates (breaking) for content managed by the NBAC. Both will have the additional responsibility of ensuring that the content changes are non-breaking.
Non-breaking changes MAY be made directly in the Core namespace instead of a new additive-only namespace for Core changes. Note:
The process of publishing a major version of the data model follow many of the same processes as in 6.1 Publishing a NIEM minor versions. Additions or differences to the process include:
The NBAC, the Harmonization Subcommittee (HSC), and the NTAC will also need to manage additional issues related to Core:
The NTAC will manage updates to technical specifications primarily during major versions, Specification updates:
Major specification changes:
The NBAC, NTAC, or domain subcommittees MAY choose to issue patches to a major or minor version following the processes above, with the following adjustments:
6.0.1.This appendix contains the informative references that are used in this document.
While any hyperlinks included in this appendix were valid at the time of publication, OASIS cannot guarantee their long-term validity.
Substantial contributions to this document from the following individuals are gratefully acknowledged:
| First Name | Last Name | Company |
|---|---|---|
| Jim | Cabral | InfoTrack US |
| Tom | Carlson | GTRI |
| Christina | Medlin | GTRI |
| Scott | Renner | MITRE |
| Duncan | Sparrell | sFractal Consulting |
The following individuals have participated in the creation of this document and are gratefully acknowledged:
NIEM Technical Architecture Committee (NTAC) TSC Members:
| First Name | Last Name | Company |
|---|---|---|
| Aubrey | Beach | Joint Staff J6 |
| Jim | Cabral | InfoTrack US |
| Tom | Carlson | GTRI |
| Mike | Douklias | Joint Staff J6 |
| Katherine | Escobar | Joint Staff J6 |
| Mike | Hulme | Unisys |
| Eric | Jahn | Alexandria Consulting |
| Dave | Kemp | NSA |
| Vamsikrishna | Kondannagari | DHS |
| Peter | Madruga | GTRI |
| Christina | Medlin | GTRI |
| Joe | Mierwa | Mission Critical Partners |
| Scott | Renner | MITRE |
| Duncan | Sparrell | sFractal Consulting |
| Jennifer | Stathakis | FBI |
| Stephen | Sullivan | BAH |
| Revision | Date | Editor | Changes Made |
|---|---|---|---|
| niem-pubs-v1.0-pn01 | 2023-03-28 | Jim Cabral and Christina Medlin | Initial version |
Copyright © OASIS Open 2023. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
This document is published under Attribution 4.0 International (CC BY 4.0).
All contributions made to this project have been made under the OASIS Contributor License Agreement (CLA).
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark/ for above guidance.