Clarify description for getNode detail

[Zarquan]

The current description for the getNode detail parameter needs clarification.

The text for the detail parameter suggests that it controls the level of detail for the requested node itself rather than any child nodes.

detail with values of:

• min: the returned record for the node contains minimum detail with all optional parts removed – the node type should be returned. e.g.,
• max : the returned record for the node contains the maximum detail, including any xsi:type specific extensions
• properties: the returned record for the node contains the basic node element with a list of properties but no xsi:type specific extensions

As is, this text seems to suggest that the following request:

http://server.example.com/vospace/nodes/mydir?detail=min

Would simply return the minimal response for that node.

<vos:node uri="vos://example.com!vospace/mydir" xsi:type="vos:ContainerNode">

On the other hand, the example given in the text returns the full content for the container node, including properties, accepts, provides and capabilities, and only applies the detail filter to the child nodes.

<vos:node xmlns:vos="...." uri="vos://example.com!vospace/mydir" xsi:type="vos:ContainerNode">
<vos:properties>
  <vos:property uri="ivo://ivoa.net/vospace/core#description">My award winning images</property>
</vos:properties>
<vos:accepts>
  <vos:view uri="ivo://ivoa.net/vospace/core#anyview"/>
</vos:accepts>
<vos:provides>
  <vos:view uri="ivo://ivoa/net/vospace/core#defaultview"/>
</vos:provides>
<vos:capabilities/>
<vos:nodes>
  <vos:node uri="vos://example.com!vospace/mydir/file3401" xsi:type="vos:DataNode"/>
  <vos:node uri="vos://example.com!vospace/mydir/file3406" xsi:type="vos:DataNode"/>
  <vos:node uri="vos://example.com!vospace/mydir/file3532" xsi:type="vos:DataNode"/>
</vos:nodes>

My guess is that the detail parameter only applies to the child nodes of a container node. In which case the text needs to specify this.

detail with values of:

• min: the returned record for the a container node contains minimum detail for any child nodes, with all optional parts removed – *only the child node type should be returned. e.g., <Node uri="vos://service/name" xsi:type="Node"/>
• max : the returned record for the a container node contains the maximum detail for any child nodes, including any xsi:type specific extensions
• properties: the returned record for the a container node contains the basic node element for any child nodes, with a list of properties but no xsi:type specific extensions

[Zarquan]

The text should also say what effect, if any, the detail parameter has on a data node.

Given this request:

http://server.example.com/vospace/nodes/mydir/file3406?detail=min

Does it make sense to only return the node type and nothing else:

<vos:node uri="vos://example.com!vospace/mydir/file3406" xsi:type="vos:DataNode"/>

[zonia3000]

I have some doubts about this.

I'm assuming that the goal of the detail filter is to limit the size of the response body, that could be very big, especially for container nodes having many children, and/or also to avoid retrieving too much unnecessary information from the databases.

I think that on a listing operation it could be useful to retrieve all the properties and views of the container node and the list of its children without details, so the proposed behavior that applies the detail filter only to child nodes makes sense to me.

However I find a bit weird to remove the properties if detail=min is applied to a data node, because as displayed on figure 2 of the current document, container nodes are a specialization of data nodes. So we should say that for data nodes that are not container nodes the behavior should be different. We should also cover link nodes case. I don't see a pratical use case for retrieving only the type of a node, so maybe we could say that the detail filter applies only to container nodes and that would simplify the specification.

I think that we should also explicitly say what to do with the busy attribute and, if we apply the filter also to link nodes, what to to with the target element.

I'm also a bit puzzled about the behavior of detail=properties. I think that its goal is to retrieve only properties if you are not interested in views and capabilities, but I don't see the purpose of removing also the type attribute. Maybe I'm just missing something, so it could be nice to have some comments from who proposed this feature in the past.

I know that this discussion is about the standard but probably we should also consider current implementations status.

I played a bit with CADC implementation and it seems that detail=min removes the properties from the container (or data node) but not from the child nodes, detail=max adds some non standard properties and detail=properties seems to be ignored.

From INAF side I can say that removing the xsi:type for the detail=properties could be difficult, since we are using JAXB that automatically generates that attribute based on the Java class type that is used.

[Zarquan]

so maybe we could say that the detail filter applies only to container nodes and that would simplify the specification.

Yep, I agree.

[Zarquan]

I don't think we should remove the type attribute. I think the text is confusing.

properties: the returned record for the node contains the basic node element with a list of properties but no xsi:type specific extensions

I think what that intended to mean was, treat the node as a basic Node element and do not include any of the elements from other types, e.g. accepts, provides or busy from DataNode, target from LinkNode or nodes from a ContainerNode.

[Zarquan]

I think what that means is that for each of these examples -

A link node:

<node uri="vos://link-001" type="vos:LinkNode">
    <properties>
        ....
    </properties>
    <target>....</target>
</node>

A data node:

<node uri="vos://data-002" type="vos:DataNode">
    <properties>
        ....
    </properties>
    <accepts>
        ....
    </accepts>
    <provides>
        ....
    </provides>
</node>

A container node:

<node uri="vos://container-002" type="vos:ContainerNode">
    <properties>
        ....
    </properties>
    <accepts>
        ....
    </accepts>
    <provides>
        ....
    </provides>
    <nodes>
        ....
    </nodes>
</node>

Would all be just represented as simple Nodes with properties :

A link node:

<node uri="vos://link-001" type="vos:LinkNode">
    <properties>
        ....
    </properties>
</node>

A data node:

<node uri="vos://data-002" type="vos:DataNode">
    <properties>
        ....
    </properties>
</node>

A container node:

<node uri="vos://container-002" type="vos:ContainerNode">
    <properties>
        ....
    </properties>
</node>

[Zarquan]

However, it doesn't say what the type attribute should be set to. Because although the DataNode, accepts, provides and busy are all optional, the LinkNode target and ContainerNode nodes list are not optional (they can be empty list, but they have to be there).

So although this is OK:

<node uri="vos://data-002" type="vos:DataNode">
    <properties>
        ....
    </properties>
</node>

According to the XML schema, these are not valid:

<node uri="vos://link-001" type="vos:LinkNode">
    <properties>
        ....
    </properties>
    <!-- missing target URI -->
</node>

<node uri="vos://container-002" type="vos:ContainerNode">
    <properties>
        ....
    </properties>
    <!-- missing nodes list -->
</node>

The only way to solve that would be to return everything as Node.

A link node:

<node uri="vos://link-001" type="vos:Node">
    <properties>
        ....
    </properties>
</node>

A data node:

<node uri="vos://data-002" type="vos:Node">
    <properties>
        ....
    </properties>
</node>

A container node:

<node uri="vos://container-002" type="vos:Node">
    <properties>
        ....
    </properties>
</node>

Which for me looses a bit too much information. I would expect a client to still want to know what type of thing each node was.

[Zarquan]

I'm assuming that the goal of the detail filter is to limit the size of the response body, that could be very big, especially for container nodes having many children, and/or also to avoid retrieving too much unnecessary information from the databases.

I think that was the original reason for proposing this yes, but I wonder if this is worth all the effort expended on tweaking the specification, schema, and software needed to implement it.

[Zarquan]

One way to resolve the schema issue would be to make LinkNode target and ContainerNode nodes optional, but we would have to be clear about what that means.

If a getNode response contained a LinkNode element with no target:

<node uri="vos://link-001" type="vos:LinkNode">
    <properties>
        ....
    </properties>
    <!-- missing target URI -->
</node>

That is because the target was filtered by the detail level, as opposed to a LinkNode element with an empty target:

<node uri="vos://link-001" type="vos:LinkNode">
    <properties>
        ....
    </properties>
    <target/>
</node>

which represents a link with a null target.

Equally, a ContainerNode element with no nodes list is because the list was filtered out by the detail level:

<node uri="vos://container-002" type="vos:ContainerNode">
    <properties>
        ....
    </properties>
    <!-- missing nodes list -->
</node>

compared to a ContainerNode with an empty list:

<node uri="vos://container-002" type="vos:ContainerNode">
    <properties>
        ....
    </properties>
    <nodes/>
</node>

which represents a ContainerNode with no children.

[zonia3000]

I don't think we should remove the type attribute. I think the text is confusing. [...] I think what that intended to mean was, treat the node as a basic Node element and do not include any of the elements from other types, e.g. accepts, provides or busy from DataNode, target from LinkNode or nodes from a ContainerNode.

Thanks for the clarification and the example. I had misinterpreted that point.

[zonia3000]

The only way to solve that would be to return everything as Node. [...] Which for me looses a bit too much information. I would expect a client to still want to know what type of thing each node was.

I agree. Node type is a very important information.

One way to resolve the schema issue would be to make LinkNode target and ContainerNode nodes optional, but we would have to be clear about what that means.

I'm fine with this approach, but this requires a new major version of the specification. I think that we can proceed with a first pull request including the minor changes that you proposed in the first comment and then propose the other changes.

[zonia3000]

I think that was the original reason for proposing this yes, but I wonder if this is worth all the effort expended on tweaking the specification, schema, and software needed to implement it.

It seems that, considering all the possible cases, it is quite complex to describe and to implement. Moreover the parameter is optional, so it seems a lot of work for something that not all the implementations will support. Maybe we could deprecate at least the properties value if nobody is using it and keep only max and min.