Technical Documents
Overview
Tech Documents
Templates
Version Control
Version Control is the practice of tracking and managing changes to documents or software code.
Semantic Versioning
-
Technical Specifications go under Version Control (Vx.y.z) as soon as the first draft has been agreed by the Working Group.
-
When Technical Document(s) have been Approved then any further changes to the document(s) require creating a new set of the document(s) under different versions, e.g., from V1.0 to V1.0.1.
The criteria for choosing the new version of an APPROVED document follows the principles of Semantic Versioning and are as follows:
| Field | Use | Description |
|---|---|---|
| X | Major Version Indicator | This field is mandatory and identifies the MAJOR version of the document as determined by the Working Group.
MAJOR versions contain major feature additions; MAY contain incompatibilities with previous document or specification revisions; and MAY change, drop, or replace existing interfaces. Initial releases are version "V1.0". |
| Y | Minor Version Indicator | This field is mandatory and identifies the MINOR version of the document—this digit version increments in one when the approved document is modified.
MINOR versions MAY contain minor feature additions, are compatible with the preceding MAJOR_MINOR specification revision, and provide evolving interfaces. The initial MINOR release for any MAJOR release is "0", i.e., 1.0 |
| Z | Service Indicator | This third digit is optional but recommended to identify bug fixes or editorial changes. It is called Service Indicator (SI).
The digit increments every time a corrective update - Approved by the Working Group and Ratified by the parent group - is applied to the document already under version control. The first Service Indicator release SHALL be "_1" for any MAJOR_MINOR release, e.g., V1.0.1. Service Indicators are compatible with the MAJOR_MINOR release they relate to but add bug fixes. MAJOR or MINOR changes to the documents under Version Control cannot be classified with a change on the Service Indicator |
Intellectual Property Rights
Copyright
This section provides a recommendation based on the best practice implemented by other projects.
Most LF project communities do not require or recommend that every contributor include their copyright notice in contributed files.
Instead, many LF Project communities recommend using a more general statement in a form similar to the following: (choose one)
Copyright The Open Mobile Alliance Authors.Copyright The Open Mobile Alliance Contributors.Copyright Contributors to the XYZ project.
These statements are intended to communicate the followig:
- the work is copyrighted;
- the contributors of the code licensed it, but retain ownership of their copyrights, and
- it was licensed for distribution as part of the Open Mobile Alliance publications.
With any of the above statements, the project avoids having to maintain lists of names of the authors or copyright holders, years or ranges of years, and variations on the (c) symbol. This aims to minimize the burden on the contributors and Chairs.
This section provides a recommended format for easy of use, but it is not mandated.
Reasons to Avoid Listing Copyright Holders
These are some of the reasons why Open Mobile Alliance does not recommend trying to list every copyright holder for contributions to every file:
- Copyright notices are not mandatory in order for the contributor to retain ownership of their copyright.
- Copyright notices are rarely kept up to date as documentation evolves, resulting inaccurate statements.
- Trying to keep notices up to date, or to correct notices that have become inaccurate, increases the burden on editors and Chairs without tangible benefit.
- Editors and Chairs often do not want to have to worry about e.g. whether a minor contribution (such as a type fix) means that a new copyright notice should be added.
Other Copyright Rules
Software Licenses
In a .XML File
The example below describes the metadata (file information, Normative Information and Legal Disclaimer) of a LwM2M Object.
<?xml version="1.0" encoding="UTF-8"?>
<!--
FILE INFORMATION
OMA Permanent Document
Name: OMA-SUP-XML_21-V2_0-20211123-A.xml
Path: http://www.openmobilealliance.org/release/ObjLwM2M_OSCORE/
OMNA LwM2M Registry
Name: 21.xml
Path: https://github.com/OpenMobileAlliance/lwm2m-registry
NORMATIVE INFORMATION
Information about this file can be found in the latest revision of OMA-TS-LightweightM2M_Core-V1_2.
This is available at http://www.openmobilealliance.org/release/LightweightM2M/
Send comments to https://github.com/OpenMobileAlliance/OMA_LwM2M_for_Developers/issues.
LEGAL DISCLAIMER
Copyright 2023 Open Mobile Alliance.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its
contributors may be used to endorse or promote products derived
from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
The above license is used as a license under copyright only. Please
reference the OMA IPR Policy for patent licensing terms:
https://www.omaspecworks.org/about/intellectual-property-rights/
-->
In a .JSON File
In this example, we describe the same metadata information (file information, Normative Information and Legal Disclaimer) but expressed in a JSON file.
{
"info": {
"permanent_document":
{
"file": "OMA-SUP-XML_0-V1_2-20201110-A.xml",
"path": "http://www.openmobilealliance.org/release/ObjLwM2M_Security/"
},
"lwm2m_registry":
{
"file": "0.xml",
"path": "https://github.com/OpenMobileAlliance/lwm2m-registry"
},
"normative_information":
{
"ts": "OMA-TS-LightweightM2M_Core-V1_2",
"ts_url": "http://www.openmobilealliance.org/release/LightweightM2M/",
"bug_reporting": "https://github.com/OpenMobileAlliance/OMA_LwM2M_for_Developers/issues"
},
"legal_disclaimer":
{
"spdx-license-identifier": "BSD-3-OMA",
"copyright": "2020 Open Mobile Alliance"
}
},
"namespace": {
"oma": "https://openmobilealliance/lwm2m"
},
"defaultNamespace": "oma",
"sdfObject": {
}
}
In a README.md
In some ocassions you may want to insert a badge in a markdown file on GitHub containing the Software License for an OMA LwM2M Objects. The SPDX License Identifier for an OMA LwM2M Object is: BSD-3-OMA.
- SPDX-License-Identifier: BSD-3-OMA
The badge for this license is:
This badge displays as:
Document License
All OMA Technical Documents MUST contain the following legal disclaimer:
Use of this document is subject to all of the terms and conditions of the Use Agreement located at
https://www.omaspecworks.org/about/policies-and-terms-of-use/.
Unless this document is clearly designated as an approved specification, this document is a work in process, is not an
approved Open Mobile Alliance™ specification, and is subject to revision or removal without notice.
You may use this document or any part of the document for internal or educational purposes only, provided you do not modify, edit or take out of context the information in this document in any manner. Information contained in this
document may be used, at your sole risk, for any purposes. You may not use this document in any other manner without
the prior written permission of the Open Mobile Alliance. The Open Mobile Alliance authorizes you to copy this
document, provided that you retain all copyright and other proprietary notices contained in the original materials on
any copies of the materials and that you comply strictly with these terms. This copyright permission does not constitute
an endorsement of the products or services. The Open Mobile Alliance assumes no responsibility for errors or omissions
in this document.
Each Open Mobile Alliance member has agreed to use reasonable endeavors to inform the Open Mobile Alliance in a
timely manner of Essential IPR as it becomes aware that the Essential IPR is related to the prepared or published
specification.
However, the members do not have an obligation to conduct IPR searches. The declared Essential IPR is publicly
available to members and non-members of the Open Mobile Alliance and may be found on the “OMA IPR Declarations”
list at https://www.omaspecworks.org/about/intellectual-property-rights/. The Open Mobile Alliance has not
conducted an independent IPR review of this document and the information contained herein, and makes no
representations or warranties regarding third party IPR, including without limitation patents, copyrights or trade secret
rights. This document may contain inventions for which you must obtain licenses from third parties before making,
using or selling the inventions. Defined terms above are set forth in the schedule to the Open Mobile Alliance
Application Form.
NO REPRESENTATIONS OR WARRANTIES (WHETHER EXPRESS OR IMPLIED) ARE MADE BY THE OPEN MOBILE
ALLIANCE OR ANY OPEN MOBILE ALLIANCE MEMBER OR ITS AFFILIATES REGARDING ANY OF THE IPR’S
REPRESENTED ON THE “OMA IPR DECLARATIONS” LIST, INCLUDING, BUT NOT LIMITED TO THE ACCURACY,
COMPLETENESS, VALIDITY OR RELEVANCE OF THE INFORMATION OR WHETHER OR NOT SUCH RIGHTS ARE
ESSENTIAL OR NON-ESSENTIAL.
THE OPEN MOBILE ALLIANCE IS NOT LIABLE FOR AND HEREBY DISCLAIMS ANY DIRECT, INDIRECT, PUNITIVE,
SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR EXEMPLARY DAMAGES ARISING OUT OF OR IN CONNECTION WITH THE
USE OF DOCUMENTS AND THE INFORMATION CONTAINED IN THE DOCUMENTS.
THIS DOCUMENT IS PROVIDED ON AN "AS IS" "AS AVAILABLE" AND "WITH ALL FAULTS" BASIS.
Copyright 2020 Open Mobile Alliance.
Used with the permission of the Open Mobile Alliance under the terms set forth above.