UWS (Universal Worker Service)

UWS is a protocol for describing and executing jobs on remote services. vo-models currently provides support for the UWS 1.1 version of the protocol.

Note

In the provided examples, the UWS namespace has not been included for brevity. As output by to_xml(), the namespace is included in the root element of the XML document.

Models for UWS are provided in the vo_models.uws package. Supported models and examples of their usage are:

Models

ErrorSummary

Represents an error summary returned by a UWS service as part of a JobSummary object.

Model

error_summary = ErrorSummary(
    type="fatal",
    has_detail=True,
    message="The job failed because of a missing parameter.",
)

error_summary.to_xml()

XML Output

<uws:errorSummary
    type="fatal" hasDetail="true">
<uws:message>The job failed because of a missing parameter.</uws:message>
</uws:errorSummary>

Parameter

Represents a single parameter of a UWS job.

Model

parameter = Parameter(
    id="lang",
    value="ADQL",
    is_post=False,
    by_reference=False,
)

parameter.to_xml()

XML Output

<uws:parameter byReference="false" id="lang" isPost="false">
    ADQL
</uws:parameter>

For multi-valued attributes, use the type vo_models.uws.models.MultiValuedParameter instead of list[Parameter]. This is equivalent to list[Parameter] but adds some special validation support required for multi-valued UWS job parameters.

Parameters

Represents a collection of Parameter objects.

Attention

This is a generic class that must be subclassed to represent the parameters of the specific service using the UWS protocol.

See JobSummary for an example of how this is used in the context of a UWS job summary response.

For example, for a TAP service, the parameters could be represented as follows:

Model

class TAPParameters(Parameters):
    lang: Parameter = Parameter(id="lang")
    query: Parameter = Parameter(id="query")
    maxrec: Parameter = Parameter(id="maxrec")
    format: Parameter = Parameter(id="format")


parameters = TAPParameters(
    lang=Parameter(value="ADQL", id="lang"),
    query=Parameter(value="SELECT * FROM ivoa.obscore", id="query"),
    maxrec=Parameter(value=10, id="maxrec"),
    format=Parameter(value="votable", id="format"),
)
parameters.to_xml()

XML Output

<uws:parameters>
    <uws:parameter byReference="false" id="lang" isPost="false">ADQL</uws:parameter>
    <uws:parameter byReference="false" id="query" isPost="false">SELECT * FROM ivoa.obscore</uws:parameter>
    <uws:parameter byReference="false" id="maxrec" isPost="false">10</uws:parameter>
    <uws:parameter byReference="false" id="format" isPost="false">votable</uws:parameter>
</uws:parameters>

ResultReference

Represents a single result reference as returned by a UWS service as part of a Results object.

Model

result_reference = ResultReference(
    id="result",
    href="http://example.com/result",
)

result_reference.to_xml()

XML Output

<uws:result
    id="result"
    xlink:type="simple"
    xlink:href="http://example.com/result"/>

Results

Represents a collection of ResultReference objects.

Model

results = Results(
    results=[
        ResultReference(id="result1", href="http://example.com/result1"),
        ResultReference(id="result2", href="http://example.com/result2"),
    ],
)

results.to_xml()

XML Output

<uws:results>
    <uws:result id="result1" xlink:type="simple" xlink:href="http://example.com/result1"/>
    <uws:result id="result2" xlink:type="simple" xlink:href="http://example.com/result2"/>
</uws:results>

ShortJobDescription

Represents a UWS jobref element, returned when fetching the job list from a UWS service.

Note

Note that the XML tag <uws:jobref> differs from the model name ShortJobDescription.

The Python model uses the name of the complexType defined in the UWS schema, but when serialized uses the tag name defined as part of the <xs:element> definition.

See Jobs for an example of how this is used in the context of a UWS job list response.

Model

short_job_description = ShortJobDescription(
    phase="PENDING",
    run_id="1234567890",
    owner_id="anon_user",
    creation_time=datetime.datetime.now(),
    job_id="job_1",
)

short_job_description.to_xml()

XML Output

<uws:jobref id="job_1" xlink:type="simple" xlink:href="">
    <uws:phase>PENDING</uws:phase>
    <uws:runId>1234567890</uws:runId>
    <uws:ownerId>anon_user</uws:ownerId>
    <uws:creationTime>2023-12-27T12:19:46.889Z</uws:creationTime>
</uws:jobref>

Jobs

Represents a collection of ShortJobDescription objects, returned at the UWS job list endpoint.

Model

jobs = Jobs(
    jobref=[
        ShortJobDescription(
            phase="PENDING",
            run_id="1234567890",
            owner_id="anon_user",
            job_id="job_1",
        ),
        ShortJobDescription(
            phase="COMPLETED",
            run_id="1234567891",
            owner_id="anon_user",
            job_id="job_2",
        ),
    ],
)

jobs.to_xml()

XML Output

<uws:jobs>
    <uws:jobref id="job_1" xlink:type="simple" xlink:href="">
        <uws:phase>PENDING</uws:phase>
        <uws:runId>1234567890</uws:runId>
        <uws:ownerId>anon_user</uws:ownerId>
        <uws:creationTime></uws:creationTime>
    </uws:jobref>
    <uws:jobref id="job_2" xlink:type="simple" xlink:href="">
        <uws:phase>COMPLETED</uws:phase>
        <uws:runId>1234567891</uws:runId>
        <uws:ownerId>anon_user</uws:ownerId>
        <uws:creationTime></uws:creationTime>
    </uws:jobref>
</uws:jobs>

JobSummary

A model for the complete representation of a UWS job summary, returned by fetching the job id from a UWS service.

Attention

This is a generic class that expects to be provided a subclass of Parameters to represent the parameters of the specific service using the UWS protocol.

The example below uses the TAPParameters class, shown in the Parameters example above, to represent the parameters of a TAP service.

Note

In this example, we have included the XML namespace in the output, to show how the namespace is included in the root element of the XML document.

Model

parameters = TAPParameters(
    lang=Parameter(value="ADQL", id="lang"),
    query=Parameter(value="SELECT * FROM ivoa.obscore", id="query"),
    maxrec=Parameter(value=10, id="maxrec"),
    format=Parameter(value="votable", id="format"),
)

job_summary = JobSummary[TAPParameters](
    job_id = "job_1",
    owner_id = "anon_user",
    phase = "COMPLETED",
    creation_time = "2023-12-01T12:00:00.000Z",
    start_time = "2023-12-01T12:00:00.000Z",
    end_time = datetime.datetime.now(),
    parameters = parameters,
    results = Results(
        results=[
            ResultReference(id="result1", href="http://example.com/result1"),
            ResultReference(id="result2", href="http://example.com/result2"),
        ],
    ),
)

job_summary.to_xml()

XML Output

<uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0"
    xmlns:xlink="http://www.w3.org/1999/xlink"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    version="1.1">
    <uws:jobId>job_1</uws:jobId>
    <uws:runId></uws:runId>
    <uws:ownerId>anon_user</uws:ownerId>
    <uws:phase>COMPLETED</uws:phase>
    <uws:quote xsi:nil="true"></uws:quote>
    <uws:creationTime>2023-12-01T12:00:00.000Z</uws:creationTime>
    <uws:startTime>2023-12-01T12:00:00.000Z</uws:startTime>
    <uws:endTime>2023-12-27T12:47:37.196Z</uws:endTime>
    <uws:executionDuration>0</uws:executionDuration>
    <uws:destruction xsi:nil="true"></uws:destruction>
    <uws:parameters>
        <uws:parameter byReference="false" id="lang" isPost="false">ADQL</uws:parameter>
        <uws:parameter byReference="false" id="query" isPost="false">SELECT * FROM ivoa.obscore</uws:parameter>
        <uws:parameter byReference="false" id="maxrec" isPost="false">10</uws:parameter>
        <uws:parameter byReference="false" id="format" isPost="false">votable</uws:parameter>
    </uws:parameters>
    <uws:results>
        <uws:result id="result1" xlink:type="simple" xlink:href="http://example.com/result1"/>
        <uws:result id="result2" xlink:type="simple" xlink:href="http://example.com/result2"/>
    </uws:results>
</uws:job>

Simple Types

The following simple types are provided in the vo_models.uws package for use in UWS models:

• vo_models.uws.types.ErrorType

• vo_models.uws.types.ExecutionPhase

• vo_models.uws.types.UWSVersion