|| This schema is... || ||
| under review | !grnchk.png! |
| complete | |

h3. Schema

|| Procedure \\ || MMI Field name || CSpace field name || DB table.field || NXQL table:field || Link to search? \\ ||
| Cataloging \\ | *Label* | Brief Description (*RF*) | collectionobjects_common_briefdescriptions.item .pos | collectionobjects_common:briefDescriptions | N \\ |
| | *Description* \\ | Distinguishing Features | collectionobjects_common.distinguishingfeatures | collectionobjects_common:distinguishingFeatures | N \\ |
| | *Content remarks* \\ | Inscription Content (*RF*) | collectionobjects_mmi_mmiinscriptioncontents.item .pos | collectionobjects_mmi:mmiInscriptionContents | N \\ |
| | *Accession number* \\ | Object Number | collectionobjects_common.objectnumber | collectionobjects_common:objectNumber | N \\ |
| | *Collection category* \\ | Responsible Department (*RF*)(*CL*) | collectionobjects_common_responsibledepartments.item | collectionobjects_common:responsibleDepartments | Y \\ |
| | *Artifact class/ Work type* *(Categories)* | Artifact class/ Work type (*RG*) \\ | _shares the table name _ \\
artifactclassworktypegroup | _shares the table name_ \\
collectionobjects_mmi \\ | |
| | \\ | Artifact Class |   .artifactclass \\ |   :artifactClassWorkTypeList/\*/artifactClass | Y \\ |
| | \\ | Work Type |   .worktype |   :artifactClassWorkTypeList/*/workType | Y \\ |
| | *Dimensions* \\ | Dimensions (component) |   | _shares the table name_ \\
collectionobjects_common \\ | N \\ |
| | | Dimension summary \\ | measuredpartgroup.dimensionsummary \\ |   :measuredPartGroupList/\*/dimensionSummary \\ | |
| | | Measured part | measuredpartgroup.measuredpart \\ |   :measuredPartGroupList/\*/measuredPart \\ | |
| | | Value date (*date*) | dimensionsubgroup.valuedate \\ |   :measuredPartGroupList/\*/dimensionSubGroupList/\*/valueDate | |
| | | Measurement unit | dimensionsubgroup.measurementunit \\ |   :measuredPartGroupList/\*/dimensionSubGroupList/\*/measurementUnit \\ | |
| | | Value (*integer*) | dimensionsubgroup.value \\ |   :measuredPartGroupList/\*/dimensionSubGroupList/\*/value | |
| | | Value qualifier (*integer*) | dimensionsubgroup.valuequalifier \\ |   :measuredPartGroupList/\*/dimensionSubGroupList/\*/valueQualifier | |
| | *Extent* \\ | Number of Objects (*integer*) | collectionobjects_common.numberofobjects | collectionobjects_common:numberOfObjects | N \\ |
| | Attribute: *Format* \\ | Physical Description | collectionobjects_common.physicaldescription | collectionobjects_common:physicalDescription | N \\ |
| | Attribute: *Technique* \\ | Technique (*RF*) | collectionobjects_mmi_mmitechniques.item .pos | collectionobjects_mmi:mmiTechniques | N \\ |
| | Attribute: *Dimensions* \\ | Dimensions (component) | _same as before?_ | | N \\ |
| | Attribute: *Display date* \\ | Production Date (component) | _shares the table name_ \\
structureddategroup | _shares the table name_ \\
collectionobjects_common | N \\ |
| | | Display date | .datedisplaydate |   :objectProductionDateGroupList/*/dateDisplayDate | |
| | | Association (*URN*) | .dateassociation |   :objectProductionDateGroupList/*/dateAssociation | |
| | | dateEarliestScalarValue (*date*) | .dateearliestscalarvalue |   :objectProductionDateGroupList/\*/dateEarliestScalarValue | |
| | | dateLatestScalarValue (*date*) | .datelatestscalarvalue |   :objectProductionDateGroupList/\*/dateLatestScalarValue | |
| | Attribute: *Materials* \\ | Material (*RF*) (*CL*) | collectionobjects_mmi_mmimaterials.item .pos | collectionobjects_mmi:mmiMaterials | N \\ |
| | Attribute: *Components* \\ | Object component name (*RG*) | _shares the table name_ \\
objectcomponentgroup \\ | _shares the table name_ \\
collectionobjects_common \\ | N \\ |
| | | Object component name |   .objectcomponentname  \\ |   :objectComponentGroupList/*/objectComponentName \\ | |
| | | Object component information |   .objectcomponentinformation \\ |   :objectComponentGroupList/\*/objectComponentInformation \\ | |
| | Authority: *Associated Entities* \\ | Associated organization (*RG*) | _shares the table name_ \\
assocorganizationgroup \\ | _shares the table name_ \\
collectionobjects_common \\ | Y \\ |
| | | Associated organization (*URN*) |   .assocorganization \\ |   :assocOrganizationGroupList/\*/assocOrganization \\ | |
| | | Associated organization type (*CL*) \\ |   .assocorganizationtype \\ |   :assocOrganizationGroupList/\*/assocOrganizationType \\ | |
| | | Associated organization note \\ |   .assocorganizationnote \\ |   :assocOrganizationGroupList/\*/assocOrganizationNote \\ | |
| | Authority: *Associated Productions* \\ | Associated production (*RG*) | _shares the table name_ \\
assocproductiongroup \\ | _shares the table name_ \\
collectionobjects_mmi \\ | Y \\ |
| | | Associated production (*URN*) \\ |   .assocproduction  \\ |   :assocProductionList/\*/assocProduction \\ | |
| | | Associated production type (*CL*) \\ |   .assocproductiontype \\ |   :assocProductionList/\*/assocProductionType \\ | |
| | | Associated production note \\ |   .assocproductionnote  \\ |   :assocProductionList/\*/assocProductionNote \\ | |
| | Authority: *Associated Publications* \\ | Associated publication (*RG*) | _shares the table name_ \\
assocpublicationgroup \\ | _shares the table name_ \\
collectionobjects_mmi \\ | Y \\ |
| | | Associated publication (*URN*) \\ |   .assocpublication \\ |   :assocPublicationList/\*/assocPublication \\ | |
| | | Associated publication type (*CL*) \\ |   .assocpublicationtype \\ |   :assocPublicationList/\*/assocPublicationType \\ | |
| | | Associated publication note \\ |   .assocpublicationnote \\ |   :assocPublicationList/\*/assocPublicationNote \\ | |
| | Authority: *Production Entities* \\ | Production organization (*RG*) | _shares the table name_ \\
objectproductionorganizationgroup \\ | _shares the table name_ \\
collectionobjects_common \\ | Y \\ |
| | | Production organization (*URN*) \\ |   .objectproductionorganization \\ |   :objectProductionOrganizationGroupList/\*/objectProductionOrganization \\ | |
| | | Production role (*CL*) \\ |   .objectproductionorganizationrole \\ |   :objectProductionOrganizationGroupList/\*/objectProductionOrganizationRole \\ | |
| | Authority: *Content Entities* \\ | Content organization (*RG*) | _shares the table name_ \\
contententitygroup \\ | _shares the table name_ \\
collectionobjects_mmi \\ | Y \\ |
| | | Content entity (*URN*) \\ |   .contententity \\ |   :contentEntityList/\*/contentEntity \\ | |
| | | Content entity type (*CL*) \\ |   .contententitytype \\ |   :contentEntityList/*/contentEntityType \\ | |
| | Authority: *Groups* (collection subsets) \\ | _need to add_ | | | Y \\ |
| Acquisition \\ | *Credit line* \\ | Credit Line | acquisitions_common.creditline | | N \\ |
| Location \\ | *Current location* \\ | Current location (*URN*) | movements_common.currentlocation | movements_common:currentLocation | N \\ |

The fields marked (*RF*) describe the NXQL format that will search through all elements of that repeatable field. To limit the search to the primary value then append {{/0}} to the field name, e.g. {{collectionobjects_mmi:mmiTechniques/0}}

Likewise, fields marked (*RG*) describe repeatable groups of fields. The underlying fields are shown with a wildcard in the field path to indicate that such an search term is required for the NXQL query string to return without a syntax error. The wildcard can be replaced with a {{0}} to indicate the primary value of that field should be only be searched upon.

The fields marked (*CL*) describe a field that is a controlled list (HTML {{select}} element). The returned value is a non-spaced string. Please see [Controlled List mapping|#ControlledListmapping] for a mapping of controlled list strings to displayed values.

(*date*) indicates a PostgreSQL "timestamp without time zone" type field and requires a DATE or TIMESTAMP literal in the NXQL notation. For instance, in non-URL encoded form:
{{collectionobjects_common:measuredPartGroupList/\*/dimensionSubGroupList/\*/valueDate <= DATE &nbsp;'2012-01-09'}} _or_
{{collectionobjects_common:measuredPartGroupList/\*/dimensionSubGroupList/\*/valueDate <= TIMESTAMP &nbsp;'2012-01-09T00:00:00'}}
See also [Common Services REST API documentation|collectionspace:Common Services REST API documentation#CommonServicesRESTAPIdocumentation-AdvancedSearchforobject%2Fprocedure%2Frecordinstances]&nbsp;and&nbsp;[NXQL documentation|http://doc.nuxeo.com/display/NXDOC/NXQL].

(*integer*) indicates a field integer type.

(*URN*) indicates a field that uses a refname structure to indicate value and metadata for that field. See also [refname|http://wiki.collectionspace.org/display/collectionspace/RefName].

h3. Searching through a range of values using text based fields
{note}The following is not the preferred form. Please see searching scalar values below.{note}

NXQL supports the {{BETWEEN}} operator to search through a range of numerical or text values.

An example
{code}
http://cspacetest.collectionspace.org:8180/cspace-services/collectionobjects?as=collectionobjects_common/physicalDescription BETWEEN 'g' AND 'h'
{code}

Another example for a simple range of {{displayDate}} values for 1950's
{code}
http://cspacetest.collectionspace.org:8180/cspace-services/collectionobjects?as=collectionobjects_common/objectProductionDateGroupList/*/dateDisplayDate BETWEEN '%1950%' AND '%1959%'
{code}

{note}
{{BETWEEN}} doesn't give expected results when the {{displayDate}} value is in any format other than strictly numerical. Values like "stamped 1934", "Jan 1973, Feb 1973", "ca. 1922", "Feb-May, Dec 1975" and "February, 1934" are not found when bounding the {{BETWEEN}} operator between two numerical values.
{note}

h3. Searching through a range of scalar date values for a structured date field

The structured date field type is a group of related fields which give greater definition of a date, range and certainty.

Searching through a range of dates for a structured date requires using the {{dateEarliestScalarValue}} and {{dateLatestScalarValue}} scalar fields of the structured date group.
These fields contain a postgres {{TIMESTAMP}} value in the form of {{YYYY-MM-DDThh:mm:ss}} where {{T}} is an indicator of a timestamp, e.g. {{2012-03-27T11:23:00}}. the API will also accept queries using a DATE literal and internally convert to/from TIMESTAMP.

All scalar dates are saved in postgres with a lower bound time stamp, {{dateEarliestScalarValue}}, of {{T00:00:00}} and a higher bound time stamp, {{dateLatestScalarValue}}, of {{T23:59:59}}.
An important fact about scalar dates in this context is that CollectionSpace modifies the saved postgres timestamp value by the server's timezone. This means the postgres scalar values are effectively 5 hours behind (NYC being UTC \-5, ignoring DST) in CollectionSpace. This impacts the way in which DATE or TIMESTAMP ranges are calculated using the REST API.

For example, say there is a search for all dates from 1954.
Using the {{DATE}} literal, rather than search from a lower bound of {{1954-01-01}} and a higher bound of {{1954-12-31}}, there would be a recalculated search from {{1953-12-31}} up through {{1955-01-01}}.
Using the {{TIMESTAMP}} literal, the range search would take into consideration the server timezone (non DST value) and recalculate based on that value. The updated query would have a range from {{1953-12-31T19:00:00}} up through {{1954-12-31:19:00:00}}.

h5. Example API call

*DATE*
{code}
non url-encoded
http://cspacetest.collectionspace.org:8180/cspace-services/collectionobjects?as=collectionobjects_common:objectProductionDateGroupList/0/dateEarliestScalarValue >= DATE "1953-12-31" AND collectionobjects_common:objectProductionDateGroupList/0/dateLatestScalarValue <= DATE "1955-01-01"
{code}

{code}
encoded
http://cspacetest.collectionspace.org:8180/cspace-services/collectionobjects?as=collectionobjects_common%3aobjectProductionDateGroupList%2F0%2FdateEarliestScalarValue++>%3D++DATE++%221955-01-01%22++AND++collectionobjects_common%3aobjectProductionDateGroupList%2F0%2FdateLatestScalarValue++<%3D++DATE++%221955-01-01%22
{code}

*TIMESTAMP*
{code}
non url-encoded
http://cspacetest.collectionspace.org:8180/cspace-services/collectionobjects?as=collectionobjects_common:objectProductionDateGroupList/0/dateEarliestScalarValue >= TIMESTAMP "1953-12-31T19:00:00" AND collectionobjects_common:objectProductionDateGroupList/0/dateLatestScalarValue <= TIMESTAMP "1954-12-31T19:00:00"
{code}

{code}
url-encoded
http://cspacetest.collectionspace.org:8180/cspace-services/collectionobjects?as=collectionobjects_common%3aobjectProductionDateGroupList%2F0%2FdateEarliestScalarValue++%3E%3D++TIMESTAMP++%221953-12-31T19:00:00%22++AND++collectionobjects_common%3aobjectProductionDateGroupList%2F0%2FdateLatestScalarValue++%3C%3D++TIMESTAMP++%221954-12-31T19:00:00%22
{code}



h3. Other parameters

|| Description || NXQL string || DB string || API query string \\ || Required ||
| is record status completed and publishable? | collectionobjects_common.recordStatus | {{collectionobjects_common.recordstatus = "completedpublish"}} | {{AND collectionobjects_common:recordStatus = 'completedpublish'}} \\ | Y |
| is object record deleted? | _[CSpace specific flag|collectionspace:Common Services REST API documentation#CommonServicesRESTAPIdocumentation-Listresults%2Cfiltering%2Cpaginationcontrols%2Csortingandsearch]_ | {{misc.lifestylestate <> 'deleted'}} | {{&wf_deleted=false}} \\ | Y |
| sort by | _[CSpace specific flag|collectionspace:Common Services REST API documentation#CommonServicesRESTAPIdocumentation-Listresults%2Cfiltering%2Cpaginationcontrols%2Csortingandsearch]_ | {{ORDER BY collectionspace_core.updatedat}} | {{&sortBy=collectionspace_core:updatedAt}} \\ | N |
| show only objects from a specific tenant | _implied_ | {{collectionspace_core.tenantid=42}} | _implied_ | Y |

h5. Sample URL query

URL encoded query string using the above parameters:
\\
{code}
http://cspacetest.collectionspace.org:8180/cspace-services/collectionobjects?as=collectionobjects_common%3AdistinguishingFeatures++ILIKE++%27Foo%25%27++AND++collectionobjects_common%3ArecordStatus+%3d+%27completedpublish%27&sortBy=collectionspace_core%3AupdatedAt&wf_deleted=false
{code}

Non-encoded URL
{code:sql}
http://cspacetest.collectionspace.org:8180/cspace-services/collectionobjects
?as=collectionobjects_common:distinguishingFeatures ILIKE 'Foo%'
AND collectionobjects_common:recordStatus = 'completedpublish'
&sortBy=collectionspace_core:updatedAt
&wf_deleted=false
{code}



h3. Get referenced authority records

Append {{authorityrefs}} to the API URL for a collectionobject record to get a list of referenced authority records': {{sourceField}}, {{itemDisplayName}} and {{refName}} (in {{short ID}} format).

An example API call for {{authorityrefs}} for a given collectionobject record
{code}
http://cspacetest.collectionspace.org:8180/cspace-services/collectionobjects/a7fdba4a-ec23-472c-9c45-47249aa3242d/authorityrefs
{code}


h3. REST API query payload columns returned

h3. Finding related procedural records using the Relationship service

The [relations service|collectionspace:Relationship Service RESTful APIs] provides the mechanism to find related procedural records of a given type. The syntax for this service API uses _subject_ and _object_ query parameters to denote the relationship direction.

The full list of query terms:
{{sbj}} = used to specify the subject's CSID
{{sbjType}} = used to specify the type of the subject

{{obj}} = used to specify the object's CSID
{{objType}} = used to specify the type of the object


With a specific {{csid}} and a general {{objType}} the API call would be

{code}
http://cspacetest.collectionspace.org:8180/cspace-services/relations?sbj={{csid}}&objType={{docType}}
{code}


Where the document type, {{docType}}, value is could be one of the following:
* Media - {{MediaTenant42}}
* Movement - {{Movement}}
* Collection object - {{CollectionObjectTenant42}}

{tip} Document types with the suffix {{Tenant42}} represent record types with a custom schema extension. {tip}

Filtering the search results requires the use of the Relationship service in order to access a related record's field value.

h5. Filter by *objects on exhibit*

The Movement service manages information around the movement of a CollectionObject - an instance of location change. This includes location changes resulting from movements between storage locations, such as between rooms or shelves.
There are a few location areas that represent exhibition areas of MMI. These locations include any {{currentLocation}} authority URN value that contains *{{BTS}}*, *{{CHX}}* or *{{AMP}}*.

{tip}{{BTS}} has multiple values and any will match this filter, e.g. {{BTS:3:8:4}}.\\ {{AMP}} will not match any current records but has the potential to in the future.{tip}

To find the current location of a CollectionObject, the following Relation API call can be made
{code}
http://cspacetest.collectionspace.org:8180/cspace-services/relations?sbj={{csid}}&objType=Movement
{code}

\* It's possible that there will not be a related movement record returned if in case the physical object cannot be found! This should be a rare occurrence in any collection.


h5. Filter by *records with images*

This is identical to how thumbnails are retrieved for CollectionObjects.
{code}
http://cspacetest.collectionspace.org:8180/cspace-services/relations?sbj={{csid}}&objType=MediaTenant42
{code}

Only media records with a {{mediaStatus}} value of {{display}} will be shown for this filter.



h3. Controlled List mapping

h5. Collection category

|| Controlled list string || Display string ||
| {{notyetassigned}} | Not yet assigned |
| {{distribution}} | Distribution |
| {{exhibition}} | Exhibition |
| {{industryasawhole}} | Industry (as a whole) |
| {{marketing}} | Marketing |
| {{merchandising}} | Merchandising |
| {{production}} | Production |
| {{reception}} | Reception |
| {{worksofart}} | Works of art |

h5. Material

|| Controlled list string || Display string || Controlled list string || Display string ||
| {{acetatefilm}} | Acetatefilm | {{metal}} | Metal |
| {{cellophane}} | cellophane | {{neon}} | Neon |
| {{cellulosenitratefilm}} | Cellulose nitrate film | {{paper}} | Paper |
| {{cement}} | Cement | {{photographicnegative}} | Photographic negative |
| {{ceramic}} | Ceramic | {{photographicpaper}} | Photographic paper |
| {{composition}} | Composition | {{photographicpapermountedontextile}} | Photographic paper mounted on textile |
| {{cork}} | Cork | {{plaster}} | Plaster |
| {{crystal}} | Crystal | {{plastic}} | Plastic |
| {{engineeredwood}} | Engineered wood | {{polystyrene}} | Polystyrene |
| {{fiberglass}} | Fiberglass | {{polyurethane}} | Polyurethane |
| {{foam}} | Foam | {{resin}} | Resin |
| {{fur}} | Fur | {{rock}} | Rock |
| {{glass}} | Glass | {{rubber}} | Rubber |
| {{glycerin}} | Glycerin | {{soap}} | Soap |
| {{hair}} | Hair | {{textile}} | Textile |
| {{latex}} | Latex | {{vinyl}} | Vinyl |
| {{leather}} | Leather | {{wax}} | Wax |
| | | {{wood}} | Wood |

h5. Associated organization type / Production role

|| Controlled list string || Display string ||
| {{creator}} | _Authority_&nbsp;Creator |
| {{designer}} | _Authority_&nbsp;Designer |
| {{distributor}} | A{_}uthority_ Distributor |
| {{licensor}} | _Authority_ Licensor |
| {{illustrator}} | _Authority_ Illustrator |
| {{manufacturer}} | _Authority_ Manufacturer |
| {{producer}} | _Authority_ Producer |
| {{publisher}} | _Authority_ Publisher |
| {{owner}} | _Authority_ Owner |
| {{authorwriter}} | _Authority_ author/writer |
| {{exhibitor}} | _Authority_ exhibitor |
| {{performer}} | _Authority_ performer |
| {{signitor}} | _Authority_ signitor |

h5. Content entity type

|| Controlled list string || Display string ||
| {{depicts}} | Depicts _Authority_ |
| {{references}} | References _Authority_ |
| {{seealso}} | See also _Authority_ |

h5. Associated production type

|| Controlled list string || Display string ||
| {{depicts}} | Depicts _Authority_ |
| {{references}} | References _Authority&nbsp;_ |
| {{isfrom}} | Is from _Authority_ |

h5. Associated publication type

|| Controlled list string || Display string ||
| {{issueof}} | _The Object_ Is an issue of _The Authority_ |
| {{references}} | _The Object&nbsp;_References \_The Authority_ |


h3. Related links

[NXQL advanced search |collectionspace:NXQL and CS Services Advanced Search]
CollecitonObject [RESTful API|collectionspace:CollectionObject Service RESTful APIs - Release v0.5]
Common services [RESTful API|collectionspace:Common Services REST API documentation]
Media service [RESTful API|collectionspace:Media Service RESTful API]
Relation service [RESTful API|collectionspace:Relationship Service RESTful APIs]