Contents

1. Introduction

The Common Services of the OOTS provide machine-to-machine APIs both for querying and data lifecycle management. This section specifies the normative common part of these APIs using the OASIS Regrep 4.0 standard. Services implementing these interfaces MUST adhere to the following interface specifications.

2. Query Interface Specification

2.1. Introduction

The query interface specification for the Common Services is based on the OASIS ebXML RegRep V4 standard. This standard has multiple protocol bindings that can be used to execute queries. Since the Common Services queries have only simple, single-value parameters, the REST binding is used to implement the DSD query interface. This implies that the query transaction is executed as an HTTP GET request with the URL representing the query to execute and the HTTP response carrying the query response as an XML document. This section profiles the REST binding as specified in the OASIS RegRep standard for use by the Common Services.

2.2. The RegRep Query Request

The URL pattern for parameterised query invocation is defined as follows in the OASIS RegRep REST binding:

«server base url»/rest/search?queryId={the query id}(&{param-name}={param-value})*

The query interface consists of a simple predefined parameterised query detailed below. In addition, the RegRep standard defines a set of canonical queries and query parameters that can be used. As the Data Service Directory is not a complete implementation of a RegRep server, it is NOT REQUIRED to support these canonical queries and query parameters. Clients, therefore, SHOULD only use the queries and query parameters specified by this specification. When the canonical queries or parameters are used, the Common Service implementation MAY return an error.

2.3. The RegRep Successful Response

As specified by the RegRep REST binding, the implemented Common Service MUST always return a RegRep QueryResponse document which MUST either contain an Exception or RegistryObjectList element with zero or more RegistryObjects .

An example response, with response-specific details omitted, is provided in the following table:

<query:QueryResponse xmlns="urn:oasis:names:tc:ebxml-regrep:xsd:lcm:4.0"
    xmlns:lcm="urn:oasis:names:tc:ebxml-regrep:xsd:lcm:4.0"
    xmlns:query="urn:oasis:names:tc:ebxml-regrep:xsd:query:4.0"
    xmlns:rim="urn:oasis:names:tc:ebxml-regrep:xsd:rim:4.0"
    xmlns:rs="urn:oasis:names:tc:ebxml-regrep:xsd:rs:4.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:tc:ebxml-regrep:xsd:lcm:4.0" totalResultCount="1" startIndex="0" status="urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success">
    <!-- depending on the count of datasets returned, the totalResultCount attribute should
  reflect the number of the datasets returned -->
    <rim:RegistryObjectList>
        <!-- One registry object per dataset -->
        <rim:RegistryObject id="urn:uuid:a1be6e74-e9ba-4d44-b04c-0376f367b8fd">
            <rim:Slot name="DataServiceEvidenceType">
                <rim:SlotValue xsi:type="rim:AnyValueType">
                    <DataServiceEvidenceType xmlns="http://data.europa.eu/sdg#">
                      <!-- Omitted for clarity -->    
                    </DataServiceEvidenceType>
                </rim:SlotValue>
            </rim:Slot>
        </rim:RegistryObject>
    </rim:RegistryObjectList>
</query:QueryResponse>

2.4. The RegRep Error Response

When an error occurs during the execution of the query, the Common Service returns an exception as defined in the Common Service Query Interface Specification. The exception has the following properties that are profiled for each expected error of the query. 

• xsi:type: The type of the error, selectable from a predefined set of error classes of the Query Interface of the Common Service.
• severity: The severity of the error, selectable from a predefined set of error classes of the Query Interface of the Common Service.
• message: A string describing the error in Human Readable form.
• code: A code for the error, specified by the Common Service Technical Design documents.

An Example of an empty result set is provided below:

<?xml version="1.0" encoding="UTF-8"?>
<query:QueryResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     xmlns:rs="urn:oasis:names:tc:ebxml-regrep:xsd:rs:4.0"
                     xmlns:rim="urn:oasis:names:tc:ebxml-regrep:xsd:rim:4.0"
                     xmlns:query="urn:oasis:names:tc:ebxml-regrep:xsd:query:4.0"
                     status="urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Failure">
 
  <rs:Exception
      xsi:type="rs:ObjectNotFoundExceptionType"
      severity="urn:oasis:names:tc:ebxml-regrep:ErrorSeverityType:Error"
      message="No Evidence Providers were found based on the given parameters"
      code="DSD:ERR:0001">
  </rs:Exception>
</query:QueryResponse>

Depending on the exception raised, the message response may contain information on how to properly recover from the exception. For example, a common service may send back an exception when more attributes are needed to be provided in order for the Common Service to properly respond. These details are further specified in their respective specifications.

3. The Lifecycle Management Specification

3.1 Introduction

A Common Service MAY provide a Lifecycle Management (LCM) Interface for a bulk update of the information stored in the Common Services of a Member State. This section provides the technical specification of this interface as it will be implemented by the European Commission to implement its Common Services. This LCM interface is a highly constrained profile based on the RegRep 4.0 LCM Manager Interface Specification that has the following limitations:

• Only the SubmitObjects protocol is supported.
• Each Member State shall authorize at most one authorized competent authority to make submissions.    
• A submission is linked to a single Member State and made on behalf of that Member State.
• Submission linked to a single Member State do not affect data related to other Member States.
• A submission contains a complete, internally consistent set of data.  It is not possible to incrementally submit objects using a series of submissions.
• In case of a successful submission made for a Member State to a Common Service, any existing data previously submitted to the Common Service for that Member State is replaced. This obviates the need for the RemoveObjects protocol.
• In case of an unsuccessful submission made for a Member State to a Common Service, the existing data held by the Common Service is retained. 

Since object submission updates data, this profile use eDelivery for secure and reliable messaging as described below.

A service implementing the LCM specification MUST define a Classification Scheme using a unique urn. The Classification Scheme MUST contain all the Classification Nodes that properly characterize the registry objects and associations under submission.

The SubmitObjects Protocol defines a SubmitObjectsRequest message for sending the objects to be added together with successful and error responses. The following subsections define these messages in detail.

3.2 The Regrep LCM Submission

For the LCM submission, the profile uses the SubmitObjectsRequest message, as defined by the RegRep 4.0 LCM Manager Interface Specification SubmitObjects Protocol. A detailed guideline how the SubmitObjects Protocol is implemented for the Common Services is illustrated in the following sections: 

• LCM Interface Specification of the Evidence Broker
• LCM Interface Specification of the Data Service Directory

The message MUST contain a unique id and one Registry Object List containing the Registry Objects under submission.

The attribute “checkReferences” on SubmitObjectsRequest MUST be set to  “true” to express that a server MUST check submitted objects and make sure that all references via reference attributes and slots to other RegistryObjects are resolvable. If a reference does not resolve then the server MUST return UnresolvedReferenceException.

Each contained Registry Object MUST contain:

• A Classification with a Classification Node that is part of the Classification Scheme as defined by the service implementing the profile.
• An id attribute that must be unique using a UUID version 4 urn. This logical id MUST be used in the contained associations, for associating source and target registry objects.
• A Slot with a name that is identical with the Classification's Classification Node. The slot MUST contain the information of the Registry Object according to the service profiled specification

Each contained Registry Object that is an Association MUST Contain:

• the xsi:type which MUST be of value rim:AssociationType
• An id attribute that must be unique using a UUID version 4.
• the sourceObject attribute that denotes the starting point of the association. The attribute value MUST be the UUID v4 urn id of a Registry Object
• the targetObject attribute that denotes the ending point of the association. The attribute value MUST be the UUID v4 urn id of a Registry Object
• The type attribute which MUST use Classification Nodes, defined as extensions to the canonical AssociationType Classification Scheme of RegRep v4.0

<lcm:SubmitObjectsRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:rs="urn:oasis:names:tc:ebxml-regrep:xsd:rs:4.0"
  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:lcm="urn:oasis:names:tc:ebxml-regrep:xsd:lcm:4.0"
  xmlns:sdg="http://data.europa.eu/sdg#"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  id="urn:uuid:4dd63731-1b16-484e-af7c-baaf492f9073">

  <rim:RegistryObjectList>
    <rim:RegistryObject id="urn:uuid:a1be6e74-e9ba-4d44-b04c-0376f367b8fd">
      <rim:Classification id="urn:uuid:e8cd682c-08f2-4f90-a310-dc2c4d785fdb" 
           classificationScheme="urn:fdc:oots:classification:example" 
           classificationNode="ExampleNode"/>

      <rim:Slot name="ExampleNode">
        <rim:SlotValue xsi:type="rim:AnyValueType">
         <!-- Registry Object Data -->
        </rim:SlotValue>
      </rim:Slot>
    </rim:RegistryObject>

    <rim:RegistryObject id="urn:uuid:9d72ced7-638e-4023-9712-d7e871bf7d3d">
       <rim:Classification id="urn:uuid:e8cd682c-08f2-4f90-a310-dc2c4d785fdb" 
           classificationScheme="urn:fdc:oots:classification:example" 
           classificationNode="ExampleNode"/>
 
     <rim:Slot name="ExampleNode">
         <rim:SlotValue xsi:type="rim:AnyValueType">
         <!-- Registry Object Data -->
        </rim:SlotValue>
      </rim:Slot>

    </rim:RegistryObject>

    <!-- Association -->
    <rim:RegistryObject xsi:type="rim:AssociationType" 
         id="urn:uuid:ac720bc9-b967-4858-b3f7-83d26020dab7" 
         sourceObject="urn:uuid:a1be6e74-e9ba-4d44-b04c-0376f367b8fd" 
         targetObject="urn:uuid:9d72ced7-638e-4023-9712-d7e871bf7d3d" 
         type="urn:oasis:names:tc:ebxml-regrep:AssociationType:Serves"/>
  </rim:RegistryObjectList>
</lcm:SubmitObjectsRequest>

3.3 The Regrep LCM Successful Response

Upon a successful SubmitObjectsRequest message submission, the service MUST return a RegistryResponse message that MUST contain:

• A requestId attribute with the value of the id of the submitObjectsRequest that this message responds to.
• A status attribute with the value "Success"

3.3.1 Implementation Guide of a Regrep LCM Successful Response

The table below defines the elements of the data model illustrated above according to the RegRep 4.0 LCM Manager Interface Specification rs:RegistryResponse.

3.3.2 Example of a Regrep LCM Successful Response

The following example shows a successful response to the SubmitObjectsRequest of section 3.1

<RegistryResponse xmlns="urn:oasis:names:tc:ebxml-regrep:xsd:rs:4.0"
                  status="urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success"
                  requestId="urn:uuid:4dd63731-1b16-484e-af7c-baaf492f9073"/>

3.3.3. Business Rules associated to the Regrep LCM Successful Response

In order to facilitate interoperability of the Regrep LCM Successful Response, a set of business rules is defined to guarantee the correct structure, use and format of information objects. The rule IDs reference to the EB transaction "LCM Successfull Response" (LCM- SUC).

The table below lists the business rules to prove the structure (e.g. namespace, root elements, slots, data types, XSD-Binding and XSD-Restriction) and content format of information objects (e.g. identifiers, formats, fixed values, mandatory set of values on specific fields (code lists)) of a "LCM Successfull Response" (LCM- SUC).

3.4 The Regrep LCM Error Response

When an error occurs during the execution of the SubmitObjectsRequest, the Common Service returns an exception. The exception has the following properties that are profiled for each expected error of the submission request. 

• xsi:type: The type of the error, selectable from a predefined set of error classes of the LCM Interface of the Common Service.
• severity: The severity of the error, selectable from a predefined set of error classes of the LCM Interface of the Common Service.
• message: A string describing the error in Human Readable form.
• code: A code for the error, specified by the Common Service Technical Design documents.

3.4.1 Implementation Guide of a Regrep LCM Error Response

The table below defines the elements of the data model illustrated above according to the RegRep 4.0 LCM Manager Interface Specification rs:RegistryResponse.

3.4.2 Example of a Regrep LCM Error Response

An Example of an empty result set is provided below:

<?xml version="1.0" encoding="UTF-8"?>
<rs:RegistryResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     xmlns:rs="urn:oasis:names:tc:ebxml-regrep:xsd:rs:4.0"
                     xmlns:rim="urn:oasis:names:tc:ebxml-regrep:xsd:rim:4.0"
                     xmlns:query="urn:oasis:names:tc:ebxml-regrep:xsd:query:4.0"
                     status="urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Failure"
                     requestId="urn:uuid:4dd63731-1b16-484e-af7c-baaf492f9073">
 
  <rs:Exception
      xsi:type="rs:InvalidRequestExceptionType"
      severity="urn:oasis:names:tc:ebxml-regrep:ErrorSeverityType:Error"
      message="A registry object in the Request does not comply with the specification"
      code="LCM:ERR:0001">
  </rs:Exception>
</rs:RegistryResponse>

3.4.3 Common Error Codes of a Regrep LCM Error Response

3.4.4. Business Rules associated to the LCM Error Response 

In order to facilitate interoperability of the Regrep LCM Error Response, a set of business rules is defined to guarantee the correct structure, use and format of information objects. The rule IDs reference to the transaction "LCM Error Response" (LCM- ERR).

The table below lists the business rules to prove the structure (e.g. namespace, root elements, slots, data types, XSD-Binding and XSD-Restriction) and content format of information objects (e.g. identifiers, formats, fixed values, mandatory set of values on specific fields (code lists)) of a "LCM Error Response" (LCM- ERR).

3.4 eDelivery Configuration

Since object submission updates data, the LCM interface uses eDelivery for secure and reliable messaging.

Use of eDelivery MUST follow the OASIS ebXML Messaging Protocol Binding for RegRep Version 1.0.  That specification provides details needed for proper eDelivery configuration, including the values for the AS4 Service, Action and Role message headers and for packaging. 

Use of eDelivery MUST also follow the OOTS eDelivery configuration as specified in chapter 4.7. This means that the Access Point of the authorized competent authority is pre-configured for message exchange with the Access Point of the Common Service and that the four corner topology profile enhancement is used.

At most one competent authority per Member State will be allowed to send object submission requests to the Common Service. The party identifier for this authority will be used as originalSender in LCM requests and as finalRecipient in LCM responses. The Common Service MUST reject requests from parties other than authorized parties using exceptions of type AuthorizationException.