Revise spec.md

1 files changed, 67 insertions, 63 deletions

diff --git a/docs/spec.md b/docs/spec.md
index efaa5be..eb71c60 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -2,7 +2,7 @@
 
 ## Introduction
 
-MOA ZS is a middleware that allow a sender application (app) to send delivery requests to delivery services.
+MOA ZS is a middleware that allows a sender application (app) to send delivery requests to delivery services.
 MOA ZS uses Apache CXF as a web service framework and the Spring Framework as inversion of control container.
 
 TODO: write a proper introduction with actors, sequence diagram & interfaces
@@ -16,57 +16,60 @@ For version 2.0.0, MOA ZS was rewritten from scratch. The following list summari
 - Add compatibility with [zusemsg].
 - Add compatibility with [zusetnvz].
 - Replace the database as persistent storage with an in-memory cache.
-- Update the app2mzs wsdl contract and it's data types to fit the needs of [zusemsg] and [zusetnvz].
+- Update the app2mzs WSDL contract and its data types to fit the needs of [zusemsg] and [zusetnvz].
 - Integrate signature verification with MOA SP-SS.
 - Drop support for message encryption and signature creation.
 - Target Platform Java 12.
 
 ### Changes between app2mzs 1.5.3 and app2mzs 2.0.0
 
-This section describes, how the app2mzs wsdl contract was changed and explains, why these changes were applied.
-Due to the nature of the changes (feature additions and feature removals in [zusemsg] 2.0.0 and [zusetnvz] 2.0.0) and due to the fact that changes propagate into the app2mzs interface, some changes are not backwards compatible and require to be integrated into the app.
+This section describes how the app2mzs WSDL contract was changed and explains why these changes were applied.
+The changes in the app2mzs WSDL contract accommodate feature additions and feature removals in [zusemsg] 2.0.0 and [zusetnvz] 2.0.0.
+Not all changes are backward compatible and require adjustments in app2mzs-1.5.3-compatible clients.
 
 #### Changes in `mzs:DeliveryRequest`
 
-- The `Server` element was removed from the `DeliveryRequest` type because this element replaced the response from the request that was sent to the ZKOPF.
-  The ZKOPF request does not exist anymore, therefore the `Server` response is not relevant.
-  This change is *not backwards-compatible*.
+- The `Server` element was removed from the `DeliveryRequest` type.
+  In MOA ZS 1.5.4, this element replaced the ZKOPF response.
+  ZKOPF request and response do not exist anymore, which renders the `Server` response irrelevant.
+  This change is *not backward compatible*.
 - The `ProfileID` option in the `DeliveryRequest/Sender` element was replaced by `msg:SenderProfile` because sender profiles are now registered at the delivery service and referred to via `DeliveryRequest/Sender/SenderProfile`.
-  This change is *not backwards-compatible*.
+  This change is *not backward compatible*.
 - The `SignatureKeyID` element was removed from `DeliveryRequest` because this element refers to the signing key.
-  Since signature creation was dropped, the element is not relevant.
-  This change is *not backwards-compatible*.
+  Since signature creation was dropped from MOA ZS, the element is not relevant.
+  This change is *not backward compatible*.
 - The optional elements `msg:Logo` and `msg:AdditionalCriteria` were added to `DeliveryRequest/Sender` because they were also added as optional elements to [zusemsg].
-  This change is *backwards-compatible*.
+  This change is *backward compatible*.
 - The element `Person` in `DeliveryRequest/Sender` was replaced by the `p:CorporateBody` profile because that is the only sender that is allowed by [zusemsg].
-  This change is *not backwards-compatible*.
+  This change is *not backward compatible*.
 - `DeliveryRequest/Sender/Address` was removed because the element was dropped in [zusemsg].
-  This change is *not backwards-compatible*.
+  This change is *not backward compatible*.
 - An alternative choice to the `Person`-`Address` sequence in `DeliveryRequest/Receiver` was added.
   This choice allows to pass a `p:Identification` element instead of the `Person`-`Address` sequence.
-  The choice was added because it is a new, optional feature in [zusemsg].
-  This change is *backwards-compatible*.
+  The choice was added to enable the optional feature in [zusemsg].
+  This change is *backward compatible*.
 - The optional element `tnvz:AustrianAddressesOnly` was added to `DeliveryRequest/Receiver` because this element was also added as an optional element to [zusetnvz].
-  This change is *backwards-compatible*.
+  This change is *backward compatible*.
 - The optional element `msg:AdditionalCriteria` and `msg:PreAdviceNote` were added to `DeliveryRequest/Receiver` because these element were also added as optional elements to [zusemsg].
-  This change is *backwards-compatible*.
+  This change is *backward compatible*.
 - The element `MetaData` in `DeliveryRequest` was replaced with the `msg:MetaData` element from [zusemsg].
   The reason for replacing the `MetaData` element is that the `MetaData` from the app2mzs contract represents the same data that the delivery service expects.
-  Furthermore, the amount of changes between both elements prohibits a straight forward conversion between them.
-  This change is *not backwards-compatible*.
+  Furthermore, the amount of changes between MetaData from app2mzs 1.5.3 and [zusemsg] 2.0.0 prohibits a straight forward conversion between both elements.
+  This change is *not backward compatible*.
 - The optional `Config` element was added to the `DeliveryRequest` element.
-  This element allows to override individual configuration parameters for the ongoing request.
+  This element allows overriding individual configuration parameters for the ongoing request.
+  This change is *backward compatible*: You do not need to specify any parameters in the `Config`-element since you can also configure delivery requests in `application.yaml`.
   See [Chapter Configuration](#configuration) for more details.
-  This change is *backwards-compatible*.
+
 - The element `XMLDocument` was replaced as this element was dropped from [zusemsg] in favor of the `msg:Payload` element.
-  This change is *not backwards-compatible*.
-- The types `BinaryDocument` and `DocumentReference` in `DeliveryRequest/Payload` were merged to remove duplicated element and to ensure that all fields that allow a conversion from `mzs:Payload` to `msg:Attachment` are available.
-  This change is *not backwards-compatible*.
+  This change is *not backward compatible*.
+- The types `BinaryDocument` and `DocumentReference` in `DeliveryRequest/Payload` were merged to remove duplicated element. Merging these elements ensures that both payload types contain all of `msg:Attachment`s mandatory fields.
+  This change is *not backward compatible*.
 - The element `MD5Checksum` in `DeliveryRequest/Payload/DocumentReference` was replaced with `msg:Checksum`, which was introduced by [zusemsg].
-  This change is *not backwards-compatible*.
-- The element `msg:Size` was added to `DeliveryRequest/Payload` because it was also added as a mandatory element in [zusemsg]. This change is not *backwards-compatible*.
-- The `sync` attribute was dropped in favor to the element `Config/ServiceTimeout`.
-  This change is *not backwards-compatible*.
+  This change is *not backward compatible*.
+- The element `msg:Size` was added to `DeliveryRequest/Payload` because it was also added as a mandatory element in [zusemsg]. This change is not *backward compatible*.
+- The `sync` attribute was dropped in favor of the element `Config/ServiceTimeout`.
+  This change is *not backward compatible*.
 
 ### Changes in `mzs:DeliveryResponse`
 
@@ -76,76 +79,76 @@ Due to the nature of the changes (feature additions and feature removals in [zus
   These mandatory elements were added to [zusemsg].
   This change is *backwards-compatible*.
 - Add `SignedDeliveryRequestStatus` to` MessageType`.
-  This optional element contains the original response that was send from the delivery service to MOA ZS.
-  The response was not modified such that containing signatures can be verified by the app.
-  This change is *backwards-compatible*.
-- Remove `MZSDeliveryID` because this ID does not exist anymore, as MOA ZS does not maintain requests in a database.
-  This change is *not backwards-compatible*.
-- Add the optional `PreadviceNoteSend` element to `ErrorType` because it was added in [zusemsg].
-  This change is *backwards-compatible*.
+  This optional element contains the original, unaltered response that was sent from the delivery service to MOA ZS.
+  The app can use this response to verify the contained signature.
+  This change is *backward compatible*.
+- Remove `MZSDeliveryID` because this ID does not exist anymore.
+  This change is *not backward compatible*.
+- Add the optional `PreadviceNoteSent` element to `ErrorType` because it was added in [zusemsg].
+  This change is *backward compatible*.
 - Remove `DocumentReference` from `ErrorType` because it was removed from [zusemsg].
-  This change is *not backwards-compatible*.
+  This change is *not backward compatible*.
 - Add the elements `msg:DeliveryTimestamp` and `msg:RelayedViaERV` to `SuccessType` because they were added in [zusemsg].
-  This change is *backwards-compatible*.
+  This change is *backward compatible*.
 
 ### Changes in `mzs:DeliveryNotification`
 
 - Remove `DeliveryConfirmation` and `DeliveryStatement` elements from `DeliveryNotification` as those element were dropped from [zusemsg].
-  This change is *not backwards-compatible*.
+  This change is *not backward compatible*.
 - Add the elements `msg:SenderDetails`, `msg:ReceiverDetails`, `msg:User`, `AdditionalFormat` and `msg:NotificationsPerformed` to the `DeliveryNotification` because they were added to [zusemsg].
-  This change is *backwards-compatible*.
+  This change is *backward compatible*.
 
 ### Changes in `mzs_mypersondata`
 
 - The element `AbstractPersonType` was defined as `abstract`, since the equivalent type in [zusemsg] is abstract as well.
-  This change is *not backwards-compatible*.
+  This change is *not backward compatible*.
 - The elements `Name` and `DateOfBirth` in `PhysicalPersonType` were set from optional to mandatory because they are mandatory in [zusemsg].
-  This change is *not backwards-compatible*.
+  This change is *not backward compatible*.
 - The optional element `Affix` was added to `PersonNameType` since this element was added to [zusemsg] as well.
-  This change is *backwards-compatible*.
+  This change is *backward compatible*.
 - The `CorporateBodyType` was extended by the optional `Target` element that was added to [zusemsg].
-  This change is *backwards-compatible*.
-- The elements `FullName` and `Organization` in `CorporateBodyType` were set from optional to mandatory because they are mandatory in [zusemsg].
-  This change is *not backwards-compatible*.
+  This change is *backward compatible*.
+- The elements `FullName` and `Organization` in `CorporateBodyType` were set from optional to mandatory because they are compulsory in [zusemsg].
+  This change is *not backward compatible*.
 - The restriction from `CountryCode` was lifted.
-  This change is *backwards-compatible*.
+  This change is *backward compatible*.
 - The optional attribute `type` was added to `PostalAddressType`.
-  This change is *backwards-compatible*.
+  This change is *backward compatible*.
 - The optional attribute `MessengerService` was added to `TelephoneAddressType`.
-  This change is *backwards-compatible*.
+  This change is *backward compatible*.
 
 ## Configuration
 
 The folder `src/test/resources/config` serves as a template for configuring MOA ZS.
 Most aspects of MOA ZS can be configured via [application.yaml](../src/test/resources/config/application.yaml).
-If you want to switch to your own configuration format, you may consult [Spring Boot Documentation: Externalized Configuration](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html).
+If you want to switch to a different configuration format, you may consult [Spring Boot Documentation: Externalized Configuration](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html).
 The following section explains individual configuration aspects.
 
 ### Delivery Request Configuration Profiles
 
-A configuration profile contains all parameters that determine, how MOA ZS processes a delivery request.
-The following list specifies, how a parameter can be configured and in which priority MOA ZS lets you override parameters (highest priority first):
+A configuration profile contains all parameters that determine how MOA ZS processes a delivery request.
+The following list specifies, how to configure a parameter and in which priority MOA ZS lets you override parameters, highest priority first:
 
 1. You can set a parameter directly in a `mzs:DeliveryRequest` under the `Config` element.
    See [app2mzs.xsd](../src/main/resources/mzs/app2mzs.xsd) for a list of parameters that you can configure.
-   Note that each parameter is optional and you can override individual parameters.
-   For parameters that are missing from the `Config` elements, MOA ZS falls back to the parameter from the referred profile.
-   The scope of a parameter in the `Config` element is limited to the current delivery request.
+   Note that each parameter is optional and you can override individual parameters, while omitting other parameters.
+   For parameters that are missing from the `Config` element, MOA ZS falls back to the parameter from the *referred profile*.
+   The scope of a parameter in the `Config` element is always limited to the current delivery request.
 
 2. You can refer to a specific profile in `mzs:DeliveryRequest/Config/ProfileID`, where the value of `ProfileID` refers to a profile that was configured in `application.yaml`.
    MOA ZS looks up the profile by the chosen ID and uses all parameters from this profile.
-   To create a profile in `application.yaml`, copy an existing profile, set a new `ProfileID` and adapt the parameters.
+   To create a profile in `application.yaml` copy the template from below or copy an existing profile from `application.yaml`, set a new `ProfileID` and adapt parameters.
    The key of each child in `delivery-request-configuration-profiles` is the `ProfileID` of the underlying profile.
    If a parameter is missing, MOA ZS falls back to the parameter in the `default` profile.
 
-3. If you so not specify a parameter in `Config`, if you do not select a `ProfileId`, or if the parameter in the selected profile is missing, MOA ZS falls back to the parameter in the `default` profile.
-
-If a mandatory parameter is not configured in any of the listed manners, MOA ZS rejects the delivery request.
+3. If you do not specify a parameter in `Config`, if you do not select a `ProfileId`, or if a parameter in the selected profile is missing, MOA ZS falls back to the parameter in the `default` profile.
+It is recommended to specify all mandatory parameters in this default profile.
+Otherwise, a parameter may be unconfigured, in which case MOA ZS rejects the delivery request.
 
 ### Structure of a Delivery Request Configuration Profile in `application.yaml`
 
-The following listing shows the structure of a delivery request configuration profile.
-You find a description and several examples eof the individual parameters in `application.yaml`.
+The following listing shows the structure of a delivery request configuration profile and serves as a template.
+You find a description and examples of the individual parameters in `application.yaml`.
 
 ```
   <ProfileID-string>:
@@ -206,10 +209,11 @@ This listing shows, how a connection of a client can be protected with SSL and h
 ### Logging
 
 MOA ZS uses Spring Boot's default logging backend, which is logback.
-In application.yaml you can choose, which loggers should log which levels.
+In `application.yaml` you can choose which loggers should log which levels.
 You can choose between the following five log levels (sorted by descending importance and ascending level of detail): `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`.
-You may specify if MOA ZS should log events to a file appender via `logging.file`.
-You can specify the logging format in `logback.xml`. See [Spring Boot Documentation: Logging](https://docs.spring.io/spring-boot/docs/current/reference/html/howto-logging.html) for details.
+You may specify if MOA ZS should log events to a file appender via the `logging.file` parameter.
+You can specify the logging format in `logback.xml`.
+See [Spring Boot Documentation: Logging](https://docs.spring.io/spring-boot/docs/current/reference/html/howto-logging.html) for further details.
 
 ## Namespace Declarations