1 Basics

1.1 Names of ASAM standards (ASM-125)

This rule defines how ASAM standard documents are named.

1.1.1 Standard name

A standard’s name consists of the following elements:

  1. An official name (see Section 1.1.2, “Official name”)

  2. An optional market name, in the following sequence:

    1. A space character

    2. An opening bracket (

    3. The market name (Section 1.1.3, “Market name”)

    4. A closing bracket )

Exceptions

There are no exceptions.

Example

ASAM MCD-2 MC (ASAP2 / A2L)
ASAM OpenDRIVE

1.1.2 Official name

  • The name of an ASAM standard always starts with the prefix ASAM.

  • The prefix ASAM shall be extended by the project group name in the defined upper and lower case writing, without extensions like versions or project types (FVD, Major, …​).

    The name of a project group is typically the name of a standard inside a domain.

Exceptions

There are no exceptions.

Example

ASAM MCD-2 MC
ASAM OpenDRIVE

1.1.3 Market name

The market name is an abbreviation.

Exceptions

There are no exceptions.

Example

ASAP2 / A2L

1.1.4 Title

The title explains the abbreviations of the official name or qualifies the scope.

Exceptions

There are no exceptions.

Example

Data Model for ECU Measurement and Calibration
Static road network description

1.1.5 Document name

A standard may consist of multiple documents that shall have the following document names:

  • 1 Main document
    Contains normative and informative content as described in rule ASM-22. A Specification describes the code of operation, the structure, and the usage of the standard.

    • [<xxx>] Specification [<xxx>]

  • 0..n Documents for implementers or programmers
    A Reference contains normative content.

    • [<xxx>] Reference [<xxx>]

  • 0..n Documents in the sense of a Manual
    A Guideline contains informative content.

    • [<xxx>] Guideline [<xxx>]

  • 0..n Supplementary documents
    Supplementary documents shall define, which content is normative or informative.

    • <Standard specific naming>

[<xxx>] Stands for specific extensions of the standard.

Exceptions

There are no exceptions.

Example

Table 1. Naming of standards parts
No Yes

Big Data Connector

Big Data Connector specification

C# Mapping Rules

C# Mapping reference

Junction Guide

Junction guideline

Source

ASAM specific rule.

1.2 Use the official names of ASAM standards (ASM-119)

  • Always use the official names of ASAM standards.

  • Do not use abbreviations.

Exceptions

See rule ASM-120 if you refer to the standard you are working on.

Example

Table 2. Use the official names of ASAM standards
No Yes

OpenDRIVE

ASAM OpenDRIVE

OS

ASAM OpenSCENARIO

Source

ASAM specific rule.

1.3 Definition of version number (ASM-14)

  • A version number shall contain Major, Minor, and Maintenance elements, separated by a dot Major.Minor.Maintenance, for example, 4.1.21.

  • Version elements are represented by unsigned integer numbers from 0 to 99.

  • Base standards and associated standards shall have an unambiguous version number.

Rules how to version associated standards:

  • Associated standards have a separate version number that is independent to the version number of the base standard.

  • In the associated standard it shall be defined, starting from which version of the base standard the associated standard can be applied.

  • The version of the base standard in relation to the associated standard is defined by the functionality of the base standard that is required for the associated standard.

    Major

    Major version developments of ASAM standards introduce significant changes to a standard.

    A newly developed ASAM standard gets the version number 1.0.0.

    A major version element is incremented when:

  • New major features are added

  • Significant changes of existing features take place. A new major version of an ASAM standard does not have to be backward compatible to its predecessor versions.

    Minor

    Minor version developments of ASAM standards introduce changes to existing features on a smaller scale or introduce new features that are rather small relative to the rest of the standard.

    A new minor version of an ASAM standard shall be backward-compatible to its immediate predecessor version.

    A minor version element is incremented when:

  • New features are added, which are considered as small relative to existing features

  • Insignificant changes are integrated

  • Compatible extensions of existing features are added

    Maintenance

    Maintenance version developments of ASAM standards resolve technical issues with the currently released version of the standard.

    A standard for which the maintenance version element is incremented cannot include new features.

    A maintenance version element is incremented when:

  • Errors are corrected

  • Ambiguities are removed

  • Clarifications are added to existing descriptions

  • Editorial improvements are made

  • Examples are modified, including the addition of examples

Exceptions

There are no exceptions.

Example

4.1.21

Source

ASAM specific rule.

1.4 Use proper names (ASM-76)

  • Always use existing proper names.

  • Apply the original spelling and the correct upper and lower case of proper names.

Exceptions

There are no exceptions.

Example

Table 3. Use proper names
No Yes

UTF8

UTF-8

utf-8

UTF-8

ascii

ASCII

Source

ASAM specific rule.

1.5 Do not include version information (ASM-1)

Do not include version information in the content or in the names of files or folders or UML models.

Exceptions

There are no exceptions.

Example

Table 4. Use of constant file names
No Yes

example_file_name_v3.adoc

example_file_name.adoc

Referenced Standard V 1.2.3

Referenced Standard

Source

ASAM specific rule.

1.6 Use AsciiDoc syntax for text documents (ASM-54)

Exceptions

There are no exceptions.

Source

ASAM specific rule.

1.7. Use adoc as file extension for text documents (ASM-23)

Exceptions

There are no exceptions.

Example

Table 5. Use of .adoc as file extension
No Yes

ExampleFileName.ado

example_file_name.adoc

Source

ASAM specific rule.

1.8 Delete trailing space characters (ASM-20)

  • Eliminate any space characters or tabs at each end of line.

  • Check the settings of the text editor to automatically remove trailing space characters:

Exceptions

There are no exceptions.

Example

Table 6. No trailing space characters before the end of line ([EOL]).
No Yes

This is wrong with space characters.     [EOL]

This is correct.[EOL]

Source

ASAM specific rule.

1.9 Keep one blank line at the end of file (ASM-24)

  • Eliminate any space characters or tabs at each end of line.

  • Check the settings of the text editor to automatically insert a blank line at the end of the file.

Exceptions

There are no exceptions.

Example

Table 7. One blank line before the end of file ([EOF]).
No Yes

This is the last text line.
[EOF]

This is the last text line.
 
[EOF]

Source

ASAM specific rule.

1.10. Use the variable {THIS_STANDARD} to refer to the standard you are working on (ASM-120)

Exceptions

See rule ASM-119 if you are writing about other standards.

Example

Code

In {THIS_STANDARD}, all roads contain lanes.

Result

In ASAM OpenDRIVE, all roads contain lanes.

Source

1.11 Spelling of terms (ASM-70)

  • Stick to one spelling for a word that allows several spellings.

  • Stick to one formatting of terms for a special purpose, for example only the first appearance.

Exceptions

There are no exceptions.

Example

Table 8. Use of consistency in spelling and formatting.
No Yes

e-mail, email

email

Bridges are objects in ASAM OpenDRIVE. Bridges are valid for a road’s complete cross section.

Bridges are objects in ASAM OpenDRIVE. Bridges are valid for a road’s complete cross section.

Source

ASAM specific rule.

1.12 Anchor syntax (ASM-78)

Elements for anchors shall be added in the following sequence:

  1. An opening squared bracket [

  2. A hash tag #

  3. A prefix that defines the type of content, for example, code-, fig-, or sec-.

  4. A unique identifier <uid> that shall be of one of the following types:

    • A generated Version 4 UUID, for example, 59425058-cb3e-41dd-ae43-0879be4f5d92

    • A semantic unique identifier, for example, example-http-request
      The semantic unique identifier should reflect a file’s name (if existing) and the caption’s content.

  5. A closing squared bracket ]

The following prefixes for anchors shall be used:

Table 9. Prefixes for anchors
Prefix Type Usage Condition Example

code-

source code blocks

conditional

Only use a code anchor if the source code is referenced.

[#code-example-http-request]

fig-

figures (images, diagrams, and so on)

required

-

[#fig-inertial-coordinate-system]

sec-

sections

conditional

Only use a section anchor if the section is referenced.

[#sec-682fa239-bf8f-4531-a825-e9486372479b]

tab-

tables

required

-

[#tab-http-status-codes]

top-

topics

required

-

[#top-5bc5b4dc-0129-40d4-a012-9e10c18f37aa]

Exceptions

There are no exceptions.

Example

File name: fig_uml_class_junction_virtual.svg
Caption:   .Class junction virtual
Anchor:    [#fig-class-junciton-virtual]

Source

ASAM specific rule.

1.13 Apply appropriate styles for cross references (ASM-15)

The syntax for rendering links is defined in the ASAM Style Resources repository in the preamble.adoc file. The syntax for links will be applied automatically during the rendering of the document.

1.13.1 Short cross references

Short cross reference style shall be applied for references on the following elements:

  • Code

  • Figures

  • Tables

A short cross reference consists of:

  1. The words Code, Figure, or Table

  2. A space character

  3. A number

  4. A space character

  5. The word shows

  6. An explanatory text

Exceptions

There are no exceptions.

Example

References on code

Code 1. Caption of the source code
<junction name="" id="1">
    <connection id="0" incomingRoad="2" connectingRoad="4" contactPoint="start">
        <laneLink from="-1" to="-1"/>
    </connection>
    <connection id="1" incomingRoad="3" connectingRoad="5" contactPoint="start">
        <laneLink from="-1" to="-1"/>
    </connection>
</junction>

Code

<<code-dd577de0-dfab-4044-bf67-1ecce6c35597>> shows ...

Result

Code 1 shows …​

References on figures

Alternative text
Figure 1. Caption of the figure

Code

<<fig-33508bf7-8893-44a1-91f5-a8f58751c1c8>> shows ...

Result

Figure 1 shows …​

References on Tables

Table 10. Caption of the table
Header column 1 Header column 2

1st cell column 1

1st cell column 2

Code

<<tab-ed7666b6-0ac0-4576-8386-37438c4b61e7>> shows ...

Result

Table 10 shows …​

1.13.2 Full cross references

Full cross reference style shall be applied for references on the following elements:

  • Sections

A full cross reference consists of:

  1. The word Section

  2. A space character

  3. The section number

  4. A comma

  5. A space character

  6. The title of the section in quotation marks

Exceptions

There are no exceptions.

Example

Code

See <<sec-f9491ea2-d18c-4b2c-8518-8cc15d3bc2f2>>.

Result

See Section 1.13.2, “Full cross references”.

Source

ASAM specific rule.

1.14 Check for broken internal references (ASM-37)

  • Check if the references to sections of the document, to figures, and to tables work.

  • Check the results of the production pipeline for reference errors.

Exceptions

There are no exceptions.

Example

There are no examples.

Source

ASAM specific rule.

1.15 Hyperlinks to external resources (ASM-7)

  • Always label hyperlinks to external resources in the same manner.

Exceptions

There are no exceptions.

Example

Code

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.

Result

This document is the copyrighted property of ASAM e.V. In alteration to the regular license terms, ASAM allows unrestricted distribution of this standard.

Source

ASAM specific rule.

1.16 Check for broken hyperlinks (ASM-38)

  • Check if hyperlinks to external resources of the document work, for example, links to websites.

  • Check the results of the production pipeline for reference errors.

Exceptions

There are no exceptions.

Example

There are no examples.

Source

ASAM specific rule.

1.17 File names of deliverables (ASM-41)

File names of deliverables consist of the following elements:

  1. The official name of the standard (see Section 1.1.2, “Official name”)

    Space characters in official names shall be replaced by underscores _, for example, ASAM_SOVD.

  2. An underscore _

  3. The document type

    • BS for basic standards

    • AS for associated standards

  4. An underscore _

  5. A V for version, followed by the version number of the document (see rule ASM-14)

    Dots in version numbers shall be replaced by hyphens -, for example, V1-0-0.

  6. The file extension .zip

Exceptions

There are no exceptions.

Example

ASAM_SOVD_BS_V1-0-0.zip

Source

ASAM specific rule.

1.18 Antora header syntax (ASM-137)

The Antora site shall have a header that contains the following information:

  1. The standard’s official name

  2. The registered symbol ® (mandatory if the standard is registered)

  3. A space character

  4. The standard’s version

  5. A comma

  6. A space character

  7. The standard’s descriptive title (mandatory if existing)

  8. A comma

  9. A space character

  10. The standard’s release date <yyyy-mm-dd>

Exceptions

There are no exceptions.

Example

ASAM OpenDRIVE® 1.8.0, Static Road Network Description, 2022-06-01

Source

ASAM specific rule.

1.19 Document title syntax (ASM-138)

Every document contained in the Antora site shall have a title that contains the following information:

  1. The standard’s official name (mandatory, see Section 1.1.2, “Official name”)

  2. The standard’s type if the standard is a Base Standard (BS) or an Associated Standard (AS) (if applicable)

    Supplementary documents do not have a standard type.

  3. The document’s name (mandatory)

  4. The document’s release date (mandatory)

Example

Code 2. Example titles of documents that are parts of the standard
ASAM OpenDRIVE BS 1.8.0 Specification, 2022-06-01 (first part)
ASAM OpenDRIVE BS 1.8.0 Signal reference, 2022-06-01 (second part)
ASAM OpenDRIVE BS 1.8.0 Junction guideline, 2022-06-01 (third part)

The release dates of all parts are equal because all parts of a standard shall be updated before a standard’s release.

Code 3. Example titles of documents that are separate documents
ASAM OpenDRIVE BS 1.9.0 Specification, 2024-07-01 (first part)
ASAM OpenDRIVE 1.9.0 Signal reference 1.0.0, 2022-06-01 (supplementary document)
ASAM OpenDRIVE 1.9.0 Junction guideline 1.1.0, 2024-07-01 (supplementary document)

The versions and release dates of supplementary documents may differ because supplementary documents may have not been updated before a standard’s release.

Source

ASAM specific rule.

1.20 Do not include footnotes (ASM-12)

Do not include footnotes in documents.

Exceptions

There are no exceptions.

Example

There is no example.

Source

ASAM specific rule.