Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Apply one-sentence-per-line in all adocs #299

Merged
merged 3 commits into from
Jul 26, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
Expand Up @@ -5,32 +5,32 @@ This Annex explains the table templates used for documentation of interfaces, op

_Card._ is the cardinality (or multiplicity) defining the lower and upper bound of the number of instances of the member element. "*" denotes an arbitrary infinite number of elements of the corresponding Type. "0..1" means optional. "0..*" or "0..3" etc. means that the list may be either not available (null object) or empty or has infinitely many / exactly three elements.


====
Note: attributes having a default value are always considered to be optional; there is always a value for the attribute because the default value is used for initialization in this case.
====


.Interface Description
[%autowidth, width="100%", cols="19%,81%",options="header",]
[%autowidth,width="100%",cols="19%,81%",options="header",]
|===
2+h|Interface: <Interface Name>
h|Operation Name h|Description
e|Oper1 a|
Human-understandable description of the operation of the interface. Only major input and output information shall be described, no individual request and result parameters.
Human-understandable description of the operation of the interface.
Only major input and output information shall be described, no individual request and result parameters.


====
Note: all words in the service operation name are written together in italics without a blank in between. The first letter of the first word is lower case, all other words are upper case.
Note: all words in the service operation name are written together in italics without a blank in between.
The first letter of the first word is lower case, all other words are upper case.
====


e|… a|
e|operN (optional) a|Human-understandable description of the operation n of the interface. Optional operations are to be marked by suffix (optional) after the operation name.
e|operN (optional) a|
Human-understandable description of the operation n of the interface.
Optional operations are to be marked by suffix (optional) after the operation name.
|===



[.table-with-appendix-table]
.Operation Description
:table-caption: Template
Expand All @@ -54,11 +54,13 @@ The operation provides its functionality through the following input and output

• Output Parameter N: human-understandable description of the purpose of output parameter N:

If *_payload_* is mentioned as output parameter, only the returned payload in case of a successful operation (status code: Success, SuccessCreated) is denoted in column _Type_. In case of failure see xref:specification/interfaces-payload.adoc#StatusCode[Generic Status Codes].
If *_payload_* is mentioned as output parameter, only the returned payload in case of a successful operation (status code: Success, SuccessCreated) is denoted in column _Type_.
In case of failure see xref:specification/interfaces-payload.adoc#StatusCode[Generic Status Codes].

If [.underline]#no# *_payload_* is mentioned as output parameter, the status code shall be SuccessNoContent in case of success, otherwise see Clause 0.

Convention: all words in the interface name are written together in italics without a blank in between. The first letter of the first word and all other words are written in upper case letters.
Convention: all words in the interface name are written together in italics without a blank in between.
The first letter of the first word and all other words are written in upper case letters.

h|semanticId 4+|`The unique identifier of this operation`

Expand All @@ -78,6 +80,6 @@ Type of the output
parameter 1

|The cardinality of type of the outputParameter1, e.g. zero-to-one (“0..1”) or at-least-one (“1..*”).
e|… | | | |
e|… | | | |
e|outputParameterN a|Human-understandable description of the output parameter N of the operation. |States whether the outputParameterN is mandatory (“yes”) or optional (“no”) |Type of the output eparameter N a|The cardinality of type of the outputParameterN, e.g. zero-to-one (“0..1”) or at-least-one (“1..*”).
|===
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,10 @@ Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, d


[appendix]
== Backus-Naur-Form
= Backus-Naur-Form

The Backus-Naur form (BNF) – a meta-syntax notation for context-free grammars – is used to define grammars. For more information see https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form[Wikipedia].
The Backus-Naur form (BNF) – a meta-syntax notation for context-free grammars – is used to define grammars.
For more information see https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form[Wikipedia].

A BNF specification is a set of derivation rules, written as

Expand Down Expand Up @@ -63,8 +64,6 @@ Hugo Me e-mail addresses: [email protected]
Hugo e-mail addresses: [email protected]
....



Invalid contact addresses:

[example]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,19 +11,25 @@ POST operations create new resources using the input content.

PUT operations replace existing resources using the input content.

POST and PUT use the regular serialization. The client creates the input content as needed, so that no further SerializationModifiers need to be used.

PATCH operations may use the regular serialization, the metadata serialization, or the ValueOnly- serialization. The SerializationModifier Core is not used. The resources in the input content must already exist on the server and are replaced one by one accordingly. If one of the resources in the input content does not exist, no changes will be made on the server. “Resource exists” means, that the type of a SubmodelElement is the same in the input content and on the server. For example, a property may only be replaced by a property; elements of a SubmodelElementCollection or SubmodelElementList can only be replaced if they already exist on the server. A SubmodelElementList with five elements cannot be patched with a SubmodelElementList with more than five elements. A SubmodelElementList with five elements can be patched with a SubmodelElementList with less than five elements since all required elements starting from index 0 already exist.

POST and PUT use the regular serialization.
The client creates the input content as needed, so that no further SerializationModifiers need to be used.

PATCH operations may use the regular serialization, the metadata serialization, or the ValueOnly- serialization.
The SerializationModifier Core is not used.
The resources in the input content must already exist on the server and are replaced one by one accordingly.
If one of the resources in the input content does not exist, no changes will be made on the server.
“Resource exists” means, that the type of a SubmodelElement is the same in the input content and on the server.
For example, a property may only be replaced by a property; elements of a SubmodelElementCollection or SubmodelElementList can only be replaced if they already exist on the server.
A SubmodelElementList with five elements cannot be patched with a SubmodelElementList with more than five elements.
A SubmodelElementList with five elements can be patched with a SubmodelElementList with less than five elements since all required elements starting from index 0 already exist.

====
Note: values remain unchanged with content=metadata.
====


=== Examples for GET Operations

[%autowidth, width="100%", cols="h,d,d",options="header",]
[%autowidth,width="100%",cols="h,d,d",options="header",]
|===
| |*Deep (default)* |*Core*
|*Normal +
Expand Down Expand Up @@ -343,7 +349,7 @@ If applied to the Property inside the SubmodelElementCollection:

=== Examples for PATCH Operations

[%autowidth, width="100%", cols="h,d"]
[%autowidth,width="100%",cols="h,d"]
|===
| |*Deep (default)*
|*Normal (default)* a|
Expand Down
Binary file not shown.
Loading