2 Structure

2.1 Use a generic ASAM specification section structure (ASM-22)

  • The section structure of ASAM specifications shall always follow the same pattern.

  • The sequence, headings and the numbering of the first and last sections are fixed.

  • The first section with a specification-specific heading and specification-specific content is the 6th section.

  • The amount of annexes is specification specific. An annex can be normative or informative, which is stated in brackets in the heading of the annex.

  • The specification contains a bibliography.

  • The specification contains a list of figures and a list of tables.

    The specification does not contain a list of source code blocks.

The generic section structure and headings are as follows, the text in brackets comment on the content:

Foreword
Introduction (specification-specific content)
    Overview (specification-specific content)
    Conventions and notations (specification-specific content)
        Modal verbs (fixed content as defined in rule ASM-21)
        Normative and informative content (fixed content as defined in rule ASM-91)
    Deliverables (specification-specific content)
1 Scope (specification-specific content)
2 Normative references (specification-specific content)
3 Terms and definitions (specification-specific content)
4 Abbreviations (specification-specific content)
5 Backward compatibility (specification-specific content)
6 (First specification-specific heading and content)
Annexes (specification-specific content)
    Annex A (normative or informative): (specification-specific heading and content)
    Annex B (normative or informative): (specification-specific heading and content)
Bibliography (specification-specific content)
List of figures (content is generated automatically)
List of tables (content is generated automatically)

Exceptions

There are no exceptions.

Example

Foreword
Introduction
    Overview
    Conventions and notations
    Deliverables
1 Scope
2 Normative references
3 Terms and definitions
4 Abbreviations
5 Backward compatibility
6 General architecture
    6.1 File Structure
    6.2 Combining Files
    6.3 Overview of elements
    6.4 Attributes used in the file
    6.5 General rules and assumptions
7 Additional data
    7.1 User Data
    7.2 Including Data
    7.3 Using different layout types
    7.4 Description of the data quality
8 Coordinate systems
    8.1 Coordinate systems overview
    8.2 Inertial coordinate systems
    8.3 Reference line coordinate systems
    8.4 Local coordinate systems
    8.5 Summary of all available coordinate systems
    8.6 Georeferencing in ASAM OpenDRIVE
9 Geometry
    9.1 Road reference line
    9.2 Straight line
    9.3 Spiral
    9.4 Arc
    9.5 Generating arbitrary road courses from geometry elements
    9.6 Cubic polynom (deprecated)
    9.7 Parametric cubic curve
10 Roads
    10.1 Properties for road sections and cross section
    10.2 Road linkage
    10.3 Road type
    10.4 Methods of elevation
    10.5 Road surface
    10.6 Use cases for roads
11 Lanes
    11.1 Lane grouping within lane sections
    11.2 Lane sections
    11.3 Lane offset
    11.4 Lane linkage
    11.5 Lane properties
    11.6 Road markings
    11.7 Specific lane rules
12 Junctions
    12.1 Common junctions
    12.2 Incoming roads
    12.3 Connecting roads
    12.4 Direct junctions
    12.5 Virtual junctions
    12.6 Road surface within junctions
    12.7 Junction groups
    12.8 Controllers for junctions
13 Objects
    13.1 Repeating objects
    13.2 Object outline
    13.3 Object material
    13.4 Lane validity for objects
    13.5 Access rules to parking spaces
    13.6 Object marking
    13.7 Object borders
    13.8 Object reference
    13.9 Tunnels
    13.10 Bridges
    13.11 Object surface
14 Signals
    14.1 Lane validity for signals
    14.2 Signal dependency
    14.3 Links between signals and objects
    14.4 Signal positioning
    14.5 Reuse of signal information
    14.6 Controllers
15 Railroads
    15.1 Railroad tracks
    15.2 Switches
    15.3 Stations
Annexes
    Annex A (normative): Enumerations
    Annex B (normative): Data types
Bibliography
List of figures
List of tables

Source

ASAM specific rule.

The following sections contain explanations on how to insert content to the sections of the standard’s structure.

2.1.1 Foreword

  • The Foreword shall be inserted in all parts (documents) of the standard.

  • The Foreword shall be identical in all parts (documents) of the standard.

The section Foreword contains the following paragraphs:

  1. About ASAM (use the following fixed content)

    ASAM e.V. (Association for Standardization of Automation and Measuring Systems) is a non-profit organization that promotes standardization of tool chains in automotive development and testing.
    Our members are international car manufacturers, suppliers, tool vendors, engineering service providers, and research institutes.
    ASAM standards are developed by experts from our member companies and are based on real use cases.
    ASAM is the legal owner of these standards and is responsible for their distribution and marketing.
    
    ASAM standards span a wide range of use cases in automotive development, test, and validation.
    They define file formats, data models, protocols, and interfaces.
    The standards enable easy exchange of data and tools within and across tool chains.
    They are applied worldwide.
  2. About the standard (develop specification-specific content)

  3. Parts of the standard (develop specification-specific content)
    List of the documents containing their document names and corresponding descriptions

Example of a foreword

Code

ASAM e.V. (Association for Standardization of Automation and Measuring Systems) is a non-profit organization that promotes standardization of tool chains in automotive development and testing.
Our members are international car manufacturers, suppliers, tool vendors, engineering service providers, and research institutes.
ASAM standards are developed by experts from our member companies and are based on real use cases.
ASAM is the legal owner of these standards and is responsible for their distribution and marketing.

ASAM standards span a wide range of use cases in automotive development, test, and validation.
They define file formats, data models, protocols, and interfaces.
The standards enable easy exchange of data and tools within and across tool chains.
They are applied worldwide.

ASAM OpenDRIVE specifies the modeling approach of how to describe static road networks for driving simulation applications using the Extensible Markup Language (XML).

Parts of the standard:

* Specification +
The Specification contains the modeling approach of how to describe static road networks for driving simulation applications.

Result

ASAM e.V. (Association for Standardization of Automation and Measuring Systems) is a non-profit organization that promotes standardization of tool chains in automotive development and testing. Our members are international car manufacturers, suppliers, tool vendors, engineering service providers, and research institutes. ASAM standards are developed by experts from our member companies and are based on real use cases. ASAM is the legal owner of these standards and is responsible for their distribution and marketing.

ASAM standards span a wide range of use cases in automotive development, test, and validation. They define file formats, data models, protocols, and interfaces. The standards enable easy exchange of data and tools within and across tool chains. They are applied worldwide.

ASAM OpenDRIVE specifies the modeling approach of how to describe static road networks for driving simulation applications using the Extensible Markup Language (XML).

Parts of the standard:

  • Specification
    The Specification contains the modeling approach of how to describe static road networks for driving simulation applications.

Example how to mention the related parts of a standard

Code

Parts of the standard:

* Core specification +
The core specification includes a conceptual description of the Testbench and Framework API.
* Test Suite User guideline +
This guideline provides a set of test cases for the XIL Testbench API to help vendors and users to verify standard conformance of their C# implementations.

Result

Parts of the standard:

  • Core specification
    The core specification includes a conceptual description of the Testbench and Framework API.

  • Test Suite User guideline
    This guideline provides a set of test cases for the XIL Testbench API to help vendors and users to verify standard conformance of their C# implementations.

2.1.2 Introduction

The Introduction section contains the following sub-sections:

  1. Overview

  2. Conventions and notations

  3. Deliverables

2.1.2.1 Overview

The Overview section describes the content of the document and gives information on why the document is needed.

Exceptions

There are no exceptions.

Example

Code

ASAM OpenDRIVE was developed in response to demand for the specification of an exchange format to define static road networks that can be used in driving simulation applications.

The ASAM OpenDRIVE Specification specifies the file format for static road network descriptions.
The Extensible Markup Language (XML) is used to represent these descriptions.
The ASAM OpenDRIVE Specification specifies how to model static road networks.
In more detail, it specifies the structure, the sequence, the elements, and values to represent static road networks.

Static road networks consist of, for example, roads, lanes, signals, junctions, and objects along the road, for example, traffic islands.
The static road networks described in an ASAM OpenDRIVE file can be either artificial or derived from real world data.
ASAM OpenDRIVE does not define dynamic content, for example, traffic participants and moving objects.

ASAM OpenDRIVE descriptions may contain:

* road definitions
** road geometry in plan view
** lateral and elevation profiles of roads
** lanes
** road marks
** signals and their validity for specific roads and lanes
** objects along roads
* junctions
** junction types
** connections
** junction areas
* junction groups
* references to controllers for traffic lights
* tram and railway tracks

Result

ASAM OpenDRIVE was developed in response to demand for the specification of an exchange format to define static road networks that can be used in driving simulation applications.

The ASAM OpenDRIVE Specification specifies the file format for static road network descriptions. The Extensible Markup Language (XML) is used to represent these descriptions. The ASAM OpenDRIVE Specification specifies how to model static road networks. In more detail, it specifies the structure, the sequence, the elements, and values to represent static road networks.

Static road networks consist of, for example, roads, lanes, signals, junctions, and objects along the road, for example, traffic islands. The static road networks described in an ASAM OpenDRIVE file can be either artificial or derived from real world data. ASAM OpenDRIVE does not define dynamic content, for example, traffic participants and moving objects.

ASAM OpenDRIVE descriptions may contain:

  • road definitions

    • road geometry in plan view

    • lateral and elevation profiles of roads

    • lanes

    • road marks

    • signals and their validity for specific roads and lanes

    • objects along roads

  • junctions

    • junction types

    • connections

    • junction areas

  • junction groups

  • references to controllers for traffic lights

  • tram and railway tracks

2.1.2.2 Conventions and notations

  • The Conventions and notations section contains at least the following sections:

    • Modal verbs (see ASM-21)

    • Normative and informative content (see ASM-91)

  • The Conventions and notations section may contain, for example, information on units, data types, and color conventions for images.

2.1.2.3 Deliverables

The Deliverables section contains information on all items of the standard, for example, documents, schema files, and UML model binary files.

2.1.3 Scope

The Scope section describes what the document does.

For example, this document

  • specifies …​

  • establishes …​

  • gives guidelines for …​

  • defines terms …​

The Scope is written as a series of statements of fact. Do not put any requirements, recommendations or permissions in the Scope.

Exceptions

There are no exceptions.

Example

Code

The ASAM OpenDRIVE Specification explains how the ASAM OpenDRIVE elements are used and explains relationships between elements in the ASAM OpenDRIVE UML model and XSD schemas, for example, roads, lanes, junctions, objects, signals, and railroads.

Result

The ASAM OpenDRIVE Specification explains how the ASAM OpenDRIVE elements are used and explains relationships between elements in the ASAM OpenDRIVE UML model and XSD schemas, for example, roads, lanes, junctions, objects, signals, and railroads.

2.1.4 Normative references

The Normative references section contains the following paragraphs:

  1. The Normative references section shall be introduced by the following content:

    The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document.
    For dated references, only the edition cited applies.
    For undated references, the latest edition of the referenced document (including any amendments) applies.
    
    Standards referenced in this section are normative in such a way that parts or the whole standard shall be applied when implementing the referenced functionality.
    Standards referenced in this section shall be cited normatively in the text.
  2. List of normative references

Example

Code

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document.
For dated references, only the edition cited applies.
For undated references, the latest edition of the referenced document (including any amendments) applies.

Standards referenced in this section are normative in such a way that parts or the whole standard shall be applied when implementing the referenced functionality.
Standards referenced in this section shall be cited normatively in the text.

* {GLO_VAR_STA_ASAM_OpenCRG} cite:[ocr]
* ISO 3166-1 cite:[iso3166-1]
* ISO 3166-2 cite:[iso3166-2]
* ISO 8855 cite:[iso8855]
* ISO 8601 cite:[iso8601]
* ISO 19111 cite:[iso19111]
* OMG® UML 2.5.1 cite:[omguml]
* W3C XML cite:[w3cxml]
* W3C XML Schema cite:[w3cxmlschema]

Result

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

Standards referenced in this section are normative in such a way that parts or the whole standard shall be applied when implementing the referenced functionality. Standards referenced in this section shall be cited normatively in the text.

  • ASAM OpenCRG [2]

  • ISO 3166-1 [3]

  • ISO 3166-2 [4]

  • ISO 8855 [5]

  • ISO 8601 [6]

  • ISO 19111 [7]

  • OMG® UML 2.5.1 [8]

  • W3C XML [9]

  • W3C XML Schema [10]

2.1.5 Terms and definitions

The Terms and definitions section shall contain a list of terms with their definitions used in the document. Only terms which are used in the document shall be added. Terms and definitions shall be listed in alphabetical order. Common terms, which a qualified user of the document will already know, should not be defined.

The following structure shall be applied:

3 Terms and definitions

Term
Definition

Term
Definition

The terms shall be developed based on the following rules:

  • The term shall be added in singular form, for example, Static road network.

The definitions shall be developed based on the following rules:

  • The definition shall consist of full sentences that end with a full stop.

  • The definition shall consist of at least one sentence and may consist of additional sentences that support the user to understand the concept.

  • The definition shall be as short as possible.

  • The term shall be mentioned in the description. No synonyms of the term shall be used in the description.

  • The term shall be mentioned in singular or plural form in the description:

    • If an object or concept does occur more than once in the context it is used, use the plural form in the description, for example Controllers are …​. The definition shall not start with an article, for example, The controllers are …​.

    • If an object or concept does not occur more than once in the context it is used, use the singular form. The definition shall start with an article, for example, A or An, for example, An inertial system is …​.

  • The description shall answer what the object or concept is. The main characteristics to define the term shall be contained in the definition (mandatory). The definition may be supplemented by information what the object or concept can be used for (optional). Examples may provide information that illustrate the concept (optional). Examples should be written as a statement of fact.

  • The description shall not contain any requirements.

Specifications exist that support technical writers in defining terms and definitions:

  • DIN 2330 - Terminology work - Principles and methods, July 2022

  • ISO 704:2009 – Terminology work – Principles and methods or

  • ISO 860:2007 – Terminology work – Harmonization of concepts and terms

Additional resources regarding terminology can be found here:

Exceptions

There are no exceptions.

Example

Code

Slip road::
A slip road is any road at an intersection that allows to change roads without entering the intersection.

Static road network::
A static road network is a collection of connected roads enriched by static objects that do not change during the runtime of a simulation.

Result

Slip road

Any road at an intersection that allows to change roads without entering the intersection.

Static road network

Collection of connected roads enriched by static objects that do not change during runtime of a simulation.

Source

ASAM specific rule.

ISO/IEC Directives, Part 2 Principles and rules for the structure and drafting of ISO and IEC document; 2021.

2.1.6 Abbreviations

The Abbreviations section shall provide a list of all acronyms with their definitions used in the document. Only acronyms that are used in the document shall be added.

The following structure shall be applied:

4 Abbreviations

Abbreviation
Definition

Abbreviation
Definition

Exceptions

There are no exceptions.

Example

Code

ASAM::
Association for Standardization of Automation and Measuring Systems

ECU::
Electronic Control Unit

Result

ASAM

Association for Standardization of Automation and Measuring Systems

ECU

Electronic Control Unit

2.1.7 Backward compatibility

When no earlier version of the standard exists, add the following content to this section:

This is the first release of this standard published by ASAM.
Therefore, no information about the backward compatibility of this standard has been added to this section.

2.1.8 Specification-specific sections

Specification-specific sections form the main part of any document. These sections define the content of the specification. Requirements shall be written so they can be verified by anyone. The document shall avoid referring to trademarks or companies.

2.1.9 Annexes

Annexes are used to provide additional information to the main body of the document and are developed for several reasons, for example:

  • when the information or table is very long and including it in the main body of the document would distract the user

  • to set apart special types of information, for example, tables, lists, and data

  • to present information regarding a particular use case of the document

Annexes are designated by:

  1. The word Annex

  2. A space character

  3. An identifier for the annex using a capital letter, for example, A

  4. A space character

  5. The word normative or informative in brackets, for example (normative)

  6. A colon

  7. A space character

  8. An annex specific heading

Example

Annexes
    Annex A (normative): Enumerations
    Annex B (normative): Data types

2.1.10 Bibliography

The Bibliography section contains references on standards, literature like books, articles, and so on. All references added in the Normative references section shall also be added to the Bibliography section.

An entry of the Bibliography has the following structure:

<author 1 last name>, <author 1 first name>; <author 2 last name>, <author 2 first name>; <…more authors…>: <title>; <publisher>; <year>; ISBN: <ISBN-13 number>

Example

Bibliography
    [1] ASAM e.V.: ASAM General Expression; 2017
    [2] Jones, Russ; Nye, Adrian: HTML und das World Wide Web; O’Reilly/International Thomson Verlag; 1995; ISBN: 9783930673346

2.2 Use generic ASAM specification directory structure (ASM-83)

The directory structure of a repository of an ASAM specification always follows the same pattern.

The content folder in the repository contains the core files for the specification.

Each main section has a separate folder which contains the AsciiDoc file with the content of the main section and optional AsciiDoc files with the content of the subsections.

Exceptions

There are no exceptions.

Example

content/
├── _images/
│   ├── [first folder for images, named like the folder in the repository containing the documentation]/
│   ├── [second folder for images, named like the folder in the repository containing the documentation]/
│   └── ...
├── 00_preface/
│   ├── 00_foreword.adoc
│   └── 00_introduction.adoc
├── 01_scope/
│   └── 01_scope.adoc
├── 02_normative_references/
│   └── 02_normative_references.adoc
├── 03_terms_and_definitions/
│   └── 03_terms_and_definitions.adoc
├── 04_abbreviations/
│   └── 04_abbreviations.adoc
├── 05_backward_compatibility/
│   └── 05_backward_compatibility.adoc
├── 06_[first specification-specific main section]/
│   ├── 06_00_[first specification-specific main section].adoc
│   ├── 06_01_[first specification-specific sub section].adoc
│   ├── 06_01_[first specification-specific sub section].adoc
│   └── ...
├── 07_[second specification-specific main section]/
│   ├── 07_00_[second specification-specific main section].adoc
│   └── ...
├── ...
├── XX_annexes/
│   ├── [first specification-specific annex]/
│   │   ├── [first specification-specific annex].adoc
│   │   └── ...
│   └── ...
├── loft/
│   ├── list_of_figures.adoc
│   └── list_of_tables.adoc
├── _config.adoc
├── bibliography.bib
└── index.adoc

Source

ASAM specific rule.

2.3 Name the mapping file index.adoc (ASM-40)

  • The mapping file index.adoc shall be in the content directory of the root directory.

Exceptions

There are no exceptions.

Example

content/
├── _images/
│   └── ...
├── ...
├── loft/
│   └── ...
└── index.adoc

Source

ASAM specific rule.

2.4 Define the complete section structure in the mapping file (ASM-39)

  • Include all sections of all levels of the section structure in the mapping file.

  • Subsections shall not have separate mapping files.

Exceptions

There are no exceptions.

Example

The following example lists the include entries for several sections and subsections in a mapping file.

[preface]
include::00_preface/00_foreword.adoc[leveloffset=+1]
[preface]
include::00_preface/00_introduction.adoc[leveloffset=+1]

:sectnums:
include::01_scope/01_scope.adoc[leveloffset=+1]

include::02_normative_references/02_normative_references.adoc[leveloffset=+1]

include::03_terms_and_definitions/03_terms_and_definitions.adoc[leveloffset=+1]

include::04_abbreviations/04_abbreviations.adoc[leveloffset=+1]

include::05_backward_compatibility/05_backward_compatibility.adoc[leveloffset=+1]

include::06_general_architecture/06_00_general_architecture.adoc[leveloffset=+1]

include::07_additional_data/07_00_additional_data.adoc[leveloffset=+1]

include::08_coordinate_systems/08_00_coordinate_systems.adoc[leveloffset=+1]
include::08_coordinate_systems/08_01_coordinate_systems_overview.adoc[leveloffset=+2]
include::08_coordinate_systems/08_02_inertial_coordinate_system.adoc[leveloffset=+2]
include::08_coordinate_systems/08_04_local_coordinate_system.adoc[leveloffset=+2]
include::08_coordinate_systems/08_03_reference_line_coordinate_system.adoc[leveloffset=+2]
include::08_coordinate_systems/08_05_summary_coordinate_systems.adoc[leveloffset=+2]
include::08_coordinate_systems/08_06_geo_referencing.adoc[leveloffset=+2]

...

:sectnums!:
== Annexes
[appendix]
include::16_annexes/enumerations/map_uml_enumerations.adoc[leveloffset=+2]
[appendix]
include::16_annexes/map_uml_data_types.adoc[leveloffset=+2]


[bibliography]
== Bibliography
bibliography::[]

:sectnums!:
include::loft/list_of_figures.adoc[leveloffset=+1]

:sectnums!:
include::loft/list_of_tables.adoc[leveloffset=+1]

Source

ASAM specific rule.

2.5 Each paragraph shall be uniquely identified (ASM-132)

There shall be no text between section levels. In such cases it is necessary to encapsulate the text in a subsection.

Exceptions

There are no exceptions.

Example

Table 10. Example of uniquely identified paragraphs
No Yes

6 Quality of standards

The ASAM Editorial Guide shall be considered when a specification is written.

6.1 Naming of parts

[...]

6 Quality of standards

6.1 Usage of the ASAM Editorial Guide

The ASAM Editorial Guide shall be considered when a specification is written.

6.2 Naming of parts

[...]

Source

ISO/IEC Directives, Part 2 Principles and rules for the structure and drafting of ISO and IEC document; 2021. See section Hanging paragraphs.

2.6 Check to include all needed sections (ASM-27)

  • Check to include all needed sections in the section structure and the mapping file.

  • Remove sections from the repository that are without use in the section structure and mapping file.

Exceptions

There are no exceptions.

Example

There is no example.

Source

ASAM specific rule.

2.7 Include information on normative and informative content (ASM-91)

Place the section on normative and informative content in the Conventions and notations section under the Introduction section in the generic ASAM specification section structure, refer to Section 2.1, “Use a generic ASAM specification section structure (ASM-22)”.

Exceptions

There are no exceptions.

Example

Code

=== Normative and informative content

Content in this specification can be normative or informative.
The sections listed in <<tab-normative-informative-content>> are normative or informative per definition.
Further informative content is shown in table <<tab-informative-text-components>>.

[#tab-normative-informative-content]
.Normative and informative sections
[%header, cols=2*]
|===
|Section                                      |Indication
|Foreword                                     |Informative
|Introduction                                 |Informative
|Scope                                        |Normative
|Normative references                         |Informative
|Terms and definitions                        |Normative
|Abbreviations                                |Normative
|Backward compatibility                       |Normative
|First to last specification-specific section |Normative
|Annexes                                      |Annexes can be normative or informative. The annex heading contains the indication "(normative)" or "(informative)".
|Bibliography                                 |Informative
|===

All other sections in this specification are normative.

[#tab-informative-text-components]
.Informative text components
[%header, cols="25, 25, 50"]
|===
|Text components   |Indication  |Hints
|Notes             |Informative |The document shall be usable without notes.
|Footnotes         |Informative |The document shall be usable without footnotes.
|Examples          |Informative |The document shall be usable without examples.
|Sequence diagrams |Informative |The document shall be usable without sequence diagrams.
|===

Notes, footnotes, and examples shall not contain requirements or any information considered indispensable for the use of the document, for example, instructions or permission.

Result

Normative and informative content

Content in this specification can be normative or informative. The sections listed in Table 11 are normative or informative per definition. Further informative content is shown in table Table 12.

Table 11. Normative and informative sections
Section Indication

Foreword

Informative

Introduction

Informative

Scope

Normative

Normative references

Informative

Terms and definitions

Normative

Abbreviations

Normative

Backward compatibility

Normative

First specification-specific section

Normative

Annexes

Annexes can be normative or informative. The annex heading contains the indication "(normative)" or "(informative)".

Bibliography

Informative

All other sections in this specification are normative.

Table 12. Informative text components
Text components Indication Hints

Notes

Informative

The document shall be usable without notes.

Footnotes

Informative

The document shall be usable without footnotes.

Examples

Informative

The document shall be usable without examples.

Sequence diagrams

Informative

The document shall be usable without sequence diagrams.

Notes, footnotes, and examples shall not contain requirements or any information considered indispensable for the use of the document, for example, instructions or permission.

Source

ASAM specific rule.

2.8 Conventions for mandatory, optional, and conditional content (ASM-133)

For exchange of products it is necessary that mandatory, optional, and conditional functionalities in a standard are classified. The condition shall be stated.

A standard compliant implementation shall support all mandatory functionalities.

In the case of an optional functionality, it might be required to define if the functionality must be implemented, for example, when looking at the implementation for a server or a client.

Exceptions

There are no exceptions.

Example

In case of an API it is necessary to define which interfaces, methods, and attributes shall be implemented. If necessary, the definition shall state if the implementation is relevant for servers or clients.

Table 13. Example for convention of mandatory, optional, and conditional content
Attribute Type Convention Description

id

string

Mandatory

Unique identifier of a value.

data

AnyValue

Mandatory

The value of the data.
The type of the value is defined by the schema.

errors

DataError[]

Conditional

Condition: Only set, if the value data represents an error and this attribute describes the error more precisely.

shema

OpenAPI Schema

Conditional

Schema for the data.
Condition: Only provided if the query parameter include-schema is true.

translation_id

string

Optional

Identifier for translating the value identifier (id).

Source

ASAM specific rule.

2.9 Include verbal forms for expressions of provisions (ASM-21)

Use and update the following section with the table of verbal forms for expressions of provisions in a specification document.

Place the modal verbs section in the Conventions and notations section under the Introduction section in the generic ASAM specification section structure, refer to Section 2.1, “Use a generic ASAM specification section structure (ASM-22)”.

Exceptions

There are no exceptions.

Example

Code

[#sec-modal-verbs]
=== Modal verbs

To ensure compliance with the {THIS_STANDARD} specification, users need to be able to distinguish between requirements, recommendations, permissions, possibilities and capabilities, and external constraints.

[#tab-modal-verbs]
.Verbal forms for expressions of provisions
[%header, cols="20, 15, 65"]
|===
|Provision                  |Verbal form        |Definition
|Requirement                |shall, shall not   |A requirement conveys objectively verifiable criteria to be fulfilled and from which no deviation is permitted if conformance with the document is to be claimed.
|Recommendation             |should, should not |A recommendation conveys a suggested possible choice or course of action deemed to be particularly suitable without necessarily mentioning or excluding others.
|Permission                 |may                |A permission conveys consent or liberty (or opportunity) to do something.
|Possibility and capability |can, cannot        |A possibility conveys expected or conceivable material, physical or causal outcome. +
                                                 A capability conveys the ability, fitness, or quality necessary to do or achieve a specified thing.
|External constraint        |must               |An external constraint or obligation on the user of the document, for example laws of nature or particular conditions existing in some countries or regions, that is not stated as a provision of the document.
                                                 External constraints are not requirements of the document.
                                                 They are given for the information of the user.
|===

Result

Modal verbs

To ensure compliance with the ASAM OpenDRIVE Specification, users need to be able to distinguish between requirements, recommendations, permissions, possibilities and capabilities, and external constraints.

The following rules for using modal verbs apply:

Table 14. Verbal forms for expressions of provisions
Provision Verbal form Definition

Requirement

shall, shall not

A requirement conveys objectively verifiable criteria to be fulfilled and from which no deviation is permitted if conformance with the document is to be claimed.

Recommendation

should, should not

A recommendation conveys a suggested possible choice or course of action deemed to be particularly suitable without necessarily mentioning or excluding others.

Permission

may

A permission conveys consent or liberty (or opportunity) to do something.

Possibility and capability

can, cannot

A possibility conveys expected or conceivable material, physical or causal outcome.
A capability conveys the ability, fitness, or quality necessary to do or achieve a specified thing.

External constraint

must

An external constraint or obligation on the user of the document, for example laws of nature or particular conditions existing in some countries or regions, that is not stated as a provision of the document. External constraints are not requirements of the document. They are given for the information of the user.

Source

ASAM specific rule.

2.10 Use the standard disclaimer (ASM-31)

2.10.1 Restricted domains

Include the following standard disclaimer for the ASAM standards of restricted domains:

Disclaimer

This document is the copyrighted property of ASAM e.V.

Any use is limited to the scope described in the license terms.

The license terms can be viewed at www.asam.net/license

Exceptions

There are no exceptions.

Example

Code

[IMPORTANT]

.Disclaimer

====

This document is the copyrighted property of ASAM e.V.

Any use is limited to the scope described in the license terms.

The license terms can be viewed at https://www.asam.net/license[www.asam.net/license]

====

2.10.2 Unrestricted domains

Include the following standard disclaimer for the ASAM standards of unrestricted domains:

Disclaimer

This document is the copyrighted property of ASAM e.V.

In alteration to the regular license terms, ASAM allows unrestricted distribution of this standard. §2 (1) of ASAM’s regular license terms is therefore substituted by the following clause: "The licensor grants everyone a basic, non-exclusive and unlimited license to use the standard {THIS_STANDARD}".

Exceptions

There are no exceptions.

Example

Code

[IMPORTANT]

.Disclaimer

====

This document is the copyrighted property of ASAM e.V.

In alteration to the regular https://www.asam.net/license[license terms], ASAM allows unrestricted distribution of this standard.
§2 (1) of ASAM's regular https://www.asam.net/license[license terms] is therefore substituted by the following clause: "The licensor grants everyone a basic, non-exclusive and unlimited license to use the standard {THIS_STANDARD}".

====

Source

ASAM specific rule.

2.11 Add information about registered standards (ASM-32)

  • Information shall be added if a standard is registered (see external link).

Exceptions

There are no exceptions.

Example

Code

<Official name of the standard> is a registered trade mark of ASAM e.V.

Result

ASAM OpenDRIVE is a registered trade mark of ASAM e.V.

Source

ASAM specific rule.

2.12 List of figures is created automatically (ASM-18)

  • The AsciiDoc pipeline renders a complete list of figures automatically.

  • Do not create a list of figures manually.

Exceptions

There are no exceptions.

Example

There is no example.

Source

ASAM specific rule.

2.13 List of tables is created automatically (ASM-19)

  • The AsciiDoc pipeline renders a complete list of tables automatically.

  • Do not create a list of tables manually.

Exceptions

There are no exceptions.

Example

There is no example.

Source

ASAM specific rule.