[#CMIS-106] Clarify types-children and types-descendants - OASIS Technical Committees Issue Tracker

OASIS Content Management Interoperability Services (CMIS) TC

Clarify types-children and types-descendants

Created: 04/Mar/09 05:19 PM Updated: 11/Jan/10 06:37 PM

Component/s:

REST/AtomPub Binding

Affects Version/s:

Draft 0.50

Fix Version/s:

Draft 0.62

Proposal:

« Hide

Make getTypeDefinition/getTypeChildren/getTypeDescendants consistent with getProperties/getChildren/getDescendants (in behavior and structure - and note more consistent naming). Specifically:

    * getTypeDefinition should return an Entry describing a single type
    * getTypeChildren should return the direct children of a type (or the root type) as a Feed. The resource should identify the type whose children will be fetched. Optional (query) args include includePropertyDefinintions, maxItems, skipCount.
    * getTypeDescendants should return the descendants of a type (or the root type) as a feed with nesting (child types will be contained in their parent's atom:entry) up to the specified depth. The resource should identify the type whose descendants will be fetched. Optional (query) args include includePropertyDefinintions, and depth.

Description

« Hide

What is the difference between TypesChildren and TypesDescendants? The description of both says they are feeds containing all the types in the repository. If both resources contain all types, then what is the difference?

   1. I suspect that either TypesDescendants is redundant and unnecessary, or
   2. that the descriptions are wrong, and they should be returning feeds of types that are children/descendants of a given type.
   3. Note that there is no "typeDescendants" description in the repository services section (REST)
   4. Also note the description of getTypes in Part 1 has a note that "CMIS will return [the types] as a flat list". It also says that if a typeId parameter is provided, then it will "only return that type and its descendants".
       a. This makes it sound like there is no such thing as TypesChildren, and should only be TypesDescendants? And it is really not exactly descendants, since it also includes the "root" type (identified by the parameter). Gack.

All

Comments

Change History

Sort Order:

[ Permalink | « Hide ]

Florent Guillaume added a comment - 04/Mar/09 05:24 PM

TypesDescendants is necessary to model the answer to the getTypes method with a typeId parameter.

But I agree that the description of TypesDescendants in part II are probably a copy/paste error, the TypesDescendants feed should be described differently.

[ Permalink | « Hide ]

Ryan McVeigh added a comment - 04/Mar/09 06:07 PM

Agreed Florent. I added a couple of other points above after I filed this.

[ Permalink | « Hide ]

Florent Guillaume added a comment - 04/Mar/09 06:34 PM

Ryan, my understanding is that the spec describes:

- workspace collection types-children points to Feed (ex: $SERVER/atom/types)
- inside an Entry for an Object, link cmis-type points to Entry (ex: $SERVER/atom/type/${typeid})

There needs to be also a Feed to model getTypes with typeId (ex: $SERVER/atom/types/${typeid}) but I'm not sure what would give us this URI. Maybe a link cmis-types-descendants returned inside an Entry for a Type?

[ Permalink | « Hide ]

Ryan McVeigh added a comment - 11/Mar/09 06:28 PM

I'm not sure how to add a proposal to this issue - it isn't an option - perhaps because there are already comments? Anyway here's my proposal:

Proposal: Make getTypeDefinition/getTypeChildren/getTypeDescendants consistent with getProperties/getChildren/getDescendants (in behavior and structure - and note more consistent naming). Specifically:

    * getTypeDefinition should return an Entry describing a single type
    * getTypeChildren should return the direct children of a type (or the root type) as a Feed. The resource should identify the type whose children will be fetched. Optional (query) args include includePropertyDefinintions, maxItems, skipCount.
    * getTypeDescendants should return the descendants of a type (or the root type) as a feed with nesting (child types will be contained in their parent's atom:entry) up to the specified depth. The resource should identify the type whose descendants will be fetched. Optional (query) args include includePropertyDefinintions, and depth.

--

This one is causing us some grief in prototyping and I would update its priority to Critical.

[ Permalink | « Hide ]

Al Brown added a comment - 14/Apr/09 01:26 PM

Is this still accurate against .6?

[ Permalink | « Hide ]

Ryan McVeigh added a comment - 21/Apr/09 04:25 PM

Yes this is still accurate. There is no typesChildren service defined in Part I, but Part II defines a collection for this purpose. Part II adds the distinct concept of types children which isn't specified in Part I. Should we have a single service to satisfy the types-children and types-desendants behavior or should we define two services?

Proposal: Rename getTypes to getTypeChildren. This service should not return the type requested by the typeId, but only return the children as requested. Introduce a getTypeDescendants service that behaves similarly but returns the full descendants list. This mirrors the similar services as defined for folders.

[ Permalink | « Hide ]

Al Brown added a comment - 05/Jan/10 12:34 AM

JIRA Cleanup