Handling Standard XML Schemas

An XML Schema document is an XML document that defines a set of XML tag names that can be used to describe something in XML. Such documents typically end with the file extension .xsd. A W3C standard defines the XML language used to define the specialized tag names.

An IVOA standard XML schema is one that has been defined in an IVOA specification document that goes through the IVOA standardization process. Standard schemas are most commonly used in the IVOA in support of Registries, but they are also used in other areas.

All standard XML schema documents are available for download via http://ivoa.net/xml .

Naming Conventions

Namespace

A schema is identified via its namespace URI, which is globally unique. It is assigned within the schema (.xsd) document. A namespace URI for an IVOA standard schema must comply with the following convention:

http://ivoa.net/xml/shortname/vversion

where shortname is a short name identifying the schema and version is the version of the schema. For example, VOResource namespace URI is

http://ivoa.net/xml/VOResource/v1.0

Typically, versions are kept to a two field format, N.N, (e.g. "0.1", "1.0", or "2.1").

Schema filenames

The official name for a schema file name must have the following form:

shortname-vversion.xsd

where shortname and version correspond to the same fields in the namespace. For example, the VOResource schema is stored in a filename on the IVOA web server as

VOResource-v1.0.xsd

Publishing the XML schemas on the IVOA web site

Where schema files are accessed

In the IVOA, a standard schema is accessible via 2 different URLs. The first is a URL that matches the schema namespace (as defined above). The second is through a similar URL of the following form:

http://ivoa.net/xml/shortname/filename

where filename is the name mandated above. For example, the VOResource schema document can be downloaded through either of the following URLs:

http://ivoa.net/xml/VOResource/v1.0
http://ivoa.net/xml/VOResource/VOResource-v1.0.xsd

Both return the same document.

The first URL is convenient for XML-aware software. Software can tell if an XML document is correct by making sure it complies with the rules set out in the XML Schema document. The XML document can, optionally, say where to get the schema, but some software, if it isn't told where to find it, will try using the namespace URI as URL for the schema document itself.

The second URL tends to be convenient for human users. A user can access the directory at http://ivoa.net/xml/VOResource/ and browse the various versions there; if he wants to save the schema locally, he can click on it and his browser will typically ask him to save it with the name VOResource-v1.0.xsd. (The other URL might result in a local filename of v1.0, which is less convenient.)

When schema files are submitted or updated

There are typically three types of occasions when a schema file needs to be submitted to the web site and published.

1. A pre-standard version of the schema (e.g. VOblah-v0.1.xsd) needs to be posted to all developers to begin prototyping and testing applications.
2. An IVOA specification which defines a schema is submitted for posting in the document repository; the schema document should be submitted as well. (If the the schema file was submitted previously and there are no changes, then there is no need to post a new copy.)
3. An update to a schema is made to update the internal documentation or to correct some error in the document; in this case, there may be no corresponding change in the associate IVOA specification.

When updating a schema file, the author must consider carefully whether the version number needs to be updated. If a non-compatible change should result in a change to the namespace URI (and therefore the schema file name). Changing the version (in the namespace) when it is not necessary and not changing it when it needs to be can both be disruptive to applications that use them.

How a new or updated schema document is submitted

Working group chairs (or their explicit desginate) are responsible for submitting schema documents associated with their working group activities.

There are two ways to submit a schema document for publishing on the web site:

1. Include the schema file when submitting the standard document

A working group chair submits a new document for the repository via the document submission tool. To provide a schema document, the submitted file must be a tar or zip file that includes both the specification document and the schema file.

2. Email the schema file to the document coordinator

Send the file as an attachment in an email ivoadoc@ivoa.net. Please indicate in the email which working group the schema is associated with as well as what category of schema it falls into. The category indicates with section of the page at http://ivoa.net/xml the schema will be listed under.

Installing a schema document

The IVOA web site exists as a collection of directories and files on the file system all contained under a single root directory. In this section we refer to this root directory as <webroot&gt:.

Upon receipt of a submitted schema document, the following steps can be followed to publish:

1. Ensure that the submitter is authorized to submit the schema document
2. Ensure that the file has the proper name; change it if necessary.
3. Ensure that there is a directory under <webroot&gt:/xml named after the schemas short name.
4. If there already exists a schema file in the short-name directory with the same name as the one you are installing, back that file up by renaming it to an name of the form shortname-vversiondn.xsd (e.g. VOResource-v1.0d1.xsd). n is an integer starting with 1 that is incremented each time a new updated version is added. ("d" is a mneumonic for "deprecated".)
5. Copy the new schema into the short-name directory
6. In the same directory, create a copy of (or a link to) the schema file called vversion (e.g. v1.0). If there is already a file with that name, there is no need to back it up, just overwrite it.
7. Edit the file <webroot&gt:/xml/index.html to add the schema in the list in this page with a link to the latest version. If the schema is already listed, ensure that the latest version given corresponds to the version just submitted.