Technical reference manual

A few words about XML

Unavoidably, your XML documents (both program and edudexDirectory) have to meet a few technical requirements: each document has to be Well Formed, and it has to be Valid.

A Well Formed document complies with standard, simple XML rules as defined by the W3C. W3Schools (a useful web developers site, with tutorials and references on web development subjects, derives its name from the World Wide Web, but is not affiliated with the W3C) publishes an extremely clear explanation here; on this page you can also play around with some code fragments to see what impact changes will have on the well-formedness of the resulting XML.

Although the so called Prolog (like <?xml version="1.0" encoding="UTF-8"?>) is optional, it is considered best practice to provide one, if only to indicate the document's encoding. It will save you a lot of frustration when dealing with non-ASCII characters.

A document is Valid when it is Well Formed and conforms to a document type definition. In the case of an EDU-DEX document, the type definition is an XML Schema published as downloadable XSD (see this download page). Additionally, the definition can be referenced from the program and edudexDirectory elements. We strongly recommend you to do so: it will be very helpful when validating your documents.

If anything on this page needs further clarification, don't hesitate to use the Feedback button at the top. We take your comments seriously and will respond within 24 hours.

The program file

A document that fulfils the technical minimum (it is Well Formed and will pass validation against the EDU-DEX program.xsd) can be shown or downloaded using the buttons below. It also contains the Prolog mentined in the previous section, and the download contains refrences to the document's XML Schema. We recommend opening an additional copy of this manual (e.g. at the page showing the program's "road map"), so that you will have the explanation of each element or attribute at your fingertips.

Attention: in order to keep displayed code readable, even on small screens, some lengthy attributes have been replaced with an ellipsis (...); the full code is avaiable using the Download Code button.

Download code

	
<?xml version="1.0" encoding="utf-8"?>
<program ... >
	<editor>info@presendata.nl</editor>
	<expires xsi:nil="true" />
	<format>1.5</format>
	<generator>PresenData XML generator 1.4</generator>
	<inPublication>true</inPublication>
	<lastEdited>2018-12-21T21:37:25</lastEdited>
	<programAdmission>
		<applicationOpen>true</applicationOpen>
		<applicationType>individual</applicationType>
		<paymentDue>up-front</paymentDue>
		<startDateDetermination>direct start</startDateDetermination>
	</programAdmission>
	<programClassification>
		<degree>certificate</degree>
		<orgUnitId>pres</orgUnitId>
		<programDuration unit="day">5</programDuration>
		<programForm>full-time</programForm>
		<programId>PRD-160</programId>
		<programLevel>mbo+</programLevel>
		<programLocation>Utrecht</programLocation>
		<programType>training</programType>
		<startingYear>2018</startingYear>
	</programClassification>
	<programContacts>
		<contactData>
			<contactName>Training and Software Development</contactName>
			<email>training@presendata.nl</email>
			<role>Software Development and Training</role>
		</contactData>
	</programContacts>
	<programCurriculum>
		<instructionMode>seminar</instructionMode>
	</programCurriculum>
	<programDescriptions>
		<programName xml:lang="nl">Web Development using the Zend Expressive Framework</programName>
		<programSummaryText xml:lang="nl">A no-nonsense introduction to Zend Expressive</programSummaryText>
		<programDescriptionText xml:lang="nl">Covers installation, requirements, structure and specialisation.</programDescriptionText>
	</programDescriptions>
	<programSchedule />
</program>

Although the code presented above is technically valid, it provides only minimal information. A more realistic example, offering cost information (it could be called a Minimum Viable Product) is available below.

Download code

	
<?xml version="1.0" encoding="utf-8"?>
<program ... >
	<editor>info@presendata.nl</editor>
	<expires xsi:nil="true" />
	<format>1.5</format>
	<generator>PresenData XML generator 1.4</generator>
	<inPublication>true</inPublication>
	<lastEdited>2018-12-21T21:37:25</lastEdited>
	<programAdmission>
		<applicationOpen>true</applicationOpen>
		<applicationType>individual</applicationType>
		<paymentDue>up-front</paymentDue>
		<startDateDetermination>direct start</startDateDetermination>
	</programAdmission>
	<programClassification>
		<degree>certificate</degree>
		<orgUnitId>pres</orgUnitId>
		<programDuration unit="day">5</programDuration>
		<programForm>full-time</programForm>
		<programId>PRD-160</programId>
		<programLevel>mbo+</programLevel>
		<programLocation>Utrecht</programLocation>
		<programType>training</programType>
		<startingYear>2018</startingYear>
	</programClassification>
	<programContacts>
		<contactData>
			<contactName>Training and Software Development</contactName>
			<email>training@presendata.nl</email>
			<role>Software Development and Training</role>
		</contactData>
	</programContacts>
	<programCurriculum>
		<instructionMode>seminar</instructionMode>
	</programCurriculum>
	<programDescriptions>
		<programName xml:lang="nl">Web Development using the Zend Expressive Framework</programName>
		<programSummaryText xml:lang="nl">A no-nonsense introduction to Zend Expressive</programSummaryText>
		<programDescriptionText xml:lang="nl">Covers installation, requirements, structure and specialisation.</programDescriptionText>
	</programDescriptions>
	<programSchedule>
		<genericProgramRun>
			<contactHoursPartOfDay>day</contactHoursPartOfDay>
			<cost>
				<amount>50</amount>
				<amountVAT>3</amountVAT>
				<amountIsFinal>true</amountIsFinal>
				<costType>study material</costType>
				<currency>eur</currency>
				<isRequiredCost>true</isRequiredCost>
				<VATExemptAmount>50</VATExemptAmount>
				<VATExemptAmountVAT>3</VATExemptAmountVAT>
			</cost>
			<cost>
				<amount>956.25</amount>
				<amountVAT>200.81</amountVAT>
				<amountIsFinal>true</amountIsFinal>
				<costType>tuition fee</costType>
				<currency>eur</currency>
				<isRequiredCost>true</isRequiredCost>
				<VATExemptAmount>1051.88</VATExemptAmount>
				<VATExemptAmountVAT>0</VATExemptAmountVAT>
			</cost>
			<courseDay>
				<id>PRD-160MO</id>
				<dayOfTheWeek>Monday</dayOfTheWeek>
				<startTime>09:30:00</startTime>
				<endTime>16:30:00</endTime>
			</courseDay>
			<courseDay>
				<id>PRD-160TU</id>
				<dayOfTheWeek>Tuesday</dayOfTheWeek>
				<startTime>09:30:00</startTime>
				<endTime>16:30:00</endTime>
			</courseDay>
			<courseDay>
				<id>PRD-160WE</id>
				<dayOfTheWeek>Wednesday</dayOfTheWeek>
				<startTime>09:30:00</startTime>
				<endTime>16:30:00</endTime>
			</courseDay>
			<numberOfContactSessions>4</numberOfContactSessions>
		</genericProgramRun>
	</programSchedule>
</program>

Take your time to acquaint yourself with the available code, have a look at the documentation, and try modifying the downloaded code to suit your needs. At this stage you might consider to validate your own variations and switch to Step 3. Otherwise, proceed to Step 2 and learn more about the edudexDirectory structure.

If anything on this page needs further clarification, don't hesitate to use the Feedback button at the top. We take your comments seriously and will respond within 24 hours.

The directory file

The structure of an edudexDirectory is far less complex than the program covered in the previous step. Challenges only occur when a client specific approach is attempted, but that subject is covered elsewhere.

Again, we recommend opening an additional copy of this manual (e.g. using this link), so that you will have the explanation of each element or attribute at your fingertips.

Download code

	
<?xml version="1.0" encoding="utf-8"?>
<edudexDirectory ... >
	<editor>info@presendata.nl</editor>
	<generator>PresenData XML generator 1.4</generator>
	<version>0.90429</version>
	<orgUnitId>pres</orgUnitId>
	<programResource>
		<programId>PRD-160</programId>
		<resourceUrl>https://www.presendata.nl/api/public/PRD-160</resourceUrl>
	</programResource>
</edudexDirectory>

You are now set to validate the XML created in the previous steps.

If anything on this page needs further clarification, don't hesitate to use the Feedback button at the top. We take your comments seriously and will respond within 24 hours.

Validate the XML

Now that the first files are ready, it is time to validate them: you'd prefer warnings about oversights at an early stage, instead of being confronted with errors in code that is published to the public.

Fortunately, validation against the program or edudexDirectory XSD is very easy if they are referenced in the XML. A closer look at, e.g., the program element show several attributes that play a role in defining the standards being used.

xmlns=http://studieData.nl/schema/edudex/program
The default XML namespace is identified here; all elements and attributes that are not qualified with an explicit namespace, are supposed to belong to the "http://studieData.nl/schema/edudex/program" namespace.
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
This phrase defines "xsi" as an alias for http://www.w3.org/2001/XMLSchema-instance; by convention, this namespace denotes standard XML. It will see immediate use in the next attribute.
xsi:schemaLocation=http://studieData.nl/schema/edudex/program http://studieData.nl/schema/edudex/program.xsd
Here, the standard XML schemaLocation attribute indicates that a definition of what is available in the "http://studieData.nl/schema/edudex/program" namespace can be found at http://studieData.nl/schema/edudex/program.xsd. Utilities offering a validation service will gladly use this link.

Do not use a DOCTYPE declaration: a mixture of DTD and XSD leads to ambiguity; as of January 2020 validation will fail when a DOCTYPE is present.

Online and local validators are available in abundance. Many of them are free of charge, and allow validating against an XML referenced in the schemaLocation attribute as described above.

Your best choice, however, is the online service offered by EDU-DEX. It not only validates the XML you provide, but will also take into account some requirements EDU-DEX imposes that can't be described in an XSD.

When all files pass validation, they are ready to be published.

If anything on this page needs further clarification, don't hesitate to use the Feedback button at the top. We take your comments seriously and will respond within 24 hours.

Configure the web server

In general, no special requirements are imposed on the webserver hosting a supplier's XML feed. Occasionally, however, problems occur when EDU-DEX tries to read such a feed. These issues can usually be attributed to outdated software or SSL certificates. This, and a few items related to the readability and maintainability of the infrastructure are listed below.

Make sure the server software is up to date; a version of the operating system, the webserver or any plugin that is no longer supported by its vendor is bound to generate unexpected behaviour.
At this stage, SSL is recommended but not required. This might be a good time, however, to consider using https: you will need it anyway when, maybe in the near future, you wish to convey client specific information. Regularly check the validity of the SSL certificate being used and update it when necessary: an outdated certificate will cause the EDU-DEX feed reader to give up on the feed.
EDU-DEX does not enforce a specific structure of directory and program URLs; the only requirement is that the location of the edudexDirectory information doesn't change after registration (covered in the next step). For your own convenience, and to improve maintainability, it is recommended to keep the structure transparent. An example could be:
- Suppose the directory information resides at https://presendata/api/edudex/programs
- Then the details of program prd160 could be located at https://presendata/api/edudex/programs/prd160
We recommend publishing a RESTfull interface (see this explanation on Wikipedia) that only needs to support GET requests. The EDU-DEX servers, when gathering information, will never expect anything more.

Some authors interpret REST in a stricter way: Its advocates reject the use of parameters in URLs. In their view, https://www.yourdomain.nl/programs&id=prd160 is unacceptable; the URL should look like https://www.yourdomain.nl/programs/prd160. EDU-DEX takes a relaxed approach and accepts both interpretations.

If anything on this page needs further clarification, don't hesitate to use the Feedback button at the top. We take your comments seriously and will respond within 24 hours.

Register your offerings with EDU-DEX

The registration process is an informal one: an email message to info@edudex.nl, stating the location of your directory feed and the official name of your organisation, is sufficient. It is possible to provide more information about your organisation (see e.g. the institute definition), but this possibility is beyond the scope of this section.

After EDU-DEX has informed you about the orgUnitId that has been assigned (don't forget to adapt directory and program code accordingly), the publication cycle will start.

Every evening at 18:00 (CET) the EDU-DEX servers will read the directory feed, and subsequently the program feeds it defines. Validating and processing is executed during the night, and the next morning at 06:00 (CET) the information will be available. In case issues surfaced during validation or processing, you will be informed by e-mail around 03:00 (CET).

If anything on this page needs further clarification, don't hesitate to use the Feedback button at the top. We take your comments seriously and will respond within 24 hours.