Specifications, Validators and Tools

Who should be reading this?

The following chapters and tools are written by developers and for
developers. If you're a project manager, then please assign
developer(s) from your team to keep track of the changes in these
specifications.

Developers chosen by the partners SHOULD:

Understand Git and be able to work with it fluently, in
order to continually keep track and review all the changes
to the specifications.

Have significant experience with XML namespaces, and
XML Schema language.

Integration with other EU projects

We have designed our Registry in a way that should allow it to be of use in
other EU projects too. If you are developing such a project, consider
using our Registry Service by hosting the Discovery Manifest file
compatible with our
specifications.
It's pretty straightforward and it should give you a head start (as you won't
need to implement a Registry of your own).

We are aiming for our Registry and Discovery API to become common underlying
parts of all similar projects focused on higher education in Europe. They are
designed to be extendible and can be used to describe all kinds of APIs (even
if some of these APIs clash together, by serving similar purpose in a different
manner).

What is EWP?

Erasmus Without Paper (EWP) project aims to ease exchanging data on
student mobility between computer systems in different countries (more
information here). In order to
make use of EWP, you will need to implement a subset of its APIs.

There are many APIs already present, and each partner will be allowed to
choose which of them he wants to implement (which allows you to start early, and
then expand to other scopes you want to participate in, step by step). Each such
API is documented separately.

Issue tracker

You can find all unresolved EWP issues
here
(if you get 404 error, then sign in to GitHub first).
If you want to browse only for the issues regarding one particular repository,
then go to the Issues tab on that repository's GitHub page (these are quite
mixed up though). You may also be interested in the available
search qualifiers.

Documents and specifications

Status labels used for not yet released documents

DRAFT
- working on it;

REVIEW RECOMMENDED
- still not a final version, but initial review is recommended;

PENDING APPROVAL
- waiting for the partners to officially
accept
the document.

Note, that discontinued drafts are usually simply removed from the
index of documents below. That's why there's no label for them.

Status labels used for released documents

LATEST RELEASE
- the latest accepted version of the document;

OBSOLETE
- might still be in use, but a newer version exists;

DEPRECATED
- might still be in use, but SHOULD be upgraded;

DISCONTINUED
- might have been used in the past, but is no longer; do not use it.

This document explains how the technical part of EWP documentation
is divided, where it is stored, how it should be designed, read and
approved.

"Technical part" refers to the part designed for software developers (the one
you are reading just now). There are lots of other types of documentation related
to the EWP project, but we are not discussing them here.

Discovery API is the first API that the partner developer needs to
implement in order to become a basic member of the *Erasmus Without Paper*
Network.

Discovery manifest files serve to announce which HEIs your system covers, which
features (APIs) you have implemented, and which credentials your clients are
going to use when fetching the data from the EWP Network.

This API allows beginner EWP developers to test the security of their EWP
Network connections. It doesn't "do" anything, but it requires the developer to
implement the core security framework (which will be needed by all the
other APIs later on).

This document describes the API implemented by the Registry Service.
It is placed in the "APIs" section of the documentation, but this does not
imply that we want you to implement it. You will be only using it (as a
client).

With help of some flowcharts, this document briefly describes how the
Student Mobility Business Process is modeled within the EWP Network. It
should be useful to get a quick grasp on which APIs are used by whom and
when.

This document describes the Institutions API. Once implemented by the host,
it allows external clients to retrieve general information on institutions
either covered, or otherwise known, by this host. This information
includes things like address, logo image and key contact persons.

This document describes the Organizational Units API. Once implemented by
the host, it allows external clients to retrieve general information on
selected organizational units (faculties, departments, divisions, etc.)
either covered, or otherwise known by this host. It responds with similar
type of information as Institutions API does, but on a lower level.

This document describes the Courses API. This API is not directly related
to EWP mobility APIs, but it might help with building user-friendly mobility
client software. It allows other HEIs to access information on courses and
other learning opportunities conducted in this institution.

This document describes the Simple Course Replication API. This API can be
implemented by any HEI, even it is does not take part in EWP mobility process.
Once implemented, it allows the clients to replicate the catalogue of courses
conducted on this HEI. This in turn allows the clients to design rich course
searching user experience.

This document describes the Interinstitutional Agreements API. This API
allows partners to compare their copies of interinstitutional Erasmus+ mobility
agreements with each other, which makes it easier to spot errors.

This document describes the Interinstitutional Agreement CNR API.
This API can be implemented by all EWP partners, and will be called by some
other EWP partners whenever related IIAs are changed on their side. It allows
the partners to listen for changes in other copies of their IIAs kept in the
EWP Network.

This document describes the Outgoing Mobilities API. This API is
implemented by the sending institution. It allows the receiving HEI to read
(but not change) data on mobilities stored on the sending HEI's servers.

This document describes the Outgoing Mobility CNR API. This API is
implemented by the receiving institution if it wants to be notified whenever
mobilities kept on their partner institutions' servers are changed.

This document describes the Incoming Mobilities API. This API is
implemented by the receiving institution. It allows the sending HEI to read the
receiving HEI's "part" of the information related to the sending HEIs outgoing
mobilities. (From the receiving HEI's perspective, these are the incoming
mobilities.)

This document describes the Incoming Mobility CNR API. This API is
implemented by the sending institution if it wants to be notified whenever
incoming mobilities kept on their partner institutions' servers are changed.

This document describes the Incoming Mobility Transcripts of Records API.
This API is implemented by the receiving institution. It allows the sending
institution to retrieve Transcripts of Records issued by the receiving
institution for a given set of mobility IDs.

This document describes the Incoming Mobility ToRs CNR API. This API is
implemented by the sending institution if it wants to be notified whenever
Transcript of Records served by the receiving institution (via the Incoming
Mobility ToRs API) are changed.

This document describes the Mobility Tool+ Institutions API.
It is assumed that this API is implemented by only one host managed by the
Directorate-General Education and Culture Unit (DG EAC) of the European Commission.
However, the specification itself does not limit the number of hosts.

Once implemented by the host, it allows external clients to retrieve
general information on institutions known by this host.

This document describes the Mobility Tool+ Projects API. It is assumed
that this API is implemented by only one host managed by the Directorate-General Education
and Culture Unit (DG EAC) of the European Commission. However, the specification itself
does not limit the number of hosts.

Once implemented by the host, it allows external clients to retrieve list of projects
for a particular institution and call year.

This document describes the Mobility Tool+ Dictionaries API. It is
assumed that this API is implemented by only one host managed by the Directorate-General
Education and Culture Unit (DG EAC) of the European Commission. However, the specification
itself does not limit the number of hosts.

Once implemented by the host, it allows external clients to retrieve terms from a
particular MT+ dictionary and call year.

This document describes the .ewpmobility file format. This specialized file
format is intended for exchanging student mobility data, in a form strictly
compatible with EWP. .ewpmobility files might prove useful when moving
mobility data from one institution to another, i.e. when migrating to EWP
workflow.

This repository contains XML Schemas used in EWP APIs for street and postal
addressing. It follows the same versioning rules as all EWP APIs do. Other
projects are welcome to reuse this schema, along with its namespace. We are also
open to suggestions of extending it.

This repository contains XML Schemas used in EWP APIs for encoding phone and
fax numbers. It follows the same versioning rules as all EWP APIs do. Other
projects are welcome to reuse this schema, along with its namespace. We are also
open to suggestions of extending it.

This repository contains XML Schemas used in EWP APIs for addressing academic
years and academic terms. It follows the same versioning rules as all EWP APIs
do. Other projects are welcome to reuse this schema, along with its namespace.
We are also open to suggestions of extending it.

This repository contains XML Schema used in some EWP APIs in contexts when
multiple, non-identifiable, abstract contact entities need to be attached to a
business entity. It follows the same versioning rules as all EWP APIs do.

This repository describes the identifier type we plan to use in EWP APIs to
uniquely identify people. It follows the same versioning rules
as all EWP APIs do. Other projects are welcome to reuse this data type, along
with its XML namespace. We are also open to suggestions of extending this
document.

Echo API Validator

This tool helps you to determine if your implementation meets the basic EWP standards
(in particular, all its security requirements).

Echo API
has been designed to serve two purposes: (a) to make developers aware of the specific
security features required by EWP, and (b) to allow us to run automated tests on all
existing implementations (thus reducing the risk of security misconfiguration). You will
need to implement this API first, and make sure it is connected to our
developer network.

Select Echo API instance to run validation on:

XML Schema Validator

This tool will help you with writing EWP XML documents. For example, you can paste
the contents of your Manifest
file here before you upload it onto your production site. You should be able to validate any
XML document described in all RELEASED,
DEPRECATED and
OBSOLETE specifications above (plus,
perhaps, some of the DRAFT ones).

Note, that this tool will validate against the schema only! Even if such validation succeeds,
your file may still be invalid (if, for example, you didn't adhere to the guidelines described in
<xs:documentation> elements included in the XSD files).