VERSION 1.0.0 MANDATORY

Contents

1. Exchange Data Model: QueryResponseError (EDM Error Response) 

This guideline explains how to use the ebRS QueryResponse using the ebRS RegistryExceptionType syntax to implement the Business Requirements (Req ID) described for the EDM Error Response. The guideline provides specific details for each class and information elements including the underlying standards, data types and cardinalities to produce conformant XML documents. In the following sections, we describe the XML serialization of the EDM Error Response in the same hierarchical order of the corresponding Exchange Data Model.

The Exchange Data Model in the figure below provides an overview of the information elements and their associations contained in the EDM Error Response. The EDM Error Response is a message created by the Evidence

Provider (EP) or more precisely, the entity returning an error message (ErrorProvider), which contains all the necessary parameters to perform the following actions:

• to either negatively respond to an Evidence Request due to an exception arising at the Error Provider (e.g. Evidence Provider or Gateway) or
• to return information about the preview location and to pause an "Evidence Response" until the data subject has agreed, in that preview location, to the use evidence.

Note that rim:Slot elements are to be processed based on the value of the name attribute, not on XML document order. However, it is good practice to following the order as presented in the diagram below.

To form a valid "QueryResponse" in the format of an EDM Error Response at least the following elements are required:

• the "status" of the QueryResponse;
• the "EvidenceResponseIdentifier" providing a unique identifier of the Response Message;
• the "SpecificationIdentifier" to identify the version of this specification;
• the "ErrorProvider" to describe the entity that is technically responsible for creating the QueryResponse; 
• the "Exception" itself is described through several mandatory codes and error messages. Each "Exception" must contain the "Timestamp" of the error occured.

The following Elements MUST be provided if they occur in the Evidence Request:

• the "requestId" of the QueryRequest;
• the "EvidenceRequester" to describe the entity that is technically responsible for receiving the QueryResponse; 

2. ebRIM Definition of the QueryResponseError (EDM Error Response)

This section defines the core ebRIM elements of the ebRS RegistryExceptionType that are used to compose a QueryResponseError (EDM Error Response). It thereby distinguishes between attributes and slots to define the Evidence Response:

Attribute Definition: The table provides an overview of the mandatory attributes and the information they contain for each QueryResponse in the format of an EDM Error Response according to the ebRIM element. 

Slot definition: The elements provide an overview of the defined ebRIM SlotType instances, which have a name and a value. The value is of type ValueType. Most rim:Slots do not contain sub-properties other than the SlotValue itself, except if they are collections. Collections refer to sources such as Core Vocabularies and a corresponding class defined in the SDG Generic Metadata Profile (see section 3). 

2.1 ebRIM QueryResponseError example

The EDM Error Responses are syntactically expressed inside an ebRS QueryResponse using the ebRS RegistryExceptionType as shown in the example below:

<?xml version="1.0" encoding="UTF-8"?>
<query:QueryResponse xmlns:rim="urn:oasis:names:tc:ebxml-regrep:xsd:rim:4.0"
    xmlns:query="urn:oasis:names:tc:ebxml-regrep:xsd:query:4.0"
    xmlns:sdg="http://data.europa.eu/p4s"
    xmlns:rs="urn:oasis:names:tc:ebxml-regrep:xsd:rs:4.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xlink="http://www.w3.org/1999/xlink"
    requestId="urn:uuid:4ffb5281-179d-4578-adf2-39fd13ccc797"
    status="urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Failure">
    <!-- The 'id' attribute of a 'QueryResponse' MUST be unique UUID (RFC 4122) for each request starting with prefix "urn:uuid:" -->
    <!-- The 'status' attribute of an unsuccessfull 'query:QueryResponse' MUST be encoded as as 'urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Failure'. -->

    <!-- Additional slots describing the response are omitted for clarity -->

    <!-- The value of 'xsi:type' attribute of a 'rs:Exception' MUST be a 'type' provided by code list 'EDMErrorCodes' (Exchange Data Model Error Response Codes).  -->
    <!-- The 'severity' attribute must be part of the code list 'ErrorSeverity' (Error Severity). The code 'urn:sr.oots.tech.ec.europa.eu:codes:ErrorSeverity:DSDErrorResponse:AdditionalInput' shall not be used by this transaction.  -->
    <!-- The value of 'severity' attribute of a 'rs:Exception' MUST  be 'urn:oasis:names:tc:ebxml-regrep:ErrorSeverityType:Error' if the rs:Exception xsi:type='rs:AuthorizationExceptionType' (@code 'EDM:ERR:0001') is NOT used.  -->
    <!-- The value of 'code' attribute of a 'rs:Exception' MUST be a 'code' matching the 'type' provided by code list 'EDMErrorCodes' (Exchange Data Model Error Response Codes). -->
    <!-- If a 'rim:Slot[@name='PreviewLocation']' is provided, the 'rs:Exception' MUST  be 'urn:sr.oots.tech.ec.europa.eu:codes:ErrorSeverity:EDMErrorResponse:PreviewRequired' and use the rs:Exception xsi:type='rs:AuthorizationExceptionType' (@code 'EDM:ERR:0001').  -->

    <rs:Exception xsi:type="rs:TimeoutExceptionType" severity="urn:oasis:names:tc:ebxml-regrep:ErrorSeverityType:Error "
        message="Exceeding timeout period"
        detail="No response from base registry for requestID 4ffb5281-179d-4578-adf2-39fd13ccc797."
        code="EDM:ERR:0005">

        <!-- Example for rs:Exception pointing to a required preview on the side of the Evidence Provider
        <rs:Exception xsi:type="rs:AuthorizationExceptionType" severity="urn:sr.oots.tech.ec.europa.eu:codes:ErrorSeverity:EDMErrorResponse:PreviewRequired"
        message="Missing Authorization"
        detail="The evidence provider requires authentication and preview and selection by the user in his domain to provide the evidence."
        code="EDM:ERR:0002"> -->


        <!-- Additional slots describing the exception and the preview if required -->

    </rs:Exception>
  </query:QueryResponse>

One or more rs:Exception elements  (1..n) can be put inside a QueryResponse. The following additional rules apply:

• The value of xsi:type  attribute of a rs:Exception  MUST be a 'type' provided by code list 'EDMErrorCodes'
• The severity  attribute must be part of the code list 'ErrorSeverity' (Error Severity). The code 'urn:sr.oots.tech.ec.europa.eu:codes:ErrorSeverity:DSDErrorResponse:AdditionalInput' shall not be used by this transaction.
• The value of severity  attribute of a 'rs:Exception' MUST be 'urn:oasis:names:tc:ebxml-regrep:ErrorSeverityType:Error' if the rs:Exception xsi:type ='rs:AuthorizationExceptionType' (@code 'EDM:ERR:0002') is NOT used. 
• The value of code attribute of a rs:Exception  MUST be a code  matching the type  provided by code list 'EDMErrorCodes' (Exchange Data Model Error Response Codes). 
• If a rim:Slot[@name='PreviewLocation'] is provided, the rs:Exception  MUST be 'urn:sr.oots.tech.ec.europa.eu:codes:ErrorSeverity:EDMErrorResponse:PreviewRequired' and use the rs:Exception xsi:type ='rs:AuthorizationExceptionType' (@code 'EDM:ERR:0002'). 

In the following table, the list of applicable ebRS Protocol Exceptions is provided that must be returned as xsi:type of the rs:Exception. The "detail" is a placeholder that may contain further information for specific errors. 

2.2 Specification Identifier example

The SpecificationIdentifier  element is used for expressing the version of the specification used for creating the referred document.

A Slot with the name of "SpecificationIdentifier" is used with the ValueType of StringValueType. In this version of the TDD specification, this MUST be set to the value oots-edm:v1.0

<!-- SpecificationIdentifier Slot -->
<rim:Slot name="SpecificationIdentifier">
    <rim:SlotValue xsi:type="rim:StringValueType">
        <!-- MUST be the fixed value "oots-edm:v1.0". -->
        <rim:Value>oots-edm:v1.0</rim:Value>
    </rim:SlotValue>
</rim:Slot>

2.3. Evidence Response Identifier example

The EvidenceResponseIdentifier element is used for expressing the Unique Identifier of the response generated by the evidence provider.

A Slot with the name of "EvidenceResponseIdentifier" is used with the ValueType of StringValueType. Note that in RIM, the rim:Value for an element of type StringValueType is of type LongText which has a length limit of 256 characters.

<!-- EvidenceResponseIdentifier Slot -->
<rim:Slot name="EvidenceResponseIdentifier">
    <rim:SlotValue xsi:type="rim:StringValueType">
        <!-- The 'rim:Value' of the 'EvidenceResponseIdentifier' MUST be unique UUID (RFC 4122) for each response. -->
        <rim:Value>530ad1e2-5eaf-4a9a-8192-227432eea95d</rim:Value>
    </rim:SlotValue>
</rim:Slot>

2.4 Timestamp example

The Timestamp element is used for expressing the creation date and time of the referenced error. 

Α Slot with the name of "Timestamp" is used with the ValueType of DateTimeValueType which has an ISO timestamp value according to xsd:dateTime.

<!-- TimeStamp -->
 <rim:Slot name="Timestamp">
     <rim:SlotValue xsi:type="rim:DateTimeValueType">
         <!-- The 'rim:Value' of 'Timestamp' MUST be according to xsd:dateTime.  -->
         <rim:Value>2020-02-14T19:20:30+01:00</rim:Value>
     </rim:SlotValue>
 </rim:Slot>

2.5 PreviewLocation example

The PreviewLocation  element is used for expressing the location of the Preview Space for the evidence request. 

Α Slot with the name of "PreviewLocation" is used with the ValueType of StringValueType which has the value of a URI. It MUST be a URI starting with 'https://'. Note that in RIM, the rim:Value for an element of type StringValueType is of type LongText which has a length limit of 256 characters.

<!-- Preview Location -->
 <rim:Slot name="PreviewLocation">
     <rim:SlotValue xsi:type="rim:StringValueType">
         <!-- The 'rim:Value' of a 'PreviewLocation' MUST be a URI starting with 'https://'. -->
         <rim:Value>https://preview.space.example.com/requests?session=d36af8bc-fea6-4ee5-a32d-5bef82cdb071</rim:Value>
     </rim:SlotValue>
 </rim:Slot>

2.6 PreviewDescription example

The PreviewDescription  element is used to provide additional explanatory information for the use of Preview Space. It provides text in possibly multiple natural languages that can be displayed to the user by the Online Procedure Portal. 

Α Slot with the name of "PreviewDescription" is used with the ValueType of InternationalStringValueType. The 'language' attribute of 'PreviewDescription' MUST be specified using the code list 'LanguageCode'. Default value "EN". Note that in RIM, the value of the attribute value of the element LocalizedString of type StringValueType is of type FreeFormText which has a length limit of 1024 characters.

<!-- Preview Description -->
 <rim:Slot name="PreviewDescription">
     <rim:SlotValue xsi:type="rim:InternationalStringValueType">
         <!-- The 'language' attribute of 'PreviewDescription' MUST be specified using the code list 'LanguageCode'. Default value "EN". -->
         <rim:Value>
             <rim:LocalizedString xml:lang="NL" value="Kies uw diploma."/>
             <rim:LocalizedString xml:lang="RO" value="Vă rugăm să selectați diploma dvs."/>
             <rim:LocalizedString xml:lang="EN" value="Please select your diploma."/>
             <rim:LocalizedString xml:lang="DE" value="Bitte wählen Sie Ihr Diplom aus."/>
          </rim:Value>
     </rim:SlotValue>
 </rim:Slot>

2.7 PreviewMethod example

The PreviewMethod  element is used for expressing the HTTP verb to access the Preview Space. 

Α Slot with the name of "PreviewMethod" is used with the ValueType of StringValueType which has the value of a either "GET", "PUT" or "POST".

<!-- Preview Method -->
 <rim:Slot name="PreviewMethod">
     <rim:SlotValue xsi:type="rim:StringValueType">
         <!-- The 'rim:Value' of a 'PreviewMethod' MUST be either the HTTP verb 'GET', 'POST' or 'PUT;. -->
         <rim:Value>GET</rim:Value>
     </rim:SlotValue>
 </rim:Slot>

3. SDGR Application Profile for the EDM Error Response

The SDGR application profile for the EDM Error Response defines the semantics of the previously introduced rim:Slots defined as a collection (green components) of the Evidence Response Message. The SDGR application profile for the EDM Error Response describes how the SDG-Generic-Metadata Profile (SDG-syntax) is profiled in ebRIM in order to compose a valid QueryResponse. It therefore contains a mapping to the underlying SDG-syntax elements and necessary parameters for providing the EDM Error Response on the basis of an earlier Evidence Request.  Thus, the values for several parameters are obtained from the Evidence Provider that is responding to the Evidence Request.  The namespace of the SDG-syntax is https://data.europa.eu/p4s. In the following samples, the prefix "sdg" is assumed to be linked to the namespace http://data.europa.eu/p4s.

3.1 Error Provider slot and example

Element to describe the organisation or agent that is providing the error. In most cases the Error Provider is the Evidence Provider informing the Evidence Requester about a failed response or missing information or to preform an authentication or preview. However, in case of multiple national routings an error might be created by an intermediate, a technical endpoint (e.g. gateway) as well or by a businesses that has been accredited to supply the evidence.  

The following info box and role model illustrates the principles and agent roles that can be applied for the Error Provider.

A Slot with the name of ErrorProvider  is expressed with the ValueType of AnyValueType which accepts any xml representation. In this particular case, the Agent class is used for the expression of the Error Provider information inside the AnyValueType Slot.

The value of the schemeID  attribute of the Identifier MUST not extend 256 characters and it either, MUST use the prefix 'urn:cef.eu:names:identifier:EAS:[Code]' and a code being part of the code list 'EAS' (Electronic Address Scheme ) OR it MUST use the prefix 'urn:oasis:names:tc:ebcore:partyid-type:unregistered:[Code]' and a code being part of the code list ‘ISO 3166-1 alpha-2 country code (EEA_country subset)’.

The value of lang  attribute of the Name MUST be part of the code list 'LanguageCode'. Default value "EN". 

The value of the AdminUnitLevel1  MUST be coded using the code list 'CountryIdentificationCode' (ISO 3166-1' alpha-2 codes). It must be provided.

The value of the AdminUnitLevel2  MUST be coded using the code list 'NUTS' (Nomenclature of Territorial Units for Statistics).

The Slot  can hold information about the Evidence Provider or Intermediaries or other agents. The roles are classified through the element Classification . The value of Classification  MUST be part of the code list 'AgentClassification'. Default value: ERRP (Error Provider). The code 'ER' shall not be used by this transaction.  

<!--   ErrorProvider Slot --> 
<rim:Slot name="ErrorProvider" 
    xmlns:rim="urn:oasis:names:tc:ebxml-regrep:xsd:rim:4.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <rim:SlotValue xsi:type="rim:AnyValueType">
        <sdg:Agent xmlns:sdg="http://data.europa.eu/p4s">
            <!-- The value of the schemeID  attribute of the Identifier MUST not extend 256 characters and it either, MUST use the prefix 'urn:cef.eu:names:identifier:EAS:[Code]' and a code being part of the code list 'EAS' (Electronic Address Scheme ) OR it MUST use the prefix 'urn:oasis:names:tc:ebcore:partyid-type:unregistered:[Code]' and a code being part of the code list ‘ISO 3166-1 alpha-2 country code (EEA_country subset)’. -->
            <sdg:Identifier schemeID="urn:cef.eu:names:identifier:EAS:0204">DE7657587001</sdg:Identifier>
		 <!-- The value of 'lang' attribute MUST be part of the code list 'LanguageCode'. Default value "EN".  -->
            <sdg:Name lang="EN">Authority for school and occupational training</sdg:Name>
            <sdg:Address>
                <sdg:FullAddress>Hamburger Str. 31, 22083 Hamburg, Germany</sdg:FullAddress>
                <sdg:LocatorDesignator>31</sdg:LocatorDesignator>
                <sdg:PostCode>22083</sdg:PostCode>
                <sdg:PostCityName>Hamburg</sdg:PostCityName>
                <sdg:Thoroughfare>Hamburger Str.</sdg:Thoroughfare>
                <!-- The value of the 'AdminUnitLevel1' MUST be coded using the code list 
            'CountryIdentificationCode' (ISO 3166-1' alpha-2 codes).  -->
                <sdg:AdminUnitLevel1>DE</sdg:AdminUnitLevel1>
                <!-- The value of the 'AdminUnitLevel2' MUST be coded using the code list 
            'NUTS' (Nomenclature of Territorial Units for Statistics).  -->
                <sdg:AdminUnitLevel2>DE60</sdg:AdminUnitLevel2>
            </sdg:Address>
            <!--   The value MUST be part of the code list 'AgentClassification'. 
        Default value: ERRP (Error Provider). The code 'ER' shall not be used by this transaction.  -->
            <sdg:Classification>ERRP</sdg:Classification>
        </sdg:Agent>
    </rim:SlotValue>
</rim:Slot>       

3.2 Evidence Requester slot and example

Element to describe the organisation or agent that has requested the evidence. The agent requests the evidence, by sending an evidence request to the evidence provider, on behalf of the evidence subject.  In several cases it might be a portal/organisation that initiates the evidence request. However, the response must be returned to the Evidence Requester that initiated the evidence request and not to the portal /intermediary in case there are more than one Evidence Requesters named in the evidence request. 

No central registry of evidence requesters is required, only the minimal details required to enable legal logging of requests or facilitate the processing of the evidence request. 

The following info box and role model illustrates the principles and agent roles that can be applied for the Evidence Requester.

The Evidence Requester element is used to describe an organisation that requests data or documents from Evidence Providers.

A Slot with the name of EvidenceRequester  is used with the ValueType of AnyValueType which accepts any xml representation. In this particular case, the Agent class of the Core Public Service Vocabulary Application Profile is used for the expression of the Evidence Requester information inside the AnyValueType Slot.

The value of the schemeID  attribute of the Identifier MUST not extend 256 characters and it either, MUST use the prefix 'urn:cef.eu:names:identifier:EAS:[Code]' and a code being part of the code list 'EAS' (Electronic Address Scheme ) OR it MUST use the prefix 'urn:oasis:names:tc:ebcore:partyid-type:unregistered:[Code]' and a code being part of the code list ‘ISO 3166-1 alpha-2 country code (EEA_country subset)’.

The value of lang  attribute of the Name MUST be part of the code list 'LanguageCode'. Default value "EN". 

<!--   Evidence Requester  -->
<rim:Slot name="EvidenceRequester">
    <rim:SlotValue xsi:type="rim:AnyValueType">
        <sdg:Agent>
            <!-- The value of the schemeID  attribute of the Identifier MUST not extend 256 characters and it either, MUST use the prefix 'urn:cef.eu:names:identifier:EAS:[Code]' and a code being part of the code list 'EAS' (Electronic Address Scheme ) OR it MUST use the prefix 'urn:oasis:names:tc:ebcore:partyid-type:unregistered:[Code]' and a code being part of the code list ‘ISO 3166-1 alpha-2 country code (EEA_country subset)’. -->
            <sdg:Identifier schemeID="urn:cef.eu:names:identifier:EAS:0190">NL22233223</sdg:Identifier>
            <!-- The value of 'lang' attribute MUST be part of the code list 'LanguageCode'. Default value "EN". -->
            <sdg:Name lang="EN">Dutch University Portal</sdg:Name>
        </sdg:Agent>
    </rim:SlotValue>
</rim:Slot>