common-types.xsd

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xml="http://www.w3.org/XML/1998/namespace"
    elementFormDefault="qualified"

    targetNamespace="https://github.com/erasmus-without-paper/ewp-specs-architecture/blob/stable-v1/common-types.xsd"
    xmlns="https://github.com/erasmus-without-paper/ewp-specs-architecture/blob/stable-v1/common-types.xsd"
>
    <xs:import
        schemaLocation="http://www.w3.org/2001/03/xml.xsd"
        namespace="http://www.w3.org/XML/1998/namespace"
    />

    <xs:annotation>
        <xs:documentation>
            This schema is a part of the Erasmus Without Paper project. Before you start
            using it, make sure you have read the general rules described here:

            http://developers.erasmuswithoutpaper.eu/
        </xs:documentation>
    </xs:annotation>

    <xs:annotation>
        <xs:documentation>
            This file contains definitions of common types used in other EWP schemas. It
            probably deserves its own separate repository, but we keep it in the Architecture
            and Security repository, for backward-compatibility. (One disadvantage of this
            is the necessity to increase the version of the whole document every time a new
            type is added.)
        </xs:documentation>
    </xs:annotation>

    <xs:complexType name="StringWithOptionalLang">
        <xs:annotation>
            <xs:documentation>
                A string with an optional (but RECOMMENDED) xml:lang attribute. It is used in
                places where a name of some entity can be provided in multiple languages.
            </xs:documentation>
        </xs:annotation>
        <xs:simpleContent>
            <xs:extension base="xs:string">
                <xs:attribute ref="xml:lang" use="optional">
                    <xs:annotation>
                        <xs:documentation>
                            A note for client developers: Keep in mind, that `xml:lang` is of the
                            `xs:language` type. This means that it MAY contain values such as `en`, but
                            also `en-US`, `ar-Cyrl-CO`, or `tlh-Kore-AQ-fonipa`. Most often, you will
                            need to parse only the first component, but in some cases other components
                            might also be pretty useful (like the script subtag - "Latn", "Cyrl", etc.).

                            The `xml:language` datatype is defined here:
                            https://www.ietf.org/rfc/bcp/bcp47.txt

                            You can also discuss this tag in context of EWP here:
                            https://github.com/erasmus-without-paper/ewp-specs-architecture/issues/11
                        </xs:documentation>
                    </xs:annotation>
                </xs:attribute>
            </xs:extension>
        </xs:simpleContent>
    </xs:complexType>

    <xs:complexType name="MultilineString">
        <xs:annotation>
            <xs:documentation>
                This is very similar to a regular xs:string, but whenever this type is used it
                indicates that the content MAY contain basic whitespace formatting, such us
                line breaks and double line breaks (for splitting paragraphs). The values still
                MUST be in plaintext though (no HTML is allowed).

                Clients which process data of this type SHOULD respect line breaks when they
                display the data to the end user (e.g. replace CRs and LFs with &lt;br&gt;s
                when rendering to HTML).
            </xs:documentation>
        </xs:annotation>
        <xs:simpleContent>
            <xs:extension base="xs:string"/>
        </xs:simpleContent>
    </xs:complexType>

    <xs:complexType name="MultilineStringWithOptionalLang">
        <xs:annotation>
            <xs:documentation>
                A multiline string (as defined in the MultilineString) with an optional (but
                RECOMMENDED) xml:lang attribute. It is used in places where a description of
                some entity can be provided in multiple languages.
            </xs:documentation>
        </xs:annotation>
        <xs:simpleContent>
            <xs:extension base="MultilineString">
                <xs:attribute ref="xml:lang" use="optional">
                    <xs:annotation>
                        <xs:documentation>
                            Also see comments on xml:lang attribute in StringWithOptionalLang type.
                        </xs:documentation>
                    </xs:annotation>
                </xs:attribute>
            </xs:extension>
        </xs:simpleContent>
    </xs:complexType>

    <xs:simpleType name="UUID">
        <xs:annotation>
            <xs:documentation>
                Universally unique identifier (UUID), formatted in human-readable canonical
                format (32 lowercase hexadecimal digits, displayed in five groups separated by
                hyphens, in the form 8-4-4-4-12 for a total of 36 characters).

                https://en.wikipedia.org/wiki/Universally_unique_identifier
            </xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:string">
            <xs:pattern value="[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"/>
        </xs:restriction>
    </xs:simpleType>

    <xs:simpleType name="AsciiPrintableIdentifier">
        <xs:annotation>
            <xs:documentation>
                A generic base type for identifiers (surrogate keys).

                This type restricts the values as described here:
                https://github.com/erasmus-without-paper/ewp-specs-architecture#ids
            </xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:string">
            <xs:pattern value="[&#x0021;-&#x007E;]{1,64}"/>
        </xs:restriction>
    </xs:simpleType>

    <xs:simpleType name="Email">
        <xs:annotation>
            <xs:documentation>
                All elements with this type should be valid email addresses.

                Please note that passing the test for the attached regex pattern does NOT imply
                for the content to be a valid email. This pattern is extremely simplified and
                it will reject only a couple of obvious mistakes (as opposed to serious hacking
                attempts).
            </xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:string">
            <xs:pattern value="[^@]+@[^\.]+\..+"></xs:pattern>
        </xs:restriction>
    </xs:simpleType>

    <xs:complexType name="Empty">
        <xs:annotation>
            <xs:documentation>
                Just a reusable empty element type, with no content nor attributes. See:
                http://stackoverflow.com/questions/20751782/
            </xs:documentation>
        </xs:annotation>
    </xs:complexType>

    <xs:simpleType name="HTTPS">
        <xs:annotation>
            <xs:documentation>
                Secure (HTTPS), absolute URL.
            </xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:anyURI">
            <xs:pattern value="https://.+" />
        </xs:restriction>
    </xs:simpleType>

    <xs:simpleType name="HTTP">
        <xs:annotation>
            <xs:documentation>
                An absolute URL. Might be either HTTP or HTTPS.
            </xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:anyURI">
            <xs:pattern value="https?://.+"/>
        </xs:restriction>
    </xs:simpleType>

    <xs:complexType name="HTTPWithOptionalLang">
        <xs:annotation>
            <xs:documentation>
                An absolute URL (might be either HTTP or HTTPS) with an optional xml:lang
                attribute.

                This type is used in places where a single website can be provided in multiple
                language versions. However, as a general rule, if the website can correctly
                auto-detect client browser's preferred language, then server implementers
                SHOULD supply this element only once, and *without* the xml:lang attribute.
            </xs:documentation>
        </xs:annotation>
        <xs:simpleContent>
            <xs:extension base="HTTP">
                <xs:attribute ref="xml:lang" use="optional">
                    <xs:annotation>
                        <xs:documentation>
                            If given, it contains the language code the client should expect the website
                            content to be in.

                            Also see comments on xml:lang attribute in StringWithOptionalLang type.
                        </xs:documentation>
                    </xs:annotation>
                </xs:attribute>
            </xs:extension>
        </xs:simpleContent>
    </xs:complexType>

    <xs:complexType name="ManifestApiEntryBase">
        <xs:annotation>
            <xs:documentation>
                A common base type for children of the `apis-implemented` element of the
                manifest file. We declare it here (as opposed to declaring in the Discovery
                API's namespace) because it is shared between all the APIs - we want it to
                stay backwards-compatible when new releases of the Discovery API are published.

                IMPORTANT: Clients MUST NOT assume that all children of `apis-implemented` will
                "inherit" these properties. It is true that most EWP-related APIs do, but
                manifest files may contain references to *any* APIs.
            </xs:documentation>
        </xs:annotation>
        <xs:sequence>
            <xs:element ref="admin-email" minOccurs="0" maxOccurs="unbounded">
                <xs:annotation>
                    <xs:documentation>
                        RECOMMENDED element. Address of a developer or server administrator who may
                        be contacted in case of problems *with this particular API* (e.g. malformed
                        responses, etc.). Multiple `admin-email` elements may be provided.
                    </xs:documentation>
                </xs:annotation>
            </xs:element>
            <xs:element ref="admin-notes" minOccurs="0" maxOccurs="1">
                <xs:annotation>
                    <xs:documentation>
                        Additional information provided by host developers for the client developers.

                        E.g. "We are currently not delivering &lt;description&gt; elements because our
                        model is incompatible with the `1.1.3` schema. We will start to deliver them
                        once we upgrade to the `1.2.0` schema."
                    </xs:documentation>
                </xs:annotation>
            </xs:element>
        </xs:sequence>
        <xs:attribute name="version" use="required">
            <xs:annotation>
                <xs:documentation>
                    The API version number the host claims its implementation of this API conforms
                    to. Host implementers MUST make sure that this number is kept in sync with their
                    implementations.

                    E.g. If you have used the `1.1.3` release of some API when you have implemented
                    your endpoint, then you SHOULD put `1.1.3` here. If you put `1.2.0` here later
                    on, then it means that you have just implemented some new `1.2.0` features (and
                    you want to let other clients know that you have implemented them).

                    Use `0.0.0` when you're implementing a draft API, which has not been officially
                    released yet and doesn't have any version number yet.
                </xs:documentation>
            </xs:annotation>
            <xs:simpleType>
                <xs:restriction base="xs:string">
                    <xs:pattern value="[0-9]+\.[0-9]+\.[0-9]+"/>
                </xs:restriction>
            </xs:simpleType>
        </xs:attribute>
    </xs:complexType>

    <xs:simpleType name="CountryCode">
        <xs:annotation>
            <xs:documentation>
                ISO 3166-1 alpha-2 country code. These codes always have exactly 2 *upper-case*
                letters (this differentiates them from *language* ISO codes, which are
                lower-case.)
            </xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:string">
            <xs:pattern value="[A-Z][A-Z]"/>
        </xs:restriction>
    </xs:simpleType>

    <xs:simpleType name="EqfLevel">
        <xs:annotation>
            <xs:documentation>
                EQF Level. In EWP it is typically used to represent study levels (also known as
                study cycles), i.e. Bachelor is 6, Master is 7, and Doctorate is 8.
                Descriptions of all the levels can be found here:
                https://en.wikipedia.org/wiki/European_Qualifications_Framework
            </xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:byte">
            <xs:minInclusive value="1"/>
            <xs:maxInclusive value="8"/>
        </xs:restriction>
    </xs:simpleType>

    <xs:simpleType name="CefrLevel">
        <xs:annotation>
            <xs:documentation>
                CEFR level code. CEFR levels are used to represent a skill of a language.
                https://en.wikipedia.org/wiki/Common_European_Framework_of_Reference_for_Languages
            </xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:string">
            <xs:pattern value="[ABC][12]"/>
        </xs:restriction>
    </xs:simpleType>

    <xs:simpleType name="Gender">
        <xs:annotation>
            <xs:documentation>
                ISO/IEC 5218 code of human sex.

                https://en.wikipedia.org/wiki/ISO/IEC_5218
            </xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:integer">
            <xs:enumeration value="0">
                <xs:annotation>
                    <xs:documentation>not known</xs:documentation>
                </xs:annotation>
            </xs:enumeration>
            <xs:enumeration value="1">
                <xs:annotation>
                    <xs:documentation>male</xs:documentation>
                </xs:annotation>
            </xs:enumeration>
            <xs:enumeration value="2">
                <xs:annotation>
                    <xs:documentation>female</xs:documentation>
                </xs:annotation>
            </xs:enumeration>
            <xs:enumeration value="9">
                <xs:annotation>
                    <xs:documentation>not applicable</xs:documentation>
                </xs:annotation>
            </xs:enumeration>
        </xs:restriction>
    </xs:simpleType>

    <xs:element name="admin-email" type="Email">
        <xs:annotation>
            <xs:documentation>
                Address of a developer (or server administrator) who may be contacted in case of
                problems.

                This element was placed in the common-types namespace because it is being used
                in multiple schemas throughout the EWP project (most notably, various sections
                of the manifest file).
            </xs:documentation>
        </xs:annotation>
    </xs:element>

    <xs:element name="admin-notes" type="MultilineString">
        <xs:annotation>
            <xs:documentation>
                Additional information provided by administrators and/or developers.

                This element was placed in the common-types namespace because it is being used
                in multiple schemas throughout the EWP project (most notably, various sections
                of the manifest file).
            </xs:documentation>
        </xs:annotation>
    </xs:element>

    <xs:element name="error-response">
        <xs:annotation>
            <xs:documentation>
                A generic envelope for all kinds of errors. Servers should attempt to include
                this element in all HTTP 4xx and HTTP 5xx responses.
            </xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:sequence>
                <xs:element name="developer-message" type="MultilineString" minOccurs="1" maxOccurs="1">
                    <xs:annotation>
                        <xs:documentation>
                            A message for the client developer.

                            In case of client errors (HTTP 4xx responses) it should describe what the
                            client did wrong (e.g. a required parameter is missing, etc.).

                            In case of server errors (HTTP 5xx responses) it's usually much harder for the
                            server to determine what went wrong, so this element will probably contain just
                            some generic message in such cases (e.g. "Something went wrong. Administrators
                            have been notified. We'll try to fix it ASAP.").
                        </xs:documentation>
                    </xs:annotation>
                </xs:element>
                <xs:element name="user-message" type="MultilineStringWithOptionalLang" minOccurs="0" maxOccurs="unbounded">
                    <xs:annotation>
                        <xs:documentation>
                            A message for the client user.

                            This message will usually be provided only in case of some very specific client
                            errors (HTTP 4xx responses) - the ones that the client actually *expects* to
                            happen sometimes. For example, if the specification explicitly states that some
                            parameter values can be rejected by the server, but it doesn't state which ones
                            (because it's up to the server implementers to decide).

                            In such cases, the "wrong" values are usually provided by the end user. And
                            this error message should contain the explanation why the server believes
                            they're "wrong". For example:

                            """University of Warsaw doesn't currently allow receiving institutions to
                            propose changes to the content of the 'Recognition at the Sending Institution'
                            table. Please contact the sending coordinator by email to propose this
                            change."""

                            User messages MAY be provided in multiple languages. English SHOULD be among
                            them.
                        </xs:documentation>
                    </xs:annotation>
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

</xs:schema>